TableCounter

TableCounter manages a single numeric value for the whole table, such as the current round or the number of remaining tokens. For a distinct value for each player, use PlayerCounter.

It can automatically update a front-end Counter when its value changes.

Creating a TableCounter

Create a counter through bga->counterFactory in the Game constructor:

$this->roundCounter = $this->bga->counterFactory->createTableCounter('round');

The factory accepts these parameters:

createTableCounter(string $name, ?int $min = 0, ?int $max = null): TableCounter

The default minimum is 0, with no maximum. Set either bound to null to remove it.

API

initDb(int $initialValue = 0) Creates database table if needed (bga_table_counters). Must be called from setupNewGame.

Parameters:

• int $initialValue initial value, if different than 0

get(): int Returns the current value of the counter.

set(int $value, ?\Bga\GameFramework\NotificationMessage $message): int Set the value of the counter, and send a notif (of type setTableCounter) 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

inc(int $inc, ?\Bga\GameFramework\NotificationMessage $message): int Increment the value of the counter, and send a notif (of type setTableCounter) 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 $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

fillResult(array &$result, ?string $fieldName = null) Updates the result object, to be used in the getAllDatas function.

Parameters:

• array &$result the object to update
• ?string $fieldName the field name to set in $result, if different from the counter name.

Notification arguments

The counter automatically supplies these notification arguments. Add only the other arguments needed by your message:

• name: the counter name
• value: the new value
• oldValue: the value before the update
• inc: the increment
• absInc: the absolute value of the increment, useful for messages describing a decrease

Example

To store and display the number of remaining tokens, import and declare the counter in the Game class:

use Bga\GameFramework\Components\Counters\TableCounter;

// Inside the Game class:
public TableCounter $remainingTokens;

Create it in the Game constructor:

$this->remainingTokens = $this->bga->counterFactory->createTableCounter('remainingTokens');

Initialize it in setupNewGame:

$this->remainingTokens->initDb(initialValue: 20);

In getAllDatas:

$this->remainingTokens->fillResult($result);

The value is sent directly in gamedatas, using the counter name by default. Pass a fieldName to fillResult to use a different field name.

Update it from an action method in a State class:

$this->game->remainingTokens->inc(-1);

Create the display element before initializing the front-end counter:

this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
    <span id="remaining-tokens-counter"></span>
`);
const counter = new ebg.counter();
counter.create('remaining-tokens-counter', {
    value: gamedatas.remainingTokens,
    tableCounter: 'remainingTokens',
});

The JS counter updates automatically when you call set or inc with notifications enabled.

Listening to counter notifications

Use notif_setTableCounter to update other parts of your interface when the value changes:

async notif_setTableCounter(args) {
    const { name, value, oldValue, inc, absInc } = args;
    if (name === 'remainingTokens') {
        // Update any other game elements that depend on this value.
    }
}