Players
Accessing player information
The active player is the player whose turn it is. The current player is the person making the request. A request may come from an inactive player or a spectator, so these values are not interchangeable.
In state callbacks and actions, prefer the framework's injected player parameters where available.
getPlayerCount() / getPlayersNumber(): int
Return the number of players at the table. Before populating the player table in setupNewGame, use count($players) instead.
getActivePlayerId()
Return the stored active-player ID. This value alone does not establish whether that player is currently active: use it for single-active-player states, not to identify active players in a multiactive state. Older APIs may return an ID as a string; cast to int when passing it to a typed API.
getPlayerNameById($playerId) / getPlayerNameByNo(int $playerNo): string
Return a player's name by ID or by their seat number.
getPlayerColorById($playerId)
Return the player's hexadecimal color without a # prefix.
getPlayerNoById($playerId) / getPlayerIdByNo($playerNo)
Convert between player IDs and the fixed player numbers assigned at table creation.
loadPlayersBasicInfos(): array
Return cached player information keyed by player ID. Entries include player_name, player_color, and player_no, along with framework flags. This does not load custom columns added by your game.
$players = $this->loadPlayersBasicInfos();
$playerIds = array_keys($players);
foreach ($players as $playerId => $player) {
$name = $player['player_name'];
$color = $player['player_color'];
$playerNo = (int)$player['player_no'];
}
reloadPlayersBasicInfos(): void
Refresh cached player information after changing it during setup, for example after assigning colors.
getCurrentPlayerId()
Return the ID of the person making the request. With the optional flag, return null when there is no logged-in user. Do not depend on a current player in setup or zombie callbacks: those can run without a browser request.
isCurrentPlayerZombie()
Check whether the current player has left or been expelled. Keep zombie-specific decisions in the zombie callback; ordinary rule validation should work for both human and zombie actions.
Info
If your game uses the zombie functions to play random moves, you should never need this method. Treat zombie players like regular players outside the zombie functions.
isSpectator()
Return whether the current requester is outside the table's player list. Spectators must receive only public game data.
Players' turn order
player_no records a player's fixed seat in the natural table order. Do not change it to implement a custom turn order. Persist custom ordering separately, such as in a game column or a global value.
getNextPlayerTable()
Return a map from each player ID to the next player's ID, wrapping around at the end. Key 0 identifies the first player.
getPrevPlayerTable()
Return the corresponding previous-player map, without the special 0 entry.
getPlayerAfter($playerId) / getPlayerBefore($playerId)
Read the next or previous player ID in natural order.
getPlayerNoAfter(int $playerNo): int / getPlayerNoBefore(int $playerNo): int
Read the next or previous player number in natural order.
createNextPlayerTable($players, $bLoop = true)
Build a next-player map for a list of player IDs in your chosen order. This does not change the stored player order. With $bLoop = false, the final player maps to null instead of the first player. Key 0 identifies the first player in either mode.
$order = $this->createNextPlayerTable([3000, 2000, 1000], false);
// [3000 => 2000, 2000 => 1000, 1000 => null, 0 => 3000]
Reflection time
giveExtraTime($playerId, $specificTime = null)
Add thinking time for a player in a real-time game. It has no effect in turn-based play. The default increment follows the table's speed settings; an explicit value is in seconds and does not scale with game speed. Prefer the default.
Remaining time is capped at the table's maximum. Adding time while a player's clock is already full has no benefit. Additional time for beginners is doubled without doubling the cap.