The following tutorial will guide you to build a sample Player vs Player game contract. We will apply the knowledge we acquired eariler and use the tic-tac-toe game to demonstrate.
For this game, we are using a standard 3x3 tic-tac-toe board. Players are divided into two roles: host and challenger. The host always makes the first move. Each pair of players can ONLY have up to two games at the same time, one where the first player becomes the host and the other one where the second player becomes the host.
Instead of using o
and x
as in the traditional tic-tac-toe game, we use 1
to denote movement by host, 2
to denote movement by challenger, and 0
to denote empty cell. Furthermore, we will use one dimensional array to store the board. Hence:
| (0,0) | (1,0) | (2,0) |
(0,0) | - | o | x |
(0,1) | - | x | - |
(0,2) | x | o | o |
Assuming x is host, the above board is equal to [0, 2, 1, 0, 1, 0, 1, 2, 2]
A user will have the following actions to interact with this contract:
create: create a new game
restart: restart an existing game, host or challenger is allowed to do this
close: close an existing game, which frees up the storage used to store the game, only host is allowed to do this
move: make a movement
For the following guide, we are going to push the contract to an account called tic.tac.toe
.
cleos create account eosio tic.tac.toe YOUR_PUBLIC_KEY
Ensure that you have your wallet unlocked and the creator's private active key in the wallet imported, otherwise the above command will fail.
[[info | Wallet Unlocking]] | For instructions on wallet unlocking and keys importing, see section Create Development Wallet.
In the above step, if you see YOUR_PUBLIC_KEY
instead of the public key value, you can either go back to section 1.4 Create Development Wallet and persist the value or replace YOUR_PUBLIC_KEY
with the public key value manually.
We are going to create two files here:
tic.tac.toe.hpp => header file where the structure of the contract is defined
tic.tac.toe.cpp => main part of the contract where the action handler is defined
Let's first start with the header file and define the structure of the contract. Open tic.tac.toe.hpp and start with the following boilerplate:
// Import necessary library#include <eosio/eosio.hpp>// Generic eosio library, i.e. print, type, math, etcusing namespace eosio;class[[eosio::contract("tic.tac.toe")]] tic_tac_toe : public contract{public:using contract::contract;tic_tac_toe(name receiver, name code, datastream<const char *> ds) : contract(receiver, code, ds) {}};
For this contract, we will need to have a table that stores a list of games. Let's define it:
...class [[eosio::contract("tic.tac.toe")]] tic_tac_toe : public contract {public:...typedef eosio::multi_index<"games"_n, game> games;};
First template parameter defines the name of the table
Second template parameter defines the structure that it stores (will be defined in the next section)
Let's define the structure for the game. Please ensure that this struct definition appears before the table definition in the code.
...class tic_tac_toe : public eosio::contract {public:...static constexpr name none = "none"_n;static constexpr name draw = "draw"_n;struct [[eosio::table]] game{static constexpr uint16_t board_width = 3;static constexpr uint16_t board_height = board_width;game() : board(board_width * board_height, 0){}name challenger;name host;name turn; // = account name of host/ challengername winner = none; // = none/ draw/ name of host/ name of challengerstd::vector<uint8_t> board;// Initialize board with empty cellvoid initialize_board(){board.assign(board_width * board_height, 0);}// Reset gamevoid reset_game(){initialize_board();turn = host;winner = "none"_n;}auto primary_key() const { return challenger.value; }EOSLIB_SERIALIZE( game, (challenger)(host)(turn)(winner)(board))};};
The primary_key method is required by the above table definition for games. That is how the table knows what field is the lookup key for the table.
To create the game, we need host account name and challenger's account name.
[[eosio::action]]void create(const name &challenger, name &host);
To restart the game, we need host account name and challenger's account name to identify the game. Furthermore, we need to specify who wants to restart the game, so we can verify the correct signature is provided.
[[eosio::action]]void restart(const name &challenger, const name &host, const name &by);
To close the game, we need host account name and challenger's account name to identify the game.
[[eosio::action]]void close(const name &challenger, const name &host);
To make a move, we need host account name and challenger's account name to identify the game. Furthermore, we need to specify who makes this move and the movement he is making.
[[eosio::action]]void move(const name &challenger, const name &host, const name &by, const uint16_t &row, const uint16_t &column);
To recap, we should have declared the following action handlers which will be defined in tic.tac.toe.cpp later.
// Import necessary library#include <eosio/eosio.hpp>// Generic eosio library, i.e. print, type, math, etcusing namespace eosio;class[[eosio::contract("tic.tac.toe")]] tic_tac_toe : public contract{public:using contract::contract;tic_tac_toe(name receiver, name code, datastream<const char *> ds) : contract(receiver, code, ds) {}static constexpr name none = "none"_n;static constexpr name draw = "draw"_n;struct [[eosio::table]] game{static constexpr uint16_t board_width = 3;static constexpr uint16_t board_height = board_width;game() : board(board_width * board_height, 0){}name challenger;name host;name turn; // = account name of host/ challengername winner = none; // = none/ draw/ name of host/ name of challengerstd::vector<uint8_t> board;// Initialize board with empty cellvoid initialize_board(){board.assign(board_width * board_height, 0);}// Reset gamevoid reset_game(){initialize_board();turn = host;winner = "none"_n;}auto primary_key() const { return challenger.value; }EOSLIB_SERIALIZE( game, (challenger)(host)(turn)(winner)(board))};typedef eosio::multi_index<"games"_n, game> games;[[eosio::action]]void create(const name &challenger, name &host);[[eosio::action]]void restart(const name &challenger, const name &host, const name &by);[[eosio::action]]void close(const name &challenger, const name &host);[[eosio::action]]void move(const name &challenger, const name &host, const name &by, const uint16_t &row, const uint16_t &column);};
Let's open tic.tac.toe.cpp and set up the boilerplate:
#include "tic.tac.toe.hpp"
We want tic tac toe
contract to only react to actions sent to the tic.tac.toe
account and react differently according to the type of the action. The actions that we declared previously are create, move, restart, and close. Let's define the individual action handlers in the next section.
For the create action handler, we want to:
Ensure that the action has the signature from the host
Ensure that the challenger and host are not the same player
Ensure that there is no existing game
Store the newly created game to the db
void tic_tac_toe::create(const name &challenger, name &host) {require_auth(host);check(challenger != host, "challenger shouldn't be the same as host");// Check if game already existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr == existing_host_games.end(), "game already exists");existing_host_games.emplace(host, [&](auto &g) {g.challenger = challenger;g.host = host;g.turn = host;});}
For the move action handler, we want to:
Ensure that the action has the signature from the host/ challenger
Ensure that the game exists
Ensure that the game is not finished yet
Ensure that the move action is done by host or challenger
Ensure that this is the right user's turn
Verify movement is valid
Update board with the new move
Change the move_turn to the other player
Determine if there is a winner
Store the updated game to the db
void tic_tac_toe::move(const name &challenger, const name &host, const name &by, const uint16_t &row, const uint16_t &column){check(has_auth(by), "the next move should be made by " + by.to_string());// Check if game existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr != existing_host_games.end(), "game doesn't exists");// Check if this game hasn't ended yetcheck(itr->winner == tic_tac_toe::none, "the game has ended!");// Check if this game belongs to the action sendercheck(by == itr->host || by == itr->challenger, "this is not your game!");// Check if this is the action sender's turncheck(by == itr->turn, "it's not your turn yet!");// Check if user makes a valid movementcheck(is_valid_movement(row, column, itr->board), "not a valid movement!");// Fill the cell, 1 for host, 2 for challenger//TODO could use constant for 1 and 2 as wellconst uint8_t cell_value = itr->turn == itr->host ? 1 : 2;const auto turn = itr->turn == itr->host ? itr->challenger : itr->host;existing_host_games.modify(itr, itr->host, [&](auto &g) {g.board[row * tic_tac_toe::game::board_width + column] = cell_value;g.turn = turn;g.winner = get_winner(g);});}
Valid movement is defined as movement done inside the board on an empty cell:
bool is_empty_cell(const uint8_t &cell){return cell == 0;}bool is_valid_movement(const uint16_t &row, const uint16_t &column, const std::vector<uint8_t> &board){uint32_t movement_location = row * tic_tac_toe::game::board_width + column;bool is_valid = movement_location < board.size() && is_empty_cell(board[movement_location]);return is_valid;}
Winner is defined as the first player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row.
...name get_winner(const tic_tac_toe::game ¤t_game){auto &board = current_game.board;bool is_board_full = true;// Use bitwise AND operator to determine the consecutive values of each column, row and diagonal// Since 3 == 0b11, 2 == 0b10, 1 = 0b01, 0 = 0b00std::vector<uint32_t> consecutive_column(tic_tac_toe::game::board_width, 3);std::vector<uint32_t> consecutive_row(tic_tac_toe::game::board_height, 3);uint32_t consecutive_diagonal_backslash = 3;uint32_t consecutive_diagonal_slash = 3;for (uint32_t i = 0; i < board.size(); i++){is_board_full &= is_empty_cell(board[i]);uint16_t row = uint16_t(i / tic_tac_toe::game::board_width);uint16_t column = uint16_t(i % tic_tac_toe::game::board_width);// Calculate consecutive row and column valueconsecutive_row[column] = consecutive_row[column] & board[i];consecutive_column[row] = consecutive_column[row] & board[i];// Calculate consecutive diagonal \ valueif (row == column){consecutive_diagonal_backslash = consecutive_diagonal_backslash & board[i];}// Calculate consecutive diagonal / valueif (row + column == tic_tac_toe::game::board_width - 1){consecutive_diagonal_slash = consecutive_diagonal_slash & board[i];}}// Inspect the value of all consecutive row, column, and diagonal and determine winnerstd::vector<uint32_t> aggregate = {consecutive_diagonal_backslash, consecutive_diagonal_slash};aggregate.insert(aggregate.end(), consecutive_column.begin(), consecutive_column.end());aggregate.insert(aggregate.end(), consecutive_row.begin(), consecutive_row.end());for (auto value : aggregate){if (value == 1){return current_game.host;}else if (value == 2){return current_game.challenger;}}// Draw if the board is full, otherwise the winner is not determined yetreturn is_board_full ? tic_tac_toe::draw : tic_tac_toe::none;}
For the restart action handler, we want to:
Ensure that the action has the signature from the host/challenger
Ensure that the game exists
Ensure that the restart action is done by host/challenger
Reset the game
Store the updated game to the db
void tic_tac_toe::restart(const name &challenger, const name &host, const name &by){check(has_auth(by), "only " + by.to_string() + "can restart the game");// Check if game existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr != existing_host_games.end(), "game doesn't exists");// Check if this game belongs to the action sendercheck(by == itr->host || by == itr->challenger, "this is not your game!");// Reset gameexisting_host_games.modify(itr, itr->host, [](auto &g) {g.reset_game();});}
For the close action handler, we want to:
Ensure that the action has the signature from the host
Ensure that the game exists
Remove the game from the db
void tic_tac_toe::close(const name &challenger, const name &host){check(has_auth(host), "only the host can close the game");require_auth(host);// Check if game existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr != existing_host_games.end(), "game doesn't exists");// Remove gameexisting_host_games.erase(itr);}
You can see the final tic.tac.toe.cpp in the next section.
The final state of the tic.tac.toe.cpp file:
// Import necessary library#include "tic.tac.toe.hpp"// Generic eosio library, i.e. print, type, math, etcusing namespace eosio;bool is_empty_cell(const uint8_t &cell){return cell == 0;}bool is_valid_movement(const uint16_t &row, const uint16_t &column, const std::vector<uint8_t> &board){uint32_t movement_location = row * tic_tac_toe::game::board_width + column;bool is_valid = movement_location < board.size() && is_empty_cell(board[movement_location]);return is_valid;}void tic_tac_toe::create(const name &challenger, name &host) {require_auth(host);check(challenger != host, "challenger shouldn't be the same as host");// Check if game already existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr == existing_host_games.end(), "game already exists");existing_host_games.emplace(host, [&](auto &g) {g.challenger = challenger;g.host = host;g.turn = host;});}void tic_tac_toe::restart(const name &challenger, const name &host, const name &by){check(has_auth(by), "only " + by.to_string() + "can restart the game");// Check if game existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr != existing_host_games.end(), "game doesn't exists");// Check if this game belongs to the action sendercheck(by == itr->host || by == itr->challenger, "this is not your game!");// Reset gameexisting_host_games.modify(itr, itr->host, [](auto &g) {g.reset_game();});}void tic_tac_toe::close(const name &challenger, const name &host){check(has_auth(host), "only the host can close the game");require_auth(host);// Check if game existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr != existing_host_games.end(), "game doesn't exists");// Remove gameexisting_host_games.erase(itr);}void tic_tac_toe::move(const name &challenger, const name &host, const name &by, const uint16_t &row, const uint16_t &column){check(has_auth(by), "the next move should be made by " + by.to_string());// Check if game existsgames existing_host_games(get_self(), host.value);auto itr = existing_host_games.find(challenger.value);check(itr != existing_host_games.end(), "game doesn't exists");// Check if this game hasn't ended yetcheck(itr->winner == tic_tac_toe::none, "the game has ended!");// Check if this game belongs to the action sendercheck(by == itr->host || by == itr->challenger, "this is not your game!");// Check if this is the action sender's turncheck(by == itr->turn, "it's not your turn yet!");// Check if user makes a valid movementcheck(is_valid_movement(row, column, itr->board), "not a valid movement!");// Fill the cell, 1 for host, 2 for challenger//TODO could use constant for 1 and 2 as wellconst uint8_t cell_value = itr->turn == itr->host ? 1 : 2;const auto turn = itr->turn == itr->host ? itr->challenger : itr->host;existing_host_games.modify(itr, itr->host, [&](auto &g) {g.board[row * tic_tac_toe::game::board_width + column] = cell_value;g.turn = turn;g.winner = get_winner(g);});}name get_winner(const tic_tac_toe::game ¤t_game){auto &board = current_game.board;bool is_board_full = true;// Use bitwise AND operator to determine the consecutive values of each column, row and diagonal// Since 3 == 0b11, 2 == 0b10, 1 = 0b01, 0 = 0b00std::vector<uint32_t> consecutive_column(tic_tac_toe::game::board_width, 3);std::vector<uint32_t> consecutive_row(tic_tac_toe::game::board_height, 3);uint32_t consecutive_diagonal_backslash = 3;uint32_t consecutive_diagonal_slash = 3;for (uint32_t i = 0; i < board.size(); i++){is_board_full &= is_empty_cell(board[i]);uint16_t row = uint16_t(i / tic_tac_toe::game::board_width);uint16_t column = uint16_t(i % tic_tac_toe::game::board_width);// Calculate consecutive row and column valueconsecutive_row[column] = consecutive_row[column] & board[i];consecutive_column[row] = consecutive_column[row] & board[i];// Calculate consecutive diagonal \ valueif (row == column){consecutive_diagonal_backslash = consecutive_diagonal_backslash & board[i];}// Calculate consecutive diagonal / valueif (row + column == tic_tac_toe::game::board_width - 1){consecutive_diagonal_slash = consecutive_diagonal_slash & board[i];}}// Inspect the value of all consecutive row, column, and diagonal and determine winnerstd::vector<uint32_t> aggregate = {consecutive_diagonal_backslash, consecutive_diagonal_slash};aggregate.insert(aggregate.end(), consecutive_column.begin(), consecutive_column.end());aggregate.insert(aggregate.end(), consecutive_row.begin(), consecutive_row.end());for (auto value : aggregate){if (value == 1){return current_game.host;}else if (value == 2){return current_game.challenger;}}// Draw if the board is full, otherwise the winner is not determined yetreturn is_board_full ? tic_tac_toe::draw : tic_tac_toe::none;}
Let's compile our contract, using eosio-cpp:
eosio-cpp -I tic_tac_toe.hpp tic_tac_toe.cpp
Now the wasm file and the abi file are ready. Time to deploy! Create a directory (let's call it tic_tac_toe) and copy your generated tic.tac.toe.wasm and tic_tac_toe.abi files.
cleos set contract tic.tac.toe tic_tac_toe -p [email protected]
Ensure that your wallet is unlocked and you have tic.tac.toe
key imported.
After the deployment and the transaction is confirmed, the contract is already available in the blockchain. You can play with it now!
[[info | Test Account]] | If you have not created these accounts already, refer to this article for creating test accounts Create Test Accounts
We are going to use bob
and alice
accounts to play this game:
cleos push action tic.tac.toe create '{"challenger":"bob", "host":"alice"}' --permission [email protected]
cleos push action tic.tac.toe move '{"challenger":"bob", "host":"alice", "by":"alice", "row":0, "column":0}' --permission [email protected]cleos push action tic.tac.toe move '{"challenger":"bob", "host":"alice", "by":"bob", "row":1, "column":1}' --permission [email protected]
$ cleos get table tic.tac.toe alice games{"rows": [{"challenger": "bob","host": "alice","turn": "bob","winner": "none","board": [1,0,0,0,2,0,0,0,0]}],"more": false}
cleos push action tic.tac.toe restart '{"challenger":"bob", "host":"alice", "by":"alice"}' --permission [email protected]
cleos push action tic.tac.toe close '{"challenger":"bob", "host":"alice"}' --permission [email protected]