Entity Key Values
SwiftlyS2 provides APICEntityKeyValues (SwiftlyS2.Shared.EntitySystem) as a typed key-value container for entity spawn/configuration values.
Creating and Disposing
The default constructor allocates the container, and APICEntityKeyValues.Dispose releases it - so prefer using:
using var keyValues = new CEntityKeyValues();APICEntityKeyValues owns a safe handle that holds the native allocation (CEntityKeyValuesSafeHandle is internal, so you never create or dispose it yourself). Three consequences are worth knowing:
Disposeis idempotent: calling it twice, or both explicitly and throughusing, is safe.- If you never call
Dispose, the safe handle's finalizer releases the allocation at some later GC point - still dispose deterministically withusingso the memory doesn't linger. - After disposal the container is unusable: every member that touches the allocation - APICEntityKeyValues.Address,
Set*,Get*and APICEntityKeyValues.Has - throwsObjectDisposedException. Create a newCEntityKeyValuesinstead of reusing a disposed one.
Address Property
Exposes the native address of the container through APICEntityKeyValues.Address (read-only nint):
nint address = keyValues.Address;It's meant for interop that expects the raw pointer - don't cache it, since it stops being valid once the container is disposed.
Setting and Getting Values
A type-specific SetX/GetX pair exists for every supported type - GetX mirrors SetX 1:1, taking the same key and returning what was stored:
| Value type | Setter | Getter |
|---|---|---|
bool | SetBool | GetBool |
int | SetInt32 | GetInt32 |
uint | SetUInt32 | GetUInt32 |
long | SetInt64 | GetInt64 |
ulong | SetUInt64 | GetUInt64 |
float | SetFloat | GetFloat |
double | SetDouble | GetDouble |
string | SetString | GetString |
nint | SetPtr | GetPtr |
CUtlStringToken | SetStringToken | GetStringToken |
Color | SetColor | GetColor |
Vector | SetVector | GetVector |
Vector2D | SetVector2D | GetVector2D |
Vector4D | SetVector4D | GetVector4D |
QAngle | SetQAngle | GetQAngle |
Setters return void and take (string key, T value); getters take the key only and return the type from the table:
keyValues.SetBool("is_enabled", true);
keyValues.SetInt32("health", 100);
keyValues.SetUInt32("flags", 1u);
keyValues.SetInt64("large_value", 9223372036854775807);
keyValues.SetUInt64("ularge_value", 18446744073709551615UL);
keyValues.SetFloat("speed", 250.5f);
keyValues.SetDouble("precise_value", 3.14159265359);
keyValues.SetString("name", "example");
keyValues.SetPtr("pointer", nint.Zero);
keyValues.SetStringToken("token", new CUtlStringToken("token"));
keyValues.SetColor("color", new Color(255, 0, 0, 255));
keyValues.SetVector("position", new Vector(0, 0, 100));
keyValues.SetVector2D("position_2d", new Vector2D(10, 20));
keyValues.SetVector4D("position_4d", new Vector4D(1, 2, 3, 4));
keyValues.SetQAngle("angle", new QAngle(0, 90, 0));
int health = keyValues.GetInt32("health");Use APICEntityKeyValues.Has to check whether a key was set before reading it:
if (keyValues.Has("health"))
{
int storedHealth = keyValues.GetInt32("health");
}Generic Set and Get
Set<T>/Get<T> are the untyped entry points for the same types, useful when the value type is only known at runtime:
keyValues.Set<int>("health", 100);
keyValues.Set<Vector>("position", new Vector(0, 0, 100));
int health = keyValues.Get<int>("health");
Vector position = keyValues.Get<Vector>("position");Set<T> picks the matching typed setter from the runtime type of value, so boxing through a wider type still stores the underlying supported type. Get<T> matches typeof(T) exactly instead - keyValues.Get<object>("health") throws even though Set<object>("health", 100) worked.
Supported Generic Types
Set<T>/Get<T> support bool, int, uint, long, ulong, float, double, string, nint, CUtlStringToken, Color, Vector, Vector2D, Vector4D, QAngle.
Using an unsupported type with Set<T> or Get<T> throws InvalidOperationException.
Members
| Member | Signature | Description |
|---|---|---|
CEntityKeyValues() | constructor | Allocates the container |
| APICEntityKeyValues.Dispose | void Dispose() | Releases the native allocation; safe to call more than once |
| APICEntityKeyValues.Address | nint Address { get; } | Native address of the container |
| APICEntityKeyValues.Has | bool Has(string key) | Whether key is present in the container |
Set<T> | void Set<T>(string key, T value) | Stores value under key; throws InvalidOperationException for unsupported types |
Get<T> | T Get<T>(string key) | Reads the value stored under key; throws InvalidOperationException for unsupported types |
The fifteen typed Set*/Get* pairs listed above complete the surface. Once the container is disposed, every member except Dispose throws ObjectDisposedException.
Using with Entity DispatchSpawn
Commonly passed into DispatchSpawn/DispatchSpawnAsync (async for non-main-thread contexts) on a CEntityInstance. See Entity for creating entities.
CBaseEntity relay = Core.EntitySystem.CreateEntityByDesignerName<CBaseEntity>("logic_relay");
using var keyValues = new CEntityKeyValues();
keyValues.SetString("targetname", "sw_relay_01");
keyValues.SetBool("StartDisabled", false);
relay.DispatchSpawn(keyValues);
await relay.DispatchSpawnAsync(keyValues); // non-main-thread