Scripting state (key-value storage)¶
re.ecs.ScriptingStateComponent attaches arbitrary key-value pairs to
networked entities. Use it to replicate custom data like per-entity counters,
team membership, per-player progress or similar.
Keys are strings. The wrappers serialize the value to MessagePack, so the
stored type has to implement Msgpack.ISerde<T>. That is the case for a
record declared partial with [Msgpack.Gen], which is what the store
requires. The type is not stored with the value, only the raw bytes are.
Every entry lives in one of the stores below. The store decides who may read the pair and who may write it:
| Store | Readable by | Writable by | Client realm | Server realm |
|---|---|---|---|---|
| Public | everyone | everyone | GetPublicKVSetPublicKV |
GetPublicKVSetPublicKV |
| Public authoritative | everyone | server | GetPublicAuthoritativeKV |
GetPublicAuthoritativeKVSetPublicAuthoritativeKV |
| Private | owner and server | owner and server | GetPrivateKVSetPrivateKV |
GetPrivateKVSetPrivateKV |
| Private authoritative | owner and server | server | GetPrivateAuthoritativeKV |
GetPrivateAuthoritativeKVSetPrivateAuthoritativeKV |
| Server only | server | server | not available | GetServerKVSetServerKV |
| Client only | owner | owner | GetClientKVSetClientKV |
not available |
"Owner" is the client the entity is assigned to. "Authoritative" stores only contain entries the server owns. Clients can read them but not write or create.
All methods take the entity id and the key: GetPublicKV<T>(id, "state"),
SetPublicKV(id, "state", value).
How entries replicate¶
A value written in the client realm into a public or private store is sent to the server and replicated to all clients that may read it. If the store is private, the value will not be sent to other clients.
Same goes for values written in the server realm, with the special case of "Authoritative" stores. These can only be written by the server. Clients and the Server itself can trust that entries were produced on the server and not modified by clients. This is useful for distributing critical entity metadata without having to build Event handler/sender pairs for everything.
Server-only values never leave the server, client-only values never leave the client.
A write is applied immediately, but replication happens on the network tick.
Check Exists, then check for null
Queryre.ecs.ScriptingStateComponent.Exists(id) first
Every getter returns T? and yields null when the key has no value
or when the stored bytes do not deserialize into the T you asked for
Always handle null with a default of your own failure mode
[Msgpack.Gen]
public partial record struct PlayerState(ulong kills, string team);
re.Con.RegisterCommand(
"give-kill",
args =>
{
foreach (var id in re.EntitySystem.GetEntities())
{
if (!re.ecs.ScriptingStateComponent.Exists(id))
{
continue;
}
var state = re.ecs.ScriptingStateComponent.GetPublicKV<PlayerState>(id, "mybundle::state")
?? new PlayerState(0, "no-team");
state.kills += 1;
re.ecs.ScriptingStateComponent.SetPublicKV(id, "mybundle::state", state);
}
}
);
A few things to keep in mind:
- Key names are unique per store per entity and shared across bundles. Use unique names and ideally prefix them with your bundle or gamemode name to avoid collisions
- Values of 1 MiB or more are dropped by the receiving side, and a replicated store stops accepting keys once it holds about 1024 of them. Such writes are ignored to prevent denial of service
The exact wrapper list per realm is in the scripting API reference, under client and server.
Example¶
This example replicates an arbitrary string an and incrementing counter on every networked entity:
re.Con.RegisterCommand(
"getKV",
args =>
{
foreach (var id in re.EntitySystem.GetEntities())
{
if (!re.ecs.ScriptingStateComponent.Exists(id))
{
continue;
}
var entry =
re.ecs.ScriptingStateComponent.GetPrivateAuthoritativeKV<ExampleKvData>(
id,
"kv-private-set-from-server"
);
if (entry != null)
{
Console.WriteLine(
$"re.ecs.ScriptingStateComponent.GetPrivateAuthoritativeKV {id} -> {entry?.counter} {entry?.someString}!"
);
}
}
}
);
re.Con.RegisterCommand(
"setKV",
args =>
{
foreach (var id in re.EntitySystem.GetEntities())
{
if (!re.ecs.ScriptingStateComponent.Exists(id))
{
continue;
}
var entry =
re.ecs.ScriptingStateComponent.GetPrivateAuthoritativeKV<ExampleKvData>(
id,
"kv-private-set-from-server"
) ?? new ExampleKvData(0, "initial-data");
entry.counter += 1;
entry.someString = args[0];
re.ecs.ScriptingStateComponent.SetPrivateAuthoritativeKV(
id,
"kv-private-set-from-server",
entry
);
}
}
);