This is a documentation for Board Game Arena: play board games online !
PlayerCounter and TableCounter
Counters allow to manipulate numbers in the game. PlayerCounter is for counters that have a distinct value for each player (for example, the player money). TableCounter is for single values, like current round.
They both share similar functions, and they can update automatically the JS counter (see Counter "create" parameters).
You can initialize them using the counterFactory available in the Game class (and State classes) like this:
$this->roundCounter = $this->counterFactory->createTableCounter('round', defaultValue: 1);
$this->playerCredits = $this->counterFactory->createPlayerCounter('credits', defaultValue: 3);
Note that by default, they have a min to 0, no max, and a default value to 0, but you can change that in the create function.
Two PlayerCounter are available by default on the games, playerScore and playerScoreAux. As their name suggests, they will update the player_score and player_score_aux for you (and scoreCtrl on front-side), so you never need to update manually the scores on the DB. They don't have a min, and default is 0, so if you need to set a different initial value, call $this->playerScore->setAll(2).
$this->counterFactory->createPlayerCounter(string $name, ?int $min = 0, ?int $max = null, int $defaultValue = 0): PlayerCounter
$this->counterFactory->createTableCounter(string $name, ?int $min = 0, ?int $max = null, int $defaultValue = 0): TableCounter
PlayerCounter
- initDb(array $playerIds)
- Initialize the DB elements. Must be called during game `setupNewGame`.
- Parameters:
array $playerIdsthe player ids having the counter (usually,array_keys($players), but you might want to add 0 for an automata)
- get(int $playerId): int
- Returns the current value of the counter for a player.
- Parameters:
int $playerIdthe player id
- Throws:
UnknownPlayerExceptionif $playerId is not in the player ids initialized by initDb
- set(int $playerId, int $value, ?\Bga\GameFramework\NotificationMessage $message): int
- Set the value of the counter, and send a notif to update the value on the front side. Returns the new value.
- Parameters:
int $playerIdthe player idint $valuethe new value?\Bga\GameFramework\NotificationMessage $messagethe next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
- Throws:
OutOfRangeCounterExceptionif the value is outside the min/maxUnknownPlayerExceptionif $playerId is not in the player ids initialized by initDb
- inc(int $playerId, int $inc, ?\Bga\GameFramework\NotificationMessage $message): int
- Increment the value of the counter, and send a notif to update the value on the front side. Returns the new value. Note: if the inc is 0, no notif will be sent.
- Parameters:
int $playerIdthe player idint $incthe value to add to the current value?\Bga\GameFramework\NotificationMessage $messagethe next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
- Throws:
OutOfRangeCounterExceptionif the value is outside the min/maxUnknownPlayerExceptionif $playerId is not in the player ids initialized by initDb
- getMin(): int
- Returns the lowest value.
- getMax(): int
- Returns the highest value.
- getAll(): array
- Return the values for each player, as an associative array $playerId => $value.
- setAll(int $value, ?\Bga\GameFramework\NotificationMessage $message): int
- Set the value of the counter for all the players, and send a notif to update the value on the front side. Returns the new value.
- Parameters:
int $valuethe new value?\Bga\GameFramework\NotificationMessage $messagethe next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
- Throws:
OutOfRangeCounterExceptionif the value is outside the min/max
- fillResult(array &$result, ?string $fieldName = null)
- Updates the result object, to be used in the `getAllDatas` function. Will set the value on each $result["players"] sub-array.
- Parameters:
array &$resultthe object to update?string $fieldNamethe field name to set in $result["players"], if different than the counter name.
TableCounter
/**
* Initialize the DB elements. Must be called during game `setupNewGame`.
*/
public function initDb() {}
/**
* Returns the current value of the counter.
*
* @return int the value
*/
public function get(): int {
return 0;
}
/**
* Set the value of the counter, and send a notif to update the value on the front side.
*
* @param int $value the new value
* @param ?string $message the next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
* @param array $customArgs the additional args to add to the notification message. `name`, `value` and `oldValue` are sent by default.
* @return int the new value
* @throws BgaSystemException if the value is outside the min/max
*/
public function set(int $value, ?\Bga\GameFramework\NotificationMessage $message = new \Bga\GameFramework\NotificationMessage()): int {
return 0;
}
/**
* Increment the value of the counter, and send a notif to update the value on the front side.
*
* Note: if the inc is 0, no notif will be sent.
*
* @param int $inc the value to add to the current value
* @param ?string $message the next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
* @param array $customArgs the additional args to add to the notification message. `name`, `value`, `oldValue`, `inc`, `absInc` are sent by default.
* @return int the new value
* @throws BgaSystemException if the value is outside the min/max
*/
public function inc(int $inc, ?\Bga\GameFramework\NotificationMessage $message = new \Bga\GameFramework\NotificationMessage()): int {
return 0;
}
/**
* Updates the result object, to be used in the `getAllDatas` function.
*
* @param array $result the object to update.
* @param ?string $fieldName the field name to set in $result, if different than the counter name.
*/
public function fillResult(array &$result, ?string $fieldName = null) {
}