swiftlys2/docs/api/releases/features/ai/

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:

  • Dispose is idempotent: calling it twice, or both explicitly and through using, is safe.
  • If you never call Dispose, the safe handle's finalizer releases the allocation at some later GC point - still dispose deterministically with using so the memory doesn't linger.
  • After disposal the container is unusable: every member that touches the allocation - APICEntityKeyValues.Address, Set*, Get* and APICEntityKeyValues.Has - throws ObjectDisposedException. Create a new CEntityKeyValues instead 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 typeSetterGetter
boolSetBoolGetBool
intSetInt32GetInt32
uintSetUInt32GetUInt32
longSetInt64GetInt64
ulongSetUInt64GetUInt64
floatSetFloatGetFloat
doubleSetDoubleGetDouble
stringSetStringGetString
nintSetPtrGetPtr
CUtlStringTokenSetStringTokenGetStringToken
ColorSetColorGetColor
VectorSetVectorGetVector
Vector2DSetVector2DGetVector2D
Vector4DSetVector4DGetVector4D
QAngleSetQAngleGetQAngle

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

MemberSignatureDescription
CEntityKeyValues()constructorAllocates the container
APICEntityKeyValues.Disposevoid Dispose()Releases the native allocation; safe to call more than once
APICEntityKeyValues.Addressnint Address { get; }Native address of the container
APICEntityKeyValues.Hasbool 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