Skip to main content

Users

FetchLeaderboard​

await FetchLeaderboard(fields, limit?=) -> array
warning

This function is only available from within a page. If called inside a game, it will just return an empty Array.

Returns a ranked leaderboard representing the top players in the game for a particular set of Accumulators.

Parameters:

  • fields (an Array of Accumulators): the Accumulators to fetch. The leaderboard entries will be sorted from highest-to-lowest by the first Accumulator in fields, then the remaining Accumulators will be used as tiebreakers if necessary.
  • limit (Number): the maximum number of entries to return. The limit is capped at 100 (the default).

Returns an Array representing the top limit entries from the leaderboard. Each element in the Array will be a Map with the following key-value pairs:

  • UserId: a string representing the player's unique identifier.
  • PlayerName: a string representing the player's display name.
  • Each accumulator in accumulators: a number representing the player's score in that Accumulator.

FetchUserAccumulators​

await FetchUserAccumulators([userId]) -> profile
warning

This function is only available from within a page. If called inside a game, it will just return an empty Map.

Returns a Map representing the user's profile. The Map will have the following key-value pairs:

  • UserId: a string representing the user's unique identifier.
  • PlayerName: a string representing the user's display name.
  • PremiumUserTier: a number representing the user's premium tier level, if they have one.
  • Each Accumulator: a number representing the user's score in that Accumulator. All available accumulators will be retrieved. If the user does not have a value for this Accumulator yet, reading it will return its initial value, which can be customized but defaults to 0.

If userId is nullish or no user exists with the given ID, returns undefined.

IsPremiumUser​

owner.IsPremiumUser -> boolean

Returns whether the owner player represents a user who has a premium subscription. If owner is not a player, looks up the Owner of the entity and returns their premium status instead. Returns undefined if owner is nullish.

IsUserLoggedIn​

owner.IsUserLoggedIn -> boolean

Returns whether the owner player represents a user who is logged in or not. Returned undefined if owner is nullish.

LoginIntent​

LoginIntent -> intent

Returns an intent to log in. The intent can be attached to a button to trigger the login process. Logging in will force the player to leave the current game or page in order to follow the login process.

Example:

Toolbar {
    Button(LoginIntent) { "Login" }
}

LogoutIntent​

LogoutIntent -> intent

Returns an intent to log out. The intent can be attached to a button to trigger the logout process. Logging out will force the player to leave the current game or page in order to follow the logout process.

Example:

Toolbar {
    Button(LogoutIntent) { "Logout" }
}

ManageAccountIntent​

ManageAccountIntent -> intent

Returns an intent to go to the account management page. The intent can be attached to a button to trigger it. Going to the account management page will force the player to leave the current game or page.

ManagePremiumIntent​

ManagePremiumIntent -> intent

Returns an intent to go to the Easel+ management page. This allows people to subscrbe, unsubscribe, and modify their Easel+ subscription. The intent can be attached to a button to trigger it. Navigating to the Easel+ management page will force the player to leave the current game or page.

OnlinePlayerScoreboard​

OnlinePlayerScoreboard(accumulator, [ui=])

Add a live scoreboard to the user interface. Unlike Scoreboard, this scoreboard will include all players currently online. This could be used to display who has achieved the most wins recently, for example.

  • accumulator (Accumulator): the property or accumulator to rank players by. This would normally be an Accumulator.
  • ui (UI): The user interface slot to which the scoreboard should be added.

Example:

pub accumulator owner.NumLifetimeWins = 0

pub fn World.Example1() {
    StatusContent {
        OnlinePlayerScoreboard(&NumLifetimeWins)
    }
}

PremiumBadge​

PremiumBadge(level=, [ui])

Creates a element that represents a particular level of Easel+. This can be used to communicate to players a minimum level that is required to unlock a feature.

  • level (Number): The level of Easel+ that the badge represents.
  • ui (UI): The slot in the user interface where the element will be inserted.

PremiumRewardLevel​

owner.PremiumRewardLevel -> number

Returns the cumulative reward level of the owner player's Easel+ subscription. You can use this property as a way to reward players for their long-term support of your game. When Easel+ players play your game, they contribute to your bandwidth quota, allowing your game reach more players.

