Accumulators

An accumulator is a special type of field that can store a sortable number on a player entity persistently between games. It is used for generating ranked leaderboards.

pub accumulator owner.NumLifetimeGames

pub game fn World.Main() {
    SpawnEachPlayer owner {
        NumLifetimeGames(delta=1, showOnLeaderboard=true)
    }
}

pub page fn owner.HomePage() {
    Content {
        P { "Loading leaderboard..." }
    }
    
    let leaderboard = await FetchLeaderboard([&NumLifetimeGames])
    Content {
        for player in leaderboard %%{
            P {
                %(player.PlayerName + " has played " + player.NumLifetimeGames + " games")
            }
        }
    }
}

Declaration

Every accumulator must have an object parameter, and the object parameter must be owner, representing the player who owns the accumulator.

The accumulator's name must begin with an uppercase letter.

accumulator owner.NumLifetimeGames

An accumulator may optionally be given an initial value.

accumulator owner.Rating = 1000

Accumulators can be declared as public using the pub keyword, which allows them to be accessed from all files in the program. Otherwise they are private and can only be accessed from within the same file. It is not possible to have two accumulators with the same name, even if they are both private and in separate files. Doing so will generate a compiler error. This is because the accumulator name forms a globally unique key which is used to look up the value from persistent storage.

pub accumulator owner.NumLifetimeGames = 0

Reading an accumulator

An accumulator can be read the same way as any other property:

let value = Rating // implicit object
let value = owner.Rating // or explicit object

The object parameter owner must be either a player entity, or one of the map entries returned by FetchLeaderboard.

It is possible to await on an accumulator to detect when it changes. Like all other await functions, it is possible to use with, on or once to handle the change.

with Rating {
    Transmission {
        P { "Your current rating: " + Rating }
    }
}

Modifying an accumulator

Accumulators can are modified by calling them as a function. Let's say we have defined an accumulator called ExampleAccumulator1:

pub accumulator owner.ExampleAccumulator1 = 0

ExampleAccumulator1 can be called as a function to increase, decrease or overwrite its value. The signature for calling an accumulator is as follows:

owner.ExampleAccumulator1(overwrite?, delta?, revertAfter?, resetAfter?, resetInterval?, showOnLeaderboard?)

owner (Entity): must refer to the player entity that owns the accumulator. If it is nullish, will do nothing.
overwrite (Number): if specified, will set the accumulator to this value. Overwriting an accumulator's value cancels all scheduled changes to the accumulator, for example from the revertAfter, resetAfter or resetInterval parameters.
delta (Number): if specified, will increase or decrease the accumulator by this amount.
revertAfter (Number): if specified, will revert the delta after this duration. This would normally be specified in minutes, hours or days. For example 30m, 4h, 30d. Reversions are processed once every minute by the server, and so any duration smaller than that will not happen exactly on time. The maximum allowable value is 365d, any values larger than this will be clamped. As revertAfter is processed by the server, if it occurs while a player is in a game, the player will only see the new value upon joining a new game.
resetAfter (Number): Schedules the accumulator to be reset to its initial value after this duration. A nullish value means the accumulator will never be reset to its initial value. This replaces any previously-defined scheduled reset. This parameter would normally be specified in minutes, hours or days. For example 30m, 4h, 30d. The maximum allowable value is 365d, any values larger than this will be clamped. Resets are processed once every minute by the server, and so any duration smaller than that will not happen exactly on time. As resetAfter is processed by the server, if a reset occurs while a player is in a game, they will only see the new value upon joining a new game.
resetInterval (Number): Schedules the accumulator to be reset to its initial value after this duration. If there is already a reset scheduled, this does nothing unless the new interval is shorter. If this parameter is nullish, deletes any previously-defined scheduled reset. This can be used to create a daily or weekly leaderboard, for example. This parameter would normally be specified in minutes, hours or days. For example 30m, 4h, 30d. The maximum allowable value is 365d, any values larger than this will be clamped. As resetInterval is processed by the server, if a reset occurs while a player is in a game, they will only see the new value upon joining a new game.
showOnLeaderboard (Boolean or Number): if specified, will include the player in any calls to FetchLeaderboard for this duration. If true, will show on the leaderboard permanently. If a Number, will show on the leaderboard for that duration.

Setting an accumulator's value

If you simply want to just set the accumulator to a specific value, without using any of the other extended parameters, you can simply use an assignment (=) statement:

owner.ExampleAccumulator1 = 123

Setting an accumulator this way removes any scheduled resets, reversions and leaderboard visibility. It is equivalent to calling the accumulator with the overwrite parameter, but with revertAfter, resetAfter, resetInterval and showOnLeaderboard set to null.

In general, if you are wanting to adjust an accumulator's value by a specific amount, you should call it with a delta instead, because that guarantees that no data is lost if multiple changes to the accumulator are made at the same time.

Resetting an accumulator's value

To reset an accumulator to its initial state, use the delete keyword:

delete owner.ExampleAccumulator1

This not only sets the accumulator to its initial value, it also removes any scheduled resets, reversions and leaderboard visibility.

Leaderboards

When modifying an accumulator by calling it as a function, there is a showOnLeaderboard parameter, which determines whether the player will be included when in the leaderboard for that particular accumulator. If the showOnLeaderboard parameter is set to true or false, the player will be included or excluded from the leaderboard permanently until the value is changed. However, it is also possible to limit the player to be shown on the leaderboard for a particular duration by passing a duration value to the showOnLeaderboard parameter. Players are expired from the leaderboard every minute by the server, and so durations much smaller than one minute will not happen exactly on time.

// add 5 rating, and show on leaderboard forever
Rating(delta=5, showOnLeaderboard=true)

// add 5 rating, and show on leaderboard for 30 days
Rating(delta=5, showOnLeaderboard=30d)

The FetchLeaderboard function is used to retrieve a list of players sorted by their accumulator values. It takes a list of accumulators to order by. The player must be included in the leaderboard for the first accumulator to be included in the list. The remaining accumulators are only used as tiebreakers. The leaderboard is always sorted from highest to lowest.

FetchLeaderboard returns an array of maps, where each map contains a PlayerName and UserId field, as well as a field for each accumulator.

let leaderboard = await FetchLeaderboard([&Rating])
for player in leaderboard %%{
    P {
        %(player.PlayerName + " has " + player.Rating + " rating and " + player.NumLifetimeGames + " games")
    }
}

Scoreboards

The Scoreboard function causes the game to display a list of currently online players and their accumulators.

pub game fn World.Main() {
    StatusContent {
        H3 { "Most Games" }
        Scoreboard(&NumLifetimeGames)
    }
}

Declaration​

Reading an accumulator​

Modifying an accumulator​

Setting an accumulator's value​

Resetting an accumulator's value​

Leaderboards​

Scoreboards​