Skip to main content

Players and props

Accessing players​

read:players

After identifying a player, you can access the underlying player object using Talo.current_player. For the current player alias, you can use Talo.current_alias.

You can also find a player by their ID using Talo.players.find(). Players retrieved this way are read-only: you can only modify or take actions on behalf of a player that was previously identified.

Searching for players​

read:players

You can use Talo.players.search() to query players. This function accepts a single query parameter that will search your playerbase for matching player IDs, alias identifiers or prop values. You can use this function to find players by their username, their ID or if they have a prop with a specific value.

var search_page := await Talo.players.search("bob")
if search_page.count == 0:
	print("No players found")
	return

var identifiers = []
for player in search_page.players:
	identifiers.append(player.get_alias().identifier)

print("Found %s results: %s" % [search_page.count, ", ".join(identifiers)])

Getting and setting props​

Players can have a list of arbitrary properties that are persisted across all of their aliases. These props are identified by their unique key and can have any string value. Keys can be up to 128 characters long and values can be up to 512 characters long.

All functions that modify props accept an optional update parameter (default true) that controls whether the player is synced with Talo after the change. Set it to false to batch multiple changes and avoid redundant debounces.

Getting props​

You can retrieve the current player's props using Talo.current_player.props. To retrieve a single prop use Talo.current_player.get_prop() (where you can also specify a fallback).

var level := Talo.current_player.get_prop("level", "1")
print("Level: ", level)

Setting props​

write:players

You can set props using Talo.current_player.set_prop(). If a prop with specified key doesn't exist it'll be created, otherwise the existing prop with the same key will be updated.

Talo.current_player.set_prop("level", "5")

# Set multiple props without triggering a sync each time
Talo.current_player.set_prop("level", "5", false)
Talo.current_player.set_prop("class", "warrior", false)
Talo.current_player.set_prop("xp", "1200")  # syncs here
warning

Player props are not linearisable - simultaneous requests may be applied out of order. You should avoid setting or deleting props in _process() functions.

Deleting props​

write:players

Props can be deleted with Talo.current_player.delete_prop() or by using Talo.current_player.set_prop() and setting the value to null.

Talo.current_player.delete_prop("level")

Prop arrays​

Prop arrays allow you to store multiple values under a single key. Each item is stored as its own value (up to 512 characters each), with a maximum of 1000 items per array.

info

Array keys are internally suffixed with [] (e.g. a key of "inventory_items" is stored as "inventory_items[]").

When using the functions below, you should reference the key without the [] suffix.

Getting prop arrays​

You can retrieve all values for a prop array using Talo.current_player.get_prop_array(). It returns an Array[String] of the current values.

var items := Talo.current_player.get_prop_array("inventory_items")
print("Inventory: ", ", ".join(items))

Setting prop arrays​

write:players

Use Talo.current_player.set_prop_array() to replace all values for a prop array key. Duplicate and empty values are ignored. The array must not be empty.

Talo.current_player.set_prop_array("inventory_items", ["sword", "shield", "helmet"])

Inserting into prop arrays​

write:players

Use Talo.current_player.insert_into_prop_array() to add a single value to an existing prop array. If the value already exists it will not be added again.

Talo.current_player.insert_into_prop_array("inventory_items", "helmet")

Removing from prop arrays​

write:players

Use Talo.current_player.remove_from_prop_array() to remove a single value from a prop array.

Talo.current_player.remove_from_prop_array("inventory_items", "helmet")

Deleting prop arrays​

write:players

Use Talo.current_player.delete_prop_array() to delete an entire prop array.

Talo.current_player.delete_prop_array("inventory_items")