This is a documentation for Board Game Arena: play board games online !

PlayerCounter and TableCounter: Difference between revisions

From Board Game Arena
Jump to navigation Jump to search
No edit summary
No edit summary
Line 19: Line 19:


=== PlayerCounter ===
=== PlayerCounter ===
/**
;initDb(array $playerIds)
:Initialize the DB elements. Must be called during game `setupNewGame`.
:Parameters:
:* <code>array $playerIds</code> the player ids having the counter (usually, <code>array_keys($players)</code>, but you might want to add 0 for an automata)


<nowiki>*</nowiki> Initialize the DB elements. Must be called during game `setupNewGame`.
;get(int $playerId)<nowiki>:</nowiki> int
:Returns the current value of the counter for a player.
:Parameters:
:* <code>int $playerId</code> the player id
:Throws:
:* <code>UnknownPlayerException</code> if $playerId is not in the player ids initialized by initDb


<nowiki>*</nowiki>/
;set(int $playerId, int $value, ?\Bga\GameFramework\NotificationMessage $message)<nowiki>:</nowiki> int
:Set the value of the counter, and send a notif to update the value on the front side. Returns the new value.
:Parameters:
:* <code>int $playerId</code> the player id
:* <code>int $value</code> the new value
:* <code>?\Bga\GameFramework\NotificationMessage $message</code> the next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
:Throws:
:* <code>OutOfRangeCounterException</code> if the value is outside the min/max
:* <code>UnknownPlayerException</code> if $playerId is not in the player ids initialized by initDb


public function initDb(array $playerIds) {
;inc(int $playerId, int $inc, ?\Bga\GameFramework\NotificationMessage $message)<nowiki>:</nowiki> 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:
:* <code>int $playerId</code> the player id
:* <code>int $inc</code> the value to add to the current value
:* <code>?\Bga\GameFramework\NotificationMessage $message</code> the next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
:Throws:
:* <code>OutOfRangeCounterException</code> if the value is outside the min/max
:* <code>UnknownPlayerException</code> if $playerId is not in the player ids initialized by initDb


}
;getMin()<nowiki>:</nowiki> int
:Returns the lowest value.


/**
;getMax()<nowiki>:</nowiki> int
:Returns the highest value.


<nowiki>*</nowiki> Returns the current value of the counter.
;getAll()<nowiki>:</nowiki> array
:Return the values for each player, as an associative array $playerId => $value.


<nowiki>*</nowiki>
;setAll(int $value, ?\Bga\GameFramework\NotificationMessage $message)<nowiki>:</nowiki> 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:
:* <code>int $value</code> the new value
:* <code>?\Bga\GameFramework\NotificationMessage $message</code> the next notif to send to the front. Empty for no log, null for no notif at all (the front will not be updated).
:Throws:
:* <code>OutOfRangeCounterException</code> if the value is outside the min/max


<nowiki>*</nowiki> @param int $playerId the player id
;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:
:* <code>array &$result</code> the object to update
:* <code>?string $fieldName</code> the field name to set in $result["players"], if different than the counter name.


<nowiki>*</nowiki> @return int the value
===TableCounter===
 
<nowiki>*</nowiki> @throws UnknownPlayerException if $playerId is not in the player ids initialized by initDb
 
<nowiki>*</nowiki>/
 
public function get(int $playerId): int {
 
return 0;
 
}
 
/**
 
<nowiki>*</nowiki> Set the value of the counter, and send a notif to update the value on the front side.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @param int $playerId the player id
 
<nowiki>*</nowiki> @param int $value the new value
 
<nowiki>*</nowiki> @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).
 
<nowiki>*</nowiki> @param array $customArgs the additional args to add to the notification message. `name`, `value` and `oldValue` are sent by default.
 
<nowiki>*</nowiki> @return int the new value
 
<nowiki>*</nowiki> @throws BgaSystemException if the value is outside the min/max
 
<nowiki>*</nowiki> @throws UnknownPlayerException if $playerId is not in the player ids initialized by initDb
 
<nowiki>*</nowiki>/
 
public function set(int $playerId, int $value, ?\Bga\GameFramework\NotificationMessage $message = new \Bga\GameFramework\NotificationMessage()): int {
 
return 0;
 
}
 
/**
 
<nowiki>*</nowiki> Increment the value of the counter, and send a notif to update the value on the front side.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> Note: if the inc is 0, no notif will be sent.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @param int $playerId the player id
 
<nowiki>*</nowiki> @param int $inc the value to add to the current value
 
<nowiki>*</nowiki> @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).
 
<nowiki>*</nowiki> @param array $customArgs the additional args to add to the notification message. `name`, `value`, `oldValue`, `inc`, `absInc` are sent by default.
 
<nowiki>*</nowiki> @return int the new value
 
<nowiki>*</nowiki> @throws BgaSystemException if the value is outside the min/max
 
<nowiki>*</nowiki> @throws UnknownPlayerException if $playerId is not in the player ids initialized by initDb
 
<nowiki>*</nowiki>/
 
public function inc(int $playerId, int $inc, ?\Bga\GameFramework\NotificationMessage $message = new \Bga\GameFramework\NotificationMessage()): int {
 
return 0;
 
}
 
/**
 
<nowiki>*</nowiki> Return the lowest value.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @return int the lowest value
 
<nowiki>*</nowiki>/
 
public function getMin(): int {
 
return 0;
 
}
 
/**
 
<nowiki>*</nowiki> Return the highest value.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @return int the highest value
 
<nowiki>*</nowiki>/
 
public function getMax(): int {
 
return 0;
 
}
 
/**
 
<nowiki>*</nowiki> Return the values for each player, as an associative array $playerId => $value.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @return array<int, int> the values
 
<nowiki>*</nowiki>/
 
public function getAll(): array {
 
return [];
 
}
 
/**
 
<nowiki>*</nowiki> Set the value of the counter for all the players, and send a notif to update the value on the front side.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @param int $value the new value
 
<nowiki>*</nowiki> @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).
 
<nowiki>*</nowiki> @param array $customArgs the additional args to add to the notification message. `name`, `value` and `oldValue` are sent by default.
 
<nowiki>*</nowiki> @return int the new value
 
<nowiki>*</nowiki> @throws BgaSystemException if the value is outside the min/max
 
<nowiki>*</nowiki>/
 
public function setAll(int $value, ?string $message = <nowiki>''</nowiki>, array $customArgs = []): int {
 
return 0;
 
}
 
/**
 
<nowiki>*</nowiki> Updates the result object, to be used in the `getAllDatas` function.
 
<nowiki>*</nowiki> Will set the value on each $result["players"] sub-array.
 
<nowiki>*</nowiki>
 
<nowiki>*</nowiki> @param array $result the object to update.
 
<nowiki>*</nowiki> @param ?string $fieldName the field name to set in $result["players"], if different than the counter name.
 
<nowiki>*</nowiki>/
 
public function fillResult(array &$result, ?string $fieldName = null) {
 
}
 
=== TableCounter ===
/**
/**


Revision as of 12:47, 1 October 2025


Game File Reference


Useful Components

Official

  • Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
  • PlayerCounter and TableCounter: PHP components to manage counters.
  • Draggable: a JS component to manage drag'n'drop actions.
  • Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
  • ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
  • Scrollmap: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
  • Stock: a JS component to manage and display a set of game elements displayed at a position.
  • Zone: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
  • bga-animations : a JS component for animations.
  • bga-cards : a JS component for cards.
  • bga-dice : a JS component for dice.
  • bga-autofit : a JS component to make text fit on a fixed size div.
  • bga-score-sheet : a JS component to help you display an animated score sheet at the end of the game.

Unofficial


Game Development Process


Guides for Common Topics


Miscellaneous Resources

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 $playerIds the 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 $playerId the player id
Throws:
  • UnknownPlayerException if $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 $playerId the player id
  • int $value the new value
  • ?\Bga\GameFramework\NotificationMessage $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).
Throws:
  • OutOfRangeCounterException if the value is outside the min/max
  • UnknownPlayerException if $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 $playerId the player id
  • int $inc the value to add to the current value
  • ?\Bga\GameFramework\NotificationMessage $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).
Throws:
  • OutOfRangeCounterException if the value is outside the min/max
  • UnknownPlayerException if $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 $value the new value
  • ?\Bga\GameFramework\NotificationMessage $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).
Throws:
  • OutOfRangeCounterException if 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 &$result the object to update
  • ?string $fieldName the 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) {

}

Retrieved from "http:///index.php?title=PlayerCounter_and_TableCounter&oldid=26682"