The PremiumRewardLevel is cumulative and is basically equal to the number of tier-months the player has been subscribed. So if a player has been subscribed to Easel+ tier 1 for 10 months, their PremiumRewardLevel will be 10. If a player has been subscribed to Easel+ tier 5 for 3 months, their PremiumRewardLevel will be 15. The level is increased every time a player's payment for Easel+ completes successfully, and so from the moment their subscription begins, PremiumRewardLevel will be at least 1.

You can use SubscribeToPremiumIntent to direct players to subscribe to Easel+, and/or to purchase a once-off boost to bring them up to a specific level.

Returns 0 for players without a current premium subscription. This is done because Easel is a multiplayer game platform with continuous running costs, and the purpose of Easel+ and its rewards is to help cover these costs. If a player unsubscribes then resubscribes later, they will return to the same PremiumRewardLevel they had before.

If owner is not a player, looks up the Owner of the entity and returns their premium status instead. Returns undefined if owner is nullish.

PremiumUserTier​

owner.PremiumUserTier -> number

Returns the tier of the owner player's premium subscription.

You can use this to reward players for their support of your game. We generally recommend you use PremiumRewardLevel instead of this function, as the reward level is cumulative and so encourages long-term subscriptions.

Returns 0 for players without a premium subscription, 1 if the player is on the first tier, 2 for the second tier, and so on. If owner is not a player, looks up the Owner of the entity and returns their premium status instead.

Returns undefined if owner is nullish.

Scoreboard​

Scoreboard(propOrAccumulator, [ui=])

Add a live scoreboard to the user interface. This scoreboard will include all players in the current game, ranked by the given Prop or Accumulator indicated by propOrAccumulator. For a player to appear in the scoreboard, you must first set their respective Prop or Accumulator to a value.

This could be used to display who has shot down the most enemies, collected the most eggs, has the most points, for example.

  • propOrAccumulator (Accumulator): the property or accumulator to rank players by.
  • ui (UI): The user interface slot to which the scoreboard should be added.

Example:

pub prop owner.Score = 0

pub fn World.Main() {
    SpawnEachPlayer owner {
        owner.Score = 0 // must set the property once to appear on the scoreboard
    }
}

pub fn World.Example1() {
    StatusContent {
        Scoreboard(&Score)
    }
}

SubscribeToPremiumIntent​

SubscribeToPremiumIntent(level?, tier?=) -> intent

Returns an intent to prompt the user to subscribe to Easel+. The intent can be attached to a button to trigger it.

The level and tier parameters are optional. level is a cumulative number that increases each month the player is subscribed to Easel+, whereas tier refers to the current tier of the player's current subscription. We recommend you generally reward people based on their level as this encourages long-term subscriptions.

  • If the level parameter is provided, the player will be given the option to purchase a boost which will bring them up to the specified PremiumRewardLevel. If they are not already subscribed to Easel+, they will be offered a subscription to the first tier at the same time. The tier parameter will be ignored.

  • Otherwise, if the tier parameter is provided, the player will be offered to subscribe to the specified PremiumUserTier of Easel+.

  • If neither the level nor tier parameter is provided, the player will be offered to subscribe to the first tier of Easel+.

If the player chooses to make the purchase, they will be required to login first if they haven't already, then they will be sent to the checkout, which will force them to leave the current game or page. When they return to your game, various values such as PremiumRewardLevel will be updated.

When an Easel+ player plays your game, they boost your bandwidth quota, allowing your game to reach more players. For this reason, you may want to encourage players to subscribe to Easel+ by offering them exclusive content or features. Lock content behind PremiumRewardLevel, and use this SubscribeToPremiumIntent function with the level parameter to prompt players to upgrade when they try to access it.

UserId​

owner.UserId -> string

Returns the unique user ID for the owner player as a String. All human players have a user ID, even if they are not logged in. If the player is a bot, returns null. If owner is nullish or not a player Entity, returns undefined.

Username​

owner.Username -> string

Returns the username that has been registered to the owner player. If the player does not have a username, returns undefined. Usernames are globally unique across the Easel platform, and have to be specifically registered by the user, and so most players will not have a username. You can help your players register a username by giving them a link to the Manage Account page by creating a button with a ManageAccountIntent.

Returns undefined if owner is nullish or not a player entity.