$this->bga->playerStats

Manage values declared in the player section of stats.jsonc. Player arguments use IDs by default.

API

init(string|array $nameOrNames, int|float|bool $value, bool $updateTableStat = false): void

Initialize the named statistics for all players during setupNewGame, after the player table has been populated. With $updateTableStat = true, also initialize table statistics with the same names.

get(string $name, int $playerIdOrNo): int|float|bool

Read one player’s value using its configured type.

getAll(string $name): array

Return all players’ values, keyed by player ID or number according to setUseNo.

set(string $name, int|float|bool $value, int $playerIdOrNo): void

Replace one player’s value.

setAll(string $name, int|float|bool $value): void

Set the same value for every player.

inc(string $name, int|float $delta, int $playerIdOrNo, bool $updateTableStat = false): void

Add to one player’s numeric statistic. With $updateTableStat = true, also add the delta to the table statistic with that name. Boolean statistics cannot be incremented.

incAll(string $name, int|float $delta): void

Add the delta to every player’s numeric statistic.

setUseNo(bool $useNo): void

Switch player arguments and getAll keys to player numbers when true. Configure this in the Game constructor if your game uses player numbers.

Example

// In setupNewGame, after initializing players:
$this->bga->playerStats->init('cardsPlayed', 0);

// During a player action (using the default player-ID mode):
$this->bga->playerStats->inc('cardsPlayed', 1, $playerId);

Optional statistics

Initialize the statistics that apply to the selected game variant. A statistic that is never initialized or updated stays undefined and is excluded from cumulative statistics; initializing it to zero records a real zero. See statistics initialization.

Updating a matching table statistic

If turns exists in both configuration sections, one player-statistic call can maintain both:

// In setupNewGame, after populating the player table:
$this->bga->playerStats->init('turns', 0, updateTableStat: true);

// After a player completes a turn:
$this->bga->playerStats->inc('turns', 1, $playerId, updateTableStat: true);

set, setAll, and incAll do not update a matching table statistic automatically. Use tableStats explicitly when those operations also need to change the table value.

Player-number mode and bulk reads

// In the Game constructor:
$this->bga->playerStats->setUseNo(true);

// During play:
$this->bga->playerStats->inc('turns', 1, $playerNo);
$turnsByPlayerNo = $this->bga->playerStats->getAll('turns');

These methods replace the player forms of initStat, setStat, incStat, and getStat. The modern set and inc take the name first, followed by the value or delta, then the player.