DTO rules

DTOs are plain C# types used as nested state, action parameters, action return values, or event payloads.

Supported shape

Declare the data as public properties:

public sealed class InventoryItem
{
    public string Id { get; set; } = "";
    public string Name { get; set; } = "";
    public int Count { get; set; }
}

Common supported types include:

• string, bool, numeric types
• enums
• DTO classes and structs
• arrays and lists
• dictionaries with string, integer, or enum keys and supported value types

Avoid exposing Unity engine objects, services, delegates, file handles, or runtime-only references across the bridge. The state-only exceptions are Texture2D, Sprite, and RenderTexture; see Unity image sources. These image types are not supported in action parameters, action return values, or event payloads.

64-bit integers

C# long and ulong become TypeScript bigint, preserving their full range. Use bigint literals such as 1n for arithmetic and String(value) for display. JSON.stringify cannot serialize a bigint directly; convert it to a string when producing JSON. Use a C# string if an ID only needs to be treated as text.

Naming

C# names are converted to camelCase in TypeScript:

public int CurrentHealth { get; set; }

bridge.currentHealth;

Use [BridgeName] only when you must preserve a different UI-facing name.

Enums

Enums appear in TypeScript as string values:

public enum Screen
{
    MainMenu,
    Hud
}

type Screen = 'MainMenu' | 'Hud';

Nulls

Initialize nested state objects and collections before Loom starts. If a value can be null, handle that case in the UI before reading its properties. See Nested state for when updates begin.

After changing DTOs or enums, follow Change the contract.