Tutorial roadtothreehoundred

This tutorial will guide you through the basics of creating a simple game on BGA Studio, through the example of Road To Three Hundred

<<INSERT CONTENT>>

Set up the board

Edit .tpl to add divs in the HTML for the main board, which is divided in three: area for the dice (we will code details later), area for this player, and area for the other player.

<div id="rt300_mainboard">
    <div id="rt300_spacer" class="rt300_zone"></div>

    <div id="rt300_dice">

    </div>

    <div id="rt300_mainplboard" class="rt300_zone" style="--player-color: #{PLAYER_COLOR}">
        <div id="rt300_playerboard_{PLAYER_ID}" class="rt300_playerboard" style="order: 0">
            <div class="rt300_playerheader">
                <div class="rt300_nameholder">
                    <div id="rt300_plname_{PLAYER_ID}" class="rt300_plname">{PLAYER_NAME}</div>
                </div>
            </div>

            <div id="rt300_metropad_{PLAYER_ID}" class="rt300_metropad" style="opacity: 1">
            </div>
        </div>
    </div>

    <div id="rt300_opponents" class="rt300_zone">
        <div id="rt300_mainplboard_{PLAYER_ID}" class="rt300_zone" style="--player-color: #{PLAYER_COLOR}">
            <div id="rt300_playerboard_{PLAYER_ID}" class="rt300_playerboard" style="order: 0">
                <div class="rt300_playerheader">
                    <div class="rt300_nameholder">
                        <div id="rt300_plname_{PLAYER_ID}" class="rt300_plname">{PLAYER_NAME}</div>
                    </div>
                </div>

                <div id="rt300_metropad_{PLAYER_ID}" class="rt300_metropad" style="opacity: 1">
                </div>
            </div>
        </div>
    </div>

</div>

Edit .css to set the div sizes and positions and upload "field.png" in the 'img' folder of your SFTP access to show the image of the board as background for both this player and the other player (smaller).

You can find the board image here : <<UPLOAD FILE>>

#rt300_mainboard {
    display: flex;
    flex-wrap: wrap;
    justify-content: space-around;
    gap: 1em;
}


#rt300_mainplboard {
    --padsize: 60vh;
    --padratio: 1;
}

.rt300_playerboard {
    border-left: 1px solid gray;
    border-top: 1px solid gray;
    filter: drop-shadow(2px 4px 6px black);
    position: relative;
}

.rt300_zone {
    align-items: center;
    display: flex;
    flex-direction: column;
    justify-content: space-evenly;
    padding: 1vh;
}

#rt300_opponents {
    --padsize: 19vh;
    --padratio: 1;
    display: flex;
    justify-content: space-evenly;
    width: 20vh;
}


@media only screen and (max-width: 560px) {
    #rt300_spacer {
        display: none;
    }
}

.rt300_playerheader {
    background-color: #46a12a;
    height: calc(var(--padsize) * var(--padratio) * 0.05);
    position: relative;
    width: calc(var(--padsize) * var(--padratio));
}
#rt300_dice {
    display: flex;
    flex-direction: column;
    justify-content: space-evenly;
    align-items: center;
    filter: drop-shadow(2px 4px 6px black);
}


.rt300_nameholder {
    align-items: center;
    display: flex;
    font-family: Indie Flower, sans-serif;
    font-weight: bolder;
    height: 38%;
    justify-content: center;
    left: 33%;
    position: absolute;
    top: 29%;
    width: 31%;
}

.rt300_plname {
    font-size: calc(var(--padsize) * var(--padratio) * 0.04);
    height: fit-content;

    color: var(--player-color);
}

.rt300_metropad {
    background-image: url(img/field.png);
    background-size: contain;
    background-repeat: no-repeat;
    height: calc(var(--padsize) * var(--padratio) * 1.252);
    position: relative;
    width: calc(var(--padsize) * var(--padratio));
}

You can run the game to check the boards are being shown.

Set up the backend of your game

Edit dbmodel.sql to create a table for board squares. We need coordinates for each square and a field to store their status.

CREATE TABLE `board` (
  `player_id` int(11) NOT NULL,
  `col` int(11) NOT NULL,
  `row` int(11) NOT NULL,
  `status` int(11) NOT NULL
);
ALTER TABLE `board` ADD PRIMARY KEY(`player_id`, `col`, `row`);

Edit .game.php->setupNewGame() to insert the empty squares (6x6) with coordinates into the database.

        $sql1 = "INSERT INTO board (player_id, row, col, status) VALUES ";
        $values = [];
        foreach ($players as $player_id => $player) {
            for ($r = 1; $r <= 6; $r++) {
                for ($c = 1; $c <= 6; $c++) {
                    $values[] = "('" . $player_id . "', '$r', '$c', 0) ";
                }
            }
        }
        $sql1 .= implode($values, ",");
        self::DbQuery($sql1);

Edit .game.php->getAllDatas() to retrieve the state of the squares from the database.

        $result["board"] = [];
        foreach ($result["players"] as $playerInfo) {
            $result["board"][$playerInfo["id"]] = DBManager::getBoardForPlayer($playerInfo["id"]);
        }

We define the DBManager class in a separate module modules\DBManager.php to keep a clean code.

<?php
class DBManager extends APP_GameClass {
    public static function getBoardForPlayer($player_id, $useUndoTable = false) {
        $sql = "SELECT col, row, status FROM board WHERE player_id = $player_id ORDER BY col, row; ";
        if ($useUndoTable) {
            $sql = "SELECT col, row, status FROM board_undo WHERE player_id = $player_id ORDER BY col, row; ";
        }
        return self::getObjectListFromDB($sql);
    }
}
?>

We will add more database management related functions to this file later on.

With class extends, we construct the game in the GameBody variable definition. Now we add construction for playerBoards[]:

var GameBody = /** @class */ (function (_super) {
    __extends(GameBody, _super);
    function GameBody() {
        var _this = 
        //console.log('GameBody constructor');
        _super.call(this) || this;

        _this.playerBoards = [];

Likewise, we set up game data in GameBody,prototype.setup funtion. Now set up the player boards:

    GameBody.prototype.setup = function (gamedatas) {
        ///////////////////////////////////////////////////////////////////////////////////////////
        // Debug
        console.log("Starting game setup");
        ///////////////////////////////////////////////////////////////////////////////////////////
        // Setting up player boards
        for (var player_id in gamedatas.players) {
            var player = gamedatas.players[player_id];

            var playerBoard = new PlayerBoard(player, gamedatas.board[player_id]);
            this.playerBoards[player_id] = playerBoard;

As we did with DBManager, we define the PlayerBoard class in a separate module modules\PlayerBoard.php to keep a clean code.

<?php
class PlayerBoard extends APP_GameClass {
    public int $playerId;
    public int $playerPassed;
    public $board = [];
    public $useUndoTable;

    function __construct($playerId) {
        // Store values
        $this->playerId = $playerId;

        // Get playerboard
        $boardInfo = DBManager::getBoardForPlayer($playerId);
        $this->board = [];
        foreach ($boardInfo as $element) {
            $cell = new PlayerBoardCell($this->playerId, $element["col"], $element["row"], $element["status"]);
            $this->board[] = $cell;
        }
    }

}

?>

and in PlayerBoardCell.php:

<?php
class PlayerBoardCell extends APP_GameClass {
    public int $col;
    public int $row;
    public int $status;
    public int $playerId;

    function __construct($playerId, $col, $row, $status) {
        $this->playerId = intval($playerId);
        $this->col = intval($col);
        $this->row = intval($row);
        $this->status = intval($status);
    }
}
?>

To make sure functions in modules are reachable from the game, add a call in material.inc.php:

require_once "modules/PlayerBoardCell.php";
require_once "modules/PlayerBoard.php";
require_once "modules/DBManager.php";

Run the game now, simply to test that nothing goes south (you will no changes with respects to the previous checkpoint).

Set up the front-end of your game

Instead of using the .js file available in the blank game template, we will use new class that extends bga core game class with more functionality:

REPLACE TEMPLATE .JS FILE BY THIS: <<LINK TO roadtothreehoundredjngm - INITIAL>>

The data you returned in $result["board"][] in .game.php->getAllDatas() needs to be made available in your .js. so that the squares layer that will be used to get click events and to display used squares is set up. This means we need to define PlayerBoard and PlayerBoiardCell classes and functions also in .js file:

var PlayerBoard = /** @class */ (function (_super) {

    __extends(PlayerBoard, _super);
    function PlayerBoard(playerInfo, boardInfo) {
        var _this = _super.call(this) || this;
        _this.clientStateArgs = {};
        // Store values
        _this.playerId = playerInfo.id;
        _this.board = [];
        boardInfo.forEach(function (element) {
            _this.board.push(new PlayerBoardCell(_this.playerId, element.col, element.row, element.status));
        });
        return _this;
    }
    return PlayerBoard;
}(RootReference));
/// <reference path="base/RootReference.ts"/>

var PlayerBoardCell = /** @class */ (function (_super) {
    __extends(PlayerBoardCell, _super);
    function PlayerBoardCell(playerId, col, row, status) {
        var _this = _super.call(this) || this;
        _this.col = parseInt(col);
        _this.row = parseInt(row);
        _this.status = parseInt(status);
        if (col >= 1 && col <= 6 && row >= 1 && row <= 6) {
            _this.element = $("".concat(playerId, "_").concat(col, "_").concat(row));

/*** THIS GIVES ERROR: Cannot read properties of null (reading 'dataset')
            // NEEDS TO BE DEBUGGED
            // ?? WHAT ARE THE IMPLICATIONS OF MISSING THIS CODE ??
            //_this.element.dataset.status = _this.status.toString();
***/
        }
        return _this;
    }
    return PlayerBoardCell;
}(RootReference));
/// <reference path="RootReference.ts"/>

Run the game now, simply to test that nothing goes south (you will no changes with respects to the previous checkpoint).

Manage states and events

Define your game states in states.inc.php. We will use 3 states in addition of the predefined states 1 and 99. One to play the round for any player, one to check the end game condition, one to enable next round for players whose game is not over yet.

The player round state requires an action from any of the active players, so its type is 'multipleactiveplayer'.

The two others are automatic actions for the game, so their type is 'game'.

In the enable next round state we will update the progression while checking for the end of the game, so for this state we set the 'updateGameProgression' flag to true.

$machinestates = [
    // The initial state. Please do not modify.
    1 => [
        "name" => "gameSetup",
        "description" => "",
        "type" => "manager",
        "action" => "stGameSetup",
        "transitions" => ["" => 4//'ST_PLAYER_MULTIACTIVATE'
        ],
    ],

    2 => [
        "name" => "playerTurn",
        "description" => clienttranslate("Waiting for other players"),
        "descriptionmyturn" => clienttranslate('${you} must select a cell to cross or pass the turn if non available'),
        "type" => "multipleactiveplayer",
        "possibleactions" => ["confirmTurn", "undoTurn", "passTurn", "passWholeGame"],
        "args" => "argPlayerTurn",
        "transitions" => ["next" => 3],
    ],

    3 => [
        "name" => "nextRoundOrGameEnd",
        "description" => "",
        "type" => "game",
        "action" => "stNextRoundOrGameEnd",
        "updateGameProgression" => true,
        "transitions" => [
            "next" => 4,
            "gameEnd" => 99,
        ],
    ],
    4 => [
        "name" => "multiActivatePlayers",
        "description" => clienttranslate("multiActivatePlayers state"),
        "type" => "game",
        "action" => "stMultiPlayerActivate",
        "transitions" => [
            "next" => 2,
        ],
    ],

    // Final state.
    // Please do not modify (and do not overload action/args methods).
    99 => [
        "name" => "gameEnd",
        "description" => clienttranslate("End of game"),
        "type" => "manager",
        "action" => "stGameEnd",
        "args" => "argGameEnd",
    ],
];

There are four actions player can do - "confirmTurn", "undoTurn", "passTurn", "passWholeGame". We define stub functions into .action.php and .game.php files now, since we have not implemented states yet.

i) action file

  public function passTurn() {
      self::setAjaxMode();

      // Then, call the appropriate method in your game logic, like "playCard" or "myAction"

      self::ajaxResponse();
  }

  public function passWholeGame() {
      self::setAjaxMode();

      // Then, call the appropriate method in your game logic, like "playCard" or "myAction"

      self::ajaxResponse();
  }

  public function confirmTurn() {
      self::setAjaxMode();

      // Retrieve arguments
      // Note: these arguments correspond to what has been sent through the javascript "ajaxcall" method

      // Then, call the appropriate method in your game logic, like "playCard" or "myAction"

      self::ajaxResponse();
  }

  public function undoTurn() {
    self::setAjaxMode();

    // Then, call the appropriate method in your game logic, like "playCard" or "myAction"
    
    self::ajaxResponse();
  }

ii) game file

    function passTurn() {
        // Check that this is the player's turn and that it is a "possible action" at this game state (see states.inc.php)
        self::checkAction("passTurn");

        // Get player and infos
        $player_id = self::getCurrentPlayerId();
        $playerInfo = DBManager::getPlayerDatasForPlayer($player_id);

        // Deactive player and if that player was the last active, change state
        $this->gamestate->setPlayerNonMultiactive($player_id, "next");
    }

    function passWholeGame() {
        // Check that this is the player's turn and that it is a "possible action" at this game state (see states.inc.php)
        self::checkAction("passWholeGame");

        // Get player and infos
        $player_id = self::getCurrentPlayerId();
        $playerInfo = DBManager::getPlayerDatasForPlayer($player_id);

        // Deactive player and if that player was the last active, change state
        $this->gamestate->setPlayerNonMultiactive($player_id, "next");
    }

    function confirmTurn($crossedCellCoordinate, $movedCellCoordinate) {

        // Check that this is the player's turn and that it is a "possible action" at this game state (see states.inc.php)
        self::checkAction("confirmTurn");

        // Get player and infos
        $player_id = self::getCurrentPlayerId();
        $playerInfo = DBManager::getPlayerDatasForPlayer($player_id);

        // Deactive player and if that player was the last active, change state
        $this->gamestate->setPlayerNonMultiactive($player_id, "next");
    }

    function undoTurn() {
        // Check that this is the player's turn and that it is a "possible action" at this game state (see states.inc.php)
        if (self::checkAction("undoTurn", false)) {
            Utils::userException(self::_("You did not make a turn to undo"));
        }

        // Get player and info
        $player_id = self::getCurrentPlayerId();
        $playerInfo = DBManager::getPlayerDatasForPlayer($player_id);

        // Re-Activate player
        $this->gamestate->setPlayersMultiactive([$player_id], "Ingore_ME", false);
    }

Now to make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argPlayerTurn and 2 functions for robot states (where the game performs some action). In .game.php, find 'Game state arguments' section and paste this in:

    function argPlayerTurn() {
        $players = DBManager::getAllPlayerDatas();

        $private = [
            "_private" => [],
        ];
        foreach ($players as $playerInfo) {
            $private["_private"][$playerInfo["id"]] = DBManager::getBoardForPlayer($playerInfo["id"], true);
        }
        return $private;
    }

Let's do stubs for robot functions, find the game state actions section in .game.php file and insert these

    function stMultiPlayerActivate() {
        $this->gamestate->nextState("next");
    }
    function stNextRoundOrGameEnd() {
        $this->gamestate->nextState("next");
    }

Now as for getActivePlayers(): the rules dictate that a player is not allowed to play anymore after 3 consecutive round passes. We need to introduce a player field to keep track of that count, so

i) we add it to player table in the DB model

ALTER TABLE `player` ADD `player_pass_count` INT NOT NULL DEFAULT '0' AFTER `player_state`;

ii) we initialise it in game.php, adding it to the populate query in setupNewGame()

// Create players
        // Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
    
        //$sql = "INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar) VALUES ";
        $sql = "INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_pass_count) VALUES ";

        $values = [];
        foreach ($players as $player_id => $player) {
            $color = array_shift($default_colors);
            $values[] = "('" . $player_id . "','$color','" . $player["player_canal"] . "','" . addslashes($player["player_name"]) . "','" . addslashes($player["player_avatar"]) . "', 0)";
            //$values[] = "('" . $player_id . "','$color','" . $player["player_canal"] . "','" . addslashes($player["player_name"]) . "','" . addslashes($player["player_avatar"]) . "')";

        }

Finally in DBManage we add all database related functions for the states coding added in this section:

public static function getActivePlayers() {
        $sql = "SELECT player_id FROM player WHERE player_pass_count < 3";
        return self::getObjectListFromDB($sql);
    }
    
    public static function getAllPlayerDatas() {
        $sql = "SELECT player_id id, player_score score, player_pass_count AS pass_count FROM player ";
        return self::getCollectionFromDb($sql);
    }
    public static function getPlayerDatasForPlayer($player_id) {
        $sql = "SELECT player_id id, player_score score, player_pass_count AS pass_count FROM player WHERE player_id = $player_id;";
        return self::getObjectFromDB($sql);
    }

Now the game should start and you should see "Waiting for other players" on the top status bar, even if you switch players.

This is because we have not set player turn yet. Let us know implement function stMultiPlayerActivate():

    function stMultiPlayerActivate() {
        // Get all players which are still in the game
        $players = DBManager::getActivePlayers();
        $players = array_map(fn($value): string => $value["player_id"], $players);

        // Give them extra time
        foreach ($players as $player_id) {
            self::giveExtraTime($player_id);
            self::giveExtraTime($player_id);
        }

        // All those players are active
        $this->gamestate->setPlayersMultiactive($players, "INGORE_ME", true);

        $this->gamestate->nextState("next");
    }

Possible player actions will depend on the result of dice roll. So we need to define this object and its logic before we implement player actions.

We'll follow same implementation steps as with boards above: tpl, css, js, game files

In tpl, add this in "rt300_dice" area:

        <div id="dice1" class="dice dice-two">
            <div id="dice-two-side-one" class="side one">
                <div class="dot one-1"></div>
            </div>
            <div id="dice-two-side-two" class="side two">
                <div class="dot two-1"></div>
                <div class="dot two-2"></div>
            </div>
            <div id="dice-two-side-three" class="side three">
                <div class="dot three-1"></div>
                <div class="dot three-2"></div>
                <div class="dot three-3"></div>
            </div>
            <div id="dice-two-side-four" class="side four">
                <div class="dot four-1"></div>
                <div class="dot four-2"></div>
                <div class="dot four-3"></div>
                <div class="dot four-4"></div>
            </div>
            <div id="dice-two-side-five" class="side five">
                <div class="dot five-1"></div>
                <div class="dot five-2"></div>
                <div class="dot five-3"></div>
                <div class="dot five-4"></div>
                <div class="dot five-5"></div>
            </div>
            <div id="dice-two-side-six" class="side six">
                <div class="dot six-1"></div>
                <div class="dot six-2"></div>
                <div class="dot six-3"></div>
                <div class="dot six-4"></div>
                <div class="dot six-5"></div>
                <div class="dot six-6"></div>
            </div>
        </div>

        <div id="dice2" class="dice dice-two">
            <div id="dice-two-side-one" class="side one">
                <div class="dot one-1"></div>
            </div>
            <div id="dice-two-side-two" class="side two">
                <div class="dot two-1"></div>
                <div class="dot two-2"></div>
            </div>
            <div id="dice-two-side-three" class="side three">
                <div class="dot three-1"></div>
                <div class="dot three-2"></div>
                <div class="dot three-3"></div>
            </div>
            <div id="dice-two-side-four" class="side four">
                <div class="dot four-1"></div>
                <div class="dot four-2"></div>
                <div class="dot four-3"></div>
                <div class="dot four-4"></div>
            </div>
            <div id="dice-two-side-five" class="side five">
                <div class="dot five-1"></div>
                <div class="dot five-2"></div>
                <div class="dot five-3"></div>
                <div class="dot five-4"></div>
                <div class="dot five-5"></div>
            </div>
            <div id="dice-two-side-six" class="side six">
                <div class="dot six-1"></div>
                <div class="dot six-2"></div>
                <div class="dot six-3"></div>
                <div class="dot six-4"></div>
                <div class="dot six-5"></div>
                <div class="dot six-6"></div>
            </div>
        </div>

        <div id="dice3" class="dice dice-three">
            <div id="dice-two-side-one" class="side one">
                <div class="dot one-1"></div>
            </div>
            <div id="dice-two-side-two" class="side two">
                <div class="dot two-1"></div>
                <div class="dot two-2"></div>
            </div>
            <div id="dice-two-side-three" class="side three">
                <div class="dot three-1"></div>
                <div class="dot three-2"></div>
                <div class="dot three-3"></div>
            </div>
            <div id="dice-two-side-four" class="side four">
                <div class="dot four-1"></div>
                <div class="dot four-2"></div>
                <div class="dot four-3"></div>
                <div class="dot four-4"></div>
            </div>
            <div id="dice-two-side-five" class="side five">
                <div class="dot five-1"></div>
                <div class="dot five-2"></div>
                <div class="dot five-3"></div>
                <div class="dot five-4"></div>
                <div class="dot five-5"></div>
            </div>
            <div id="dice-two-side-six" class="side six">
                <div class="dot six-1"></div>
                <div class="dot six-2"></div>
                <div class="dot six-3"></div>
                <div class="dot six-4"></div>
                <div class="dot six-5"></div>
                <div class="dot six-6"></div>
            </div>
        </div>

So we have one class for each of the 3 dice, one classe for each die side, and for each side as many classes as dots on the side. We'll see how all this is used later on. For now, in .css we define class for dice, dot and side, and for selected dice:

.dice {
    display: flex;
    width: 100px;
    height: 100px;
    transform-style: preserve-3d;
    transition: transform 1s;
}

.dot {
    position: absolute;
    width: 20px;
    height: 20px;
    margin: -10px 5px 5px -10px;
    border-radius: 20px;
    background-color: #46a12a;
    box-shadow: inset 2px 2px #46a12a;
}

.side {
    position: absolute;
    background-color: #fff;
    border-radius: 5px;
    width: 100px;
    height: 100px;
    border: 1px solid #e5e5e5;
    text-align: center;
    line-height: 2em;
}

.dice.used > div.side {
    background-color: darkgray;
    border: 1px solid darkgray;
}