This is a documentation for Board Game Arena: play board games online !
PlayerCounter and TableCounter: Difference between revisions
No edit summary |
No edit summary |
||
| Line 14: | Line 14: | ||
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 <code>$this->playerScore->setAll(2)</code>. | 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 <code>$this->playerScore->setAll(2)</code>. | ||
$this->counterFactory->createPlayerCounter(string $name, ?int $min = 0, ?int $max = null, int $defaultValue = 0): PlayerCounter | '''$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 | '''$this->counterFactory->createTableCounter(string $name, ?int $min = 0, ?int $max = null, int $defaultValue = 0): TableCounter''' | ||
=== PlayerCounter === | === PlayerCounter === | ||
Revision as of 11:39, 1 October 2025
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
/**
* Initialize the DB elements. Must be called during game `setupNewGame`.
*/
public function initDb(array $playerIds) {
}
/**
* Returns the current value of the counter.
*
* @param int $playerId the player id
* @return int the value
* @throws UnknownPlayerException if $playerId is not in the player ids initialized by initDb
*/
public function get(int $playerId): int {
return 0;
}
/**
* Set the value of the counter, and send a notif to update the value on the front side.
*
* @param int $playerId the player id
* @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
* @throws UnknownPlayerException if $playerId is not in the player ids initialized by initDb
*/
public function set(int $playerId, 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 $playerId the player id
* @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
* @throws UnknownPlayerException if $playerId is not in the player ids initialized by initDb
*/
public function inc(int $playerId, int $inc, ?\Bga\GameFramework\NotificationMessage $message = new \Bga\GameFramework\NotificationMessage()): int {
return 0;
}
/**
* Return the lowest value.
*
* @return int the lowest value
*/
public function getMin(): int {
return 0;
}
/**
* Return the highest value.
*
* @return int the highest value
*/
public function getMax(): int {
return 0;
}
/**
* Return the values for each player, as an associative array $playerId => $value.
*
* @return array<int, int> the values
*/
public function getAll(): array {
return [];
}
/**
* Set the value of the counter for all the players, 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 setAll(int $value, ?string $message = '', array $customArgs = []): int {
return 0;
}
/**
* Updates the result object, to be used in the `getAllDatas` function.
* Will set the value on each $result["players"] sub-array.
*
* @param array $result the object to update.
* @param ?string $fieldName the field name to set in $result["players"], if different than the counter name.
*/
public function fillResult(array &$result, ?string $fieldName = null) {
}
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) {
}