Skip to content

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 GetPublicKV
SetPublicKV
GetPublicKV
SetPublicKV
Public authoritative everyone server GetPublicAuthoritativeKV GetPublicAuthoritativeKV
SetPublicAuthoritativeKV
Private owner and server owner and server GetPrivateKV
SetPrivateKV
GetPrivateKV
SetPrivateKV
Private authoritative owner and server server GetPrivateAuthoritativeKV GetPrivateAuthoritativeKV
SetPrivateAuthoritativeKV
Server only server server not available GetServerKV
SetServerKV
Client only owner owner GetClientKV
SetClientKV
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:

cl/App.cs
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}!"
                );
            }
        }
    }
);
sv/App.cs
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
            );
        }
    }
);
sh/Messages.cs
[Msgpack.Gen]
public partial record struct ExampleKvData(ulong counter, string someString);