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")

Handling rejected props

Player prop updates support partial success. If an update contains a mix of valid and invalid props, the valid props will be set and only the invalid ones will fail (see rejection reasons).

You can listen for rejected props by connecting to the Talo.players.props_rejected signal:

func _ready() -> void:
	Talo.players.props_rejected.connect(_on_props_rejected)

func _on_props_rejected(rejected_props: Array[TaloRejectedProp]) -> void:
	for prop in rejected_props:
		# prop.key: the key of the rejected prop
		# prop.error: the rejection reason code (e.g. TaloRejectedProp.RejectionReason.PROP_VALUE_TOO_LONG)
		# prop.message: a human-readable description of the rejection
		# e.g. "Rejected prop 'username': Prop value exceeds 512 characters (PROP_VALUE_TOO_LONG)"
		print("Rejected prop '%s': %s (%s)" % [prop.key, prop.message, prop.error])

Prop rejection reasons

The TaloRejectedProp class exposes an error property of type TaloRejectedProp.RejectionReason:

Reason	Description
PROP_KEY_TOO_LONG	The prop key exceeds 128 characters
PROP_VALUE_TOO_LONG	The prop value exceeds 512 characters
PROP_ARRAY_TOO_LONG	The prop array exceeds 1000 items
PROP_CONTAINS_PROFANITY	The prop key or value contains profanity
PROP_KEY_RESERVED	The prop key is reserved by Talo

func _on_props_rejected(rejected_props: Array[TaloRejectedProp]) -> void:
	for rejected_prop in rejected_props:
		match rejected_prop.error:
			TaloRejectedProp.RejectionReason.PROP_KEY_TOO_LONG:
				push_warning("Key too long: %s" % rejected_prop.key)
			TaloRejectedProp.RejectionReason.PROP_VALUE_TOO_LONG:
				push_warning("Value too long for key: %s" % rejected_prop.key)
			TaloRejectedProp.RejectionReason.PROP_CONTAINS_PROFANITY:
				push_warning("Profanity detected in key: %s" % rejected_prop.key)
			_:
				push_warning("Prop '%s' was rejected: %s" % [rejected_prop.key, rejected_prop.message])