SplitScript reference / Unity

Unity

state provider

state Unity

Attaches to a Unity game and binds declared managed metadata schemas.

Automatic mode detects Windows IL2CPP and Windows, Linux, or macOS Mono runtimes. Mono uses measured runtime build identities when available, with platform version selection for unknown builds. macOS supports x86-64 and ARM64. Linux support requires x86-64; a player build ID is used only when the Mono runtime has no readable ID of its own. Use an explicit selector only when the target's metadata profile is known and automatic detection is inappropriate.

The read-only process value remains a native Process handle. Managed images and classes declared with image are the public managed-memory interface. Their reachable metadata is bound once before onAttach runs; scripts do not discover runtime images, classes, field offsets, or static tables themselves. The attachment-scoped unity value separately exposes native scene and hierarchy facilities.

A declared class name such as PlayerController is an immutable local snapshot type. PlayerController.Ref is a live remote reference. Following a live static or instance field is fallible and rereads replaceable object pointers on every state poll. Non-null class references validate the runtime class and accept subclasses; nullable nulls remain valid. Calling .snapshot() recursively reads all active fields transactionally. Class checks share bounded work and attachment-scoped ancestry caches. Direct scalar fields need no such class check; snapshots, strings, arrays, and instance-search results materialize owned values. Generated binders, readers, and runtime discovery are retained only when reachable from the script.

Examples

Detect the Unity backend automatically

state Unity ["game.exe"] {}

Read one transactional managed snapshot

image "Assembly-CSharp" {
    class GameManager {
        static GameManager instance;
        u32 score;
        bool finished;
    }
}

state Unity ["game.exe"] {
    manager: GameManager = GameManager.instance?.snapshot()?;
}

Read a managed component from the active scene hierarchy

state Unity ["game.exe"] {
    player = unity.scenes.active()?
        .find("World/Player")?
        .component<PlayerController>()?
        .snapshot();
}

image "Assembly-CSharp" {
    class PlayerController {
        u32 score;
    }
}

Value type

Contextual values