Actions

Action methods start with act and accept typed parameters. Methods in a state class are declared with #[PossibleAction]; Game can provide fallback actions. See state action callbacks for their placement and injected player parameters.

use Bga\GameFramework\States\PossibleAction;

#[PossibleAction]
public function actSelectTile(int $tileId): void
{
    // Validate ownership and game rules before applying the selection.
}

this.bga.actions.performAction('actSelectTile', { tileId: this.selectedTileId });

The framework fills array $args from the current state's arguments. It also supplies int $activePlayerId, int $activePlayerNo, int $currentPlayerId, and int $currentPlayerNo, including their snake_case equivalents. Use active-player parameters only for single-active-player states. The current player is the request's author; an unqualified $playerId is not a current-player magic parameter for an action.

Parameter attributes

Optional attributes

The server matches request fields to parameter names and converts basic int, float, bool, and string values.

You don't need to specify an attribute for these simple types unless you need extra configuration, such as a request field name that differs from the PHP parameter name.

Import parameter attributes from Bga\GameFramework\Actions\Types. All support an optional $name to read a request field with a different name from the PHP parameter.

Boolean

BoolParam(?string $name = null)

Read a boolean request parameter.

use Bga\GameFramework\Actions\Types\BoolParam;

public function actSetAutoPass(#[BoolParam(name: 'enabled')] bool $autoPass): void
{
    // $autoPass contains the boolean sent as "enabled".
}

Number

IntParam(?string $name = null, ?int $min = null, ?int $max = null)

Read an integer with optional bounds.

use Bga\GameFramework\Actions\Types\IntParam;

public function actSelectPosition(#[IntParam(name: 'id')] int $tileId,
    #[IntParam(min: 1, max: 5)] int $position): void
{
    // The framework checks the position's numeric bounds.
    // Check that this tile can legally be placed there.
}

FloatParam(?string $name = null, ?float $min = null, ?float $max = null)

Read a floating-point number with optional bounds.

use Bga\GameFramework\Actions\Types\FloatParam;

public function actChooseAmount(#[FloatParam(min: 0.5, max: 10.0)] float $amount): void
{
    // $amount is between 0.5 and 10.0, inclusive.
    // Check any additional restrictions required by the game rules.
}

String

StringParam(?string $name = null, ?bool $alphanum = false, ?bool $alphanum_dash = false, ?bool $base64 = false, ?array $enum = null)

Constrain strings with a character check or an allowed-value list. alphanum accepts ASCII letters, digits, underscores, and spaces; alphanum_dash also allows hyphens. Validate any additional restrictions required by your game.

use Bga\GameFramework\Actions\Types\StringParam;

public function actChooseMode(#[StringParam(enum: ['move', 'attack', 'pass'])] string $mode): void
{
    // Validate that the chosen mode is legal in the current game situation.
}

Int array

IntArrayParam(?string $name = null, ?int $min = null, ?int $max = null)

Read a list of integers. The bounds apply to the number of entries, not to the values of individual entries. Validate IDs, ownership, duplicates, and game-specific constraints in the action.

use Bga\GameFramework\Actions\Types\IntArrayParam;

public function actDiscardTiles(#[IntArrayParam(min: 2, max: 4)] array $ids): void
{
    // Validate the listed tiles before discarding them.
}

this.bga.actions.performAction('actDiscardTiles', { ids: [8, 12, 25] });

For an optional empty list, use a nullable parameter such as #[IntArrayParam] ?array $ids and handle null as an empty list.

Object / array

JsonParam(?string $name = null, ?bool $associative = true, ?bool $alphanum = true, ?string $class = null)

Decode a JSON string. By default, objects become associative arrays. Set associative: false or null for object decoding. The default alphanum validation restricts string keys and values to letters, digits, underscores, hyphens, and spaces; disabling it requires your own validation.

use Bga\GameFramework\Actions\Types\JsonParam;

public function actSubmitPlan(#[JsonParam] array $plan): void
{
    // Validate the decoded structure and the proposed moves.
}

this.bga.actions.performAction('actSubmitPlan', {
    plan: JSON.stringify({ tileIds: [8, 12], destination: 'garden' }),
});

A class argument can reconstruct a data object. The class can also be inferred from a typed parameter:

use Bga\GameFramework\Actions\Types\JsonParam;

class PlacementPlan
{
    public function __construct(
        public int $tileId,
        public string $destination,
    ) {}
}

class PlanActions
{
    public function actSubmitPlan(#[JsonParam] PlacementPlan $plan): void
    {
        // Validate the proposed plan before applying it.
    }

    public function actSubmitPlans(#[JsonParam(class: PlacementPlan::class)] array $plans): void
    {
        // Each object in the JSON array is mapped to PlacementPlan.
    }
}

PlanActions above illustrates the signatures; put the actual action methods in Game or a state class.

Disabling the automatic action check

Use #[CheckAction(false)] only for actions intentionally available outside the requester's turn. Check participation, elimination status, permissions, and current-state rules explicitly as needed.

use Bga\GameFramework\Actions\CheckAction;

#[CheckAction(false)]
public function actChangeMind(int $currentPlayerId): void
{
    $this->game->gamestate->checkPossibleAction('actChangeMind');
    // Check that this player may change their choice.
    $this->game->gamestate->setPlayersMultiactive([$currentPlayerId], ResolveChoices::class);
}

Configure the front-end action call consistently:

this.bga.actions.performAction('actChangeMind', {}, {
    checkAction: false,
    checkPossibleActions: true,
});