State classes: State directory

Game File Reference

Overview

• dbmodel.sql - database model
• gameinfos.inc.php - meta-information
• gameoptions.json - game options & user preferences
• img/ - game art
• Game Metadata Manager - tags and metadata media
• material.inc.php - static data
• misc/ - studio-only storage
• modules/ - additional game code
• States/ - State classes
• states.inc.php - state machine
• stats.json - statistics
• X.action.php - player actions
• X.css - interface stylesheet
• Game.php - main logic
• X.js - interface logic
• X.view.php - dynamic game layout
• X_X.tpl - static game layout

---

Useful Components

Official

• Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
• PlayerCounter and TableCounter: PHP components to manage counters.
• Draggable: a JS component to manage drag'n'drop actions.
• Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
• ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
• Scrollmap: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
• Stock: a JS component to manage and display a set of game elements displayed at a position.
• Zone: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
• bga-animations : a JS component for animations.
• bga-cards : a JS component for cards.
• bga-dice : a JS component for dice.
• bga-autofit : a JS component to make text fit on a fixed size div.
• bga-score-sheet : a JS component to help you display an animated score sheet at the end of the game.

Unofficial

• BGA Code Sharing - Shared resources, projects on git hub, common code, other links
• BGA Studio Cookbook - Tips and instructions on using API's, libraries and frameworks
• Common board game elements image resources

---

Game Development Process

• First steps with BGA Studio
• Create a game in BGA Studio: Complete Walkthrough
• Tutorial reversi
• Tutorial hearts
• BGA Studio Guidelines
• BGA game Lifecycle
• Pre-release checklist
• Post-release phase
• Player Resources - add player help/rules to your game page

---

Guides for Common Topics

• Translations - make your game translatable
• Game Replay
• Mobile Users
• 3D
• Compatibility

---

Miscellaneous Resources

• Studio FAQ
• Tools and tips of BGA Studio - Tips and instructions on setting up development environment
• Studio logs - Instructions for log access
• Practical debugging - Tips focused on debugging
• Troubleshooting - Most common "I am really stuck" situations
• Studio Bugs - Reports against Studio itself (not BGA!)

🚧 Work in Progress 🚧

You can test it on the Studio, but not yet deploy it to production.

State classes allow to create a PHP class for each game state. It allows to split the code in multiple files, without using Traits. The advantage is that the IDE understands the structure and can provide auto-completion and error highlights, that are lost in Traits.

Structure

The State class in modules/php/States/PlayerTurn.php will have this structure:

namespace Bga\Games\<MyGameName>\States;

use Bga\GameFramework\StateType;
use Bga\GameFramework\States\GameState;
use Bga\GameFramework\States\PossibleAction;
use Bga\Games\<MyGameName>\Game;

class PlayerTurn extends GameState
{
    function __construct(
        protected Game $game,
    ) {
        parent::__construct($game,
            id: 2,
            type: StateType::ACTIVE_PLAYER,

            // optional
            description: clienttranslate('${actplayer} must play a card or pass'),
            descriptionMyTurn: clienttranslate('${you} must play a card or pass'),
            transitions: [],
            updateGameProgression: false,
            initialPrivate: null,
        );
    }

    public function getArgs(): array
    {
        // the data sent to the front when entering the state
        return [];
    } 

    function onEnteringState(int $activePlayerId) {
        // the code to run when entering the state
    }   

    #[PossibleAction]
    public function actPlayCard(int $cardId, int $activePlayerId, array $args): string
    {
        // the code to run when the player triggers actPlayCard with bgaPerformAction
    }

    function zombie(int $playerId): string {
        // the code to run when the player is a Zombie
    }
}

The state must extends Bga\GameFramework\States\GameState and follow the same __construct function as the example. Only $game, id and type are mandatory, other parameters are optional. In non GAME states, the zombie function is also mandatory.

Differences with states declared in states.inc.php

Moved elements

The function getArgs replaces the function that was declared as "args" => "argXXX" on states.inc.php. Same for the function onEnteringState that was "action" => "stXXX" on states.inc.php. The zombie function doesn't have the state as first parameter anymore, because it's not needed in this context.

The possible actions for this states don't need to be declared as an array, they will be found with the tag #[PossibleAction] over each possible action.

The functions declared in Game.php will be accessible with $this->game instead of $this. The Game sub-objects are available on the State class too, so you can write $this->notif->all without needing to pass through the game variable.

New elements

In the new class

The getArgs function can set some predefined parameters that will be automatically filled:

• int $activePlayerId/$active_player_id will be filled by the result of getActivePlayerId. To be used on ACTIVE_PLAYER states only.
• int $playerId/$player_id/$currentPlayerId/$current_player_id will be filled by the player id of the current PRIVATE state. To be used on PRIVATE states only.

The onEnteringState function can set some predefined parameters that will be automatically filled:

• array $args will be filled by the result of $this->getArgs().
• int $activePlayerId/$active_player_id will be filled by the result of getActivePlayerId. To be used on ACTIVE_PLAYER states only.
• int $playerId/$player_id/$currentPlayerId/$current_player_id will be filled by the player id of the current PRIVATE state. To be used on PRIVATE states only.

The actXXX functions (auto-wired functions) can set some predefined parameters that will be automatically filled:

• array $args will be filled by the result of $this->getArgs().
• int $activePlayerId/$active_player_id will be filled by the result of getActivePlayerId. To be used on ACTIVE_PLAYER states only.
• int $currentPlayerId/$current_player_id will be filled by the result of getCurrentPlayerId.

For all those functions, and also the zombie function, they can now send a redirection to a game state as a returned result. The allowed writings are:

• return NextPlayer::class will redirect to the state declared in that class.
• return ST_END_GAME; = return 99; will redirect to the state of that id. It must be typed as int, numbers in a string won't work.
• return 'nextPlayer'; will redirect to the transition of that name (requires transitions to be declared in the constructor).

If you use this writing, remove $this->gamestate->nexState to avoid double redirection!

The initialPrivate parameter of the constructor can be null or an int as before, but can now also accept a class name as value initialPrivate: PlaceCard::class

Outside the new class

You can now pass a state class as the parameter of GameStateBuilder::gameSetup(PlayDisc::class)->build(), and on some function that previously only accepted transitions, like $this->gamestate->nextPrivateState(ConfirmTurn::class) or $this->gamestate->setPlayerNonMultiactive($currentPlayerId, EndRound::class)

Zombie

Some utilities function has been added for Zombie Mode, so the example you can see in Zombie Mode can be simplified to :

Example of Zombie level 0

    function zombie(int $playerId): void {
        return NextPlayer::class;
    }

Example of Zombie level 1

    function zombie(int $playerId): void {
        $args = $this->getArgs();
        $zombieChoice = $this->getRandomZombieChoice($args['playableCardsIds']); // random choice over possible moves
        return $this->actPlayCard($zombieChoice, $playerId, $args); // this function will return the state to go to, so we return it to end the zombie function
    }

Example of Zombie level 2

    function zombie(int $playerId): void {
        $args = $this->getArgs();
        $possibleSpaces = $args['possibleSpaces'];
        $playerCards = $this->getPlayerCards($playerId);

        $possibleAnswerPoints = [];
        foreach ($possibleSpaces as $choice) {
            $possibleAnswerPoints[$choice] = $this->getPointsFromState3Choice($playerCards, $choice); // for each possible choice, compute the points the player/Bot would immediately gain
        }

        $zombieChoice = $this->getBestZombieChoice($possibleAnswerPoints); // get top choice over possible moves
        return $this->actPlayCard($zombieChoice, $playerId, $args); // this function will return the state to go to, so we return it to end the zombie function
    }