From 94b89f7e685302b69f5101da007bca9fd45c32e0 Mon Sep 17 00:00:00 2001
From: tudor <7089284+tudddorrr@users.noreply.github.com>
Date: Sat, 21 Mar 2026 17:11:19 +0000
Subject: [PATCH 1/2] prop arrays docs
---
docs/godot/player-props.mdx | 74 ++++++++++++++++++++++++++++++++++++-
docs/unity/player-props.mdx | 74 ++++++++++++++++++++++++++++++++++++-
2 files changed, 146 insertions(+), 2 deletions(-)
diff --git a/docs/godot/player-props.mdx b/docs/godot/player-props.mdx
index f313a4b..369be7a 100644
--- a/docs/godot/player-props.mdx
+++ b/docs/godot/player-props.mdx
@@ -36,18 +36,27 @@ 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.
+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.
### 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).
+```gdscript
+var level := Talo.current_player.get_prop("level", "1")
+print("Level: ", level)
+```
+
### Setting props
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.
+```gdscript
+Talo.current_player.set_prop("level", "5")
+```
+
:::warning
Player props are not linearisable - simultaneous requests may be applied out of order. You should avoid setting or deleting props in `_process()` functions.
:::
@@ -57,3 +66,66 @@ Player props are not linearisable - simultaneous requests may be applied out of
Props can be deleted with `Talo.current_player.delete_prop()` or by using `Talo.current_player.set_prop()` and setting the value to `null`.
+
+```gdscript
+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.
+
+```gdscript
+var items := Talo.current_player.get_prop_array("inventory_items")
+print("Inventory: ", ", ".join(items))
+```
+
+### Setting prop arrays
+
+
+
+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.
+
+```gdscript
+Talo.current_player.set_prop_array("inventory_items", ["sword", "shield", "helmet"])
+```
+
+### Inserting into prop arrays
+
+
+
+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.
+
+```gdscript
+Talo.current_player.insert_into_prop_array("inventory_items", "helmet")
+```
+
+### Removing from prop arrays
+
+
+
+Use `Talo.current_player.remove_from_prop_array()` to remove a single value from a prop array.
+
+```gdscript
+Talo.current_player.remove_from_prop_array("inventory_items", "helmet")
+```
+
+### Deleting prop arrays
+
+
+
+Use `Talo.current_player.delete_prop_array()` to delete an entire prop array.
+
+```gdscript
+Talo.current_player.delete_prop_array("inventory_items")
+```
diff --git a/docs/unity/player-props.mdx b/docs/unity/player-props.mdx
index 203e219..1cf7fcd 100644
--- a/docs/unity/player-props.mdx
+++ b/docs/unity/player-props.mdx
@@ -50,18 +50,27 @@ private async void SearchPlayers()
## 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.
+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.
### Getting props
You can retrieve the current player's props using `Talo.CurrentPlayer.props`. To retrieve a single prop use `Talo.CurrentPlayer.GetProp()` (where you can also specify a fallback).
+```csharp
+var level = Talo.CurrentPlayer.GetProp("level", "1");
+Debug.Log($"Level: {level}");
+```
+
### Setting props
You can set props using `Talo.CurrentPlayer.SetProp()`. If a prop with specified key doesn't exist it'll be created, otherwise the existing prop with the same key will be updated.
+```csharp
+Talo.CurrentPlayer.SetProp("level", "5");
+```
+
:::warning
Player props are not linearisable - simultaneous requests may be applied out of order. You should avoid setting or deleting props in `Update()` functions.
:::
@@ -71,3 +80,66 @@ Player props are not linearisable - simultaneous requests may be applied out of
Props can be deleted with `Talo.CurrentPlayer.DeleteProp()` or by using `Talo.CurrentPlayer.SetProp()` and setting the value to `null`.
+
+```csharp
+Talo.CurrentPlayer.DeleteProp("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 `"inventoryItems"` is stored as `"inventoryItems[]"`).
+
+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.CurrentPlayer.GetPropArray()`. It returns an `IReadOnlyList` of the current values.
+
+```csharp
+var items = Talo.CurrentPlayer.GetPropArray("inventoryItems");
+Debug.Log($"Inventory: {string.Join(", ", items)}");
+```
+
+### Setting prop arrays
+
+
+
+Use `Talo.CurrentPlayer.SetPropArray()` to replace all values for a prop array key. Duplicate and empty values are ignored. The array must not be empty.
+
+```csharp
+Talo.CurrentPlayer.SetPropArray("inventoryItems", new[] { "sword", "shield", "helmet" });
+```
+
+### Inserting into prop arrays
+
+
+
+Use `Talo.CurrentPlayer.InsertIntoPropArray()` to add a single value to an existing prop array. If the value already exists it will not be added again.
+
+```csharp
+Talo.CurrentPlayer.InsertIntoPropArray("inventoryItems", "helmet");
+```
+
+### Removing from prop arrays
+
+
+
+Use `Talo.CurrentPlayer.RemoveFromPropArray()` to remove a single value from a prop array.
+
+```csharp
+Talo.CurrentPlayer.RemoveFromPropArray("inventoryItems", "helmet");
+```
+
+### Deleting prop arrays
+
+
+
+Use `Talo.CurrentPlayer.DeletePropArray()` to delete an entire prop array.
+
+```csharp
+Talo.CurrentPlayer.DeletePropArray("inventoryItems");
+```
From cee844df2466392583027abe591dc04e523ba1b2 Mon Sep 17 00:00:00 2001
From: tudor <7089284+tudddorrr@users.noreply.github.com>
Date: Sat, 21 Mar 2026 17:22:18 +0000
Subject: [PATCH 2/2] reference update param
---
docs/godot/player-props.mdx | 7 +++++++
docs/unity/player-props.mdx | 7 +++++++
2 files changed, 14 insertions(+)
diff --git a/docs/godot/player-props.mdx b/docs/godot/player-props.mdx
index 369be7a..3037a23 100644
--- a/docs/godot/player-props.mdx
+++ b/docs/godot/player-props.mdx
@@ -38,6 +38,8 @@ print("Found %s results: %s" % [search_page.count, ", ".join(identifiers)])
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](/docs/godot/settings-reference#debounce_timer_seconds).
+
### 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).
@@ -55,6 +57,11 @@ You can set props using `Talo.current_player.set_prop()`. If a prop with specifi
```gdscript
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
diff --git a/docs/unity/player-props.mdx b/docs/unity/player-props.mdx
index 1cf7fcd..591d269 100644
--- a/docs/unity/player-props.mdx
+++ b/docs/unity/player-props.mdx
@@ -52,6 +52,8 @@ private async void SearchPlayers()
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](/docs/unity/settings-reference#debouncetimerseconds).
+
### Getting props
You can retrieve the current player's props using `Talo.CurrentPlayer.props`. To retrieve a single prop use `Talo.CurrentPlayer.GetProp()` (where you can also specify a fallback).
@@ -69,6 +71,11 @@ You can set props using `Talo.CurrentPlayer.SetProp()`. If a prop with specified
```csharp
Talo.CurrentPlayer.SetProp("level", "5");
+
+// Set multiple props without triggering a sync each time
+Talo.CurrentPlayer.SetProp("level", "5", false);
+Talo.CurrentPlayer.SetProp("class", "warrior", false);
+Talo.CurrentPlayer.SetProp("xp", "1200"); // syncs here
```
:::warning