Unity SDK

{
  "dependencies": {
    "com.biomata.sdk": "file:../path/to/biomata-engine/unity_sdk",
    "com.unity.nuget.newtonsoft-json": "3.2.1"
  }
}

pip install -e ".[websocket]"
biomata-ws --config examples/engine_owned/sim.yaml --port 8765

using Biomata.SDK;
using Biomata.SDK.Unity;
using Biomata.SDK.Models;
using System.Collections.Generic;
using UnityEngine;

public class NPCController : MonoBehaviour
{
    private async void Start()
    {
        var biomata = BiomataManager.Instance;

        // Register agent with idle brain (no Ollama needed for testing)
        await biomata.Client.Agents.RegisterAsync(new AgentRegistration
        {
            AgentId    = "npc_guard_01",
            AgentName  = "Guard",
            BrainClass = "src.plugins.builtin.idle_brain.brain.IdleBrain",
        });

        // Send one tick with agent observation
        var observations = new List<AgentObservationData>
        {
            new AgentObservationData("npc_guard_01",
                new Dictionary<string, object>
                {
                    ["location"] = "gatehouse",
                    ["health"]   = 100,
                })
        };

        TickResult result = await biomata.Client.Ticks.TickAsync(observations);

        foreach (var decision in result.Decisions)
        {
            Debug.Log($"{decision.AgentName}: {decision.Action} — {decision.OutcomeText}");
            foreach (var cmd in decision.EngineCommands)
                ApplyCommand(decision.AgentId, cmd);
        }
    }

    private void ApplyCommand(string agentId, Dictionary<string, object> cmd)
    {
        var type = cmd.GetValueOrDefault("type")?.ToString();
        if (type == "navigate")
        {
            // Move the NPC's NavMeshAgent, Rigidbody, etc.
        }
    }
}

var config = new BiomataConfig
{
    Host                      = "localhost",
    Port                      = 8765,
    UseTls                    = false,
    ConnectTimeoutSeconds     = 10f,
    DefaultCallTimeoutSeconds = 30f,
};

var client = new SimulationClient(config);
await client.ConnectAsync(cancellationToken);

// Sub-clients — available after ConnectAsync
client.Health        // HealthClient — liveness probes
client.Agents        // AgentClient — register/remove agents
client.Observations  // ObservationClient — push pre-tick observations
client.Ticks         // TickClient — execute ticks, pause, resume
client.Events        // EventStreamClient — real-time event subscriptions
client.Snapshots     // SnapshotClient — save/restore state

await client.DisconnectAsync();

// Access from any script
var manager = BiomataManager.Instance;

// C# events (fired on main thread)
manager.OnConnectionStateChanged += state => Debug.Log($"Connection: {state}");
manager.OnTickEnd        += ev => Debug.Log($"Tick {ev.Tick} complete");
manager.OnActionCompleted += ev => Debug.Log($"{ev.AgentId}: {ev.Data.GetString("action")}");
manager.OnStreamDisconnected += ex => Debug.LogWarning("Stream disconnected");
manager.OnStreamFailed += ex => Debug.LogError($"Stream failed: {ex.Message}");

// Connect manually (if ConnectOnStart = false)
await manager.ConnectAsync();

// Convenience tick (delegates to Client.Ticks.TickAsync)
TickResult result = await manager.TickAsync(observations, worldMetadata);

// Autonomous mode control
await manager.PauseAsync();
await manager.ResumeAsync();

var config = new BiomataConfig
{
    Host                      = "localhost",
    Port                      = 8765,
    UseTls                    = false,      // wss:// requires a valid server cert
    ConnectTimeoutSeconds     = 10f,
    DefaultCallTimeoutSeconds = 30f,
    Retry = new RetryConfig
    {
        MaxAttempts         = 8,
        InitialDelaySeconds = 0.5f,
        MaxDelaySeconds     = 30f,
        Multiplier          = 2f,
        JitterFraction      = 0.25f,
    }
};

// Derived address
string addr = config.Address; // "ws://localhost:8765"

// Read tick mode from transport after connect
var transport = (WebSocketTransport)client._transport;
var tickMode  = transport.ServerTickMode; // "host_driven" or "autonomous"

if (tickMode == "host_driven")
{
    // Call TickAsync — DO NOT call pause/resume
}
else if (tickMode == "autonomous")
{
    // Subscribe to events — DO NOT call TickAsync
    await client.Events.StartAsync(ct);
}

var reg = new AgentRegistration
{
    AgentId     = "npc_guard_01",
    AgentName   = "Guard",
    BrainClass  = "src.plugins.builtin.ollama.brain.OllamaLLMBrain",
    BrainConfig = new Dictionary<string, object>
    {
        ["llm_config"] = new Dictionary<string, object>
        {
            ["model"]       = "qwen2.5:14b",
            ["temperature"] = 0.8,
        },
        ["personality"] = new Dictionary<string, object>
        {
            ["traits"] = new[] { "strategic", "loyal" },
            ["goals"]  = new[] { "protect the keep" },
        }
    },
    MemoryClass  = "",
    MemoryConfig = null,
};

var obs = new AgentObservationData(
    agentId: "npc_guard_01",
    observation: new Dictionary<string, object>
    {
        ["location"]  = "gatehouse",
        ["health"]    = 100,
        ["nearby_agents"] = new[]
        {
            new Dictionary<string, object>
            {
                ["id"]        = "npc_bandit_01",
                ["name"]      = "Bandit",
                ["inventory"] = new Dictionary<string, object>(),
                ["ext"]       = new Dictionary<string, object>(),
            }
        }
    }
);

TickResult result = await client.Ticks.TickAsync(observations, worldMetadata);

result.Tick       // int — engine tick number
result.Decisions  // IReadOnlyList<AgentDecisionResult>
result.Errors     // IReadOnlyList<(string AgentId, string Message)>
result.AllCommands // IReadOnlyList<(string AgentId, Dictionary<string,object> Command)>

// O(1) lookup by agent ID
var decision = result.ForAgent("npc_guard_01");
if (decision != null)
{
    Debug.Log($"{decision.AgentName}: {decision.Action}");
    Debug.Log($"Outcome: {decision.OutcomeText}");
    foreach (var cmd in decision.EngineCommands)
        ApplyCommand(decision.AgentId, cmd);
}

decision.AgentId        // string
decision.AgentName      // string
decision.Action         // string — action name chosen by brain
decision.Parameters     // Dictionary<string, object>
decision.OutcomeText    // string — human-readable result
decision.EngineCommands // IReadOnlyList<Dictionary<string, object>>
decision.Error          // string | null — non-null if step threw an exception

sim.yaml defines agents
    ↓
Backend starts ticking (with or without Unity)
    ↓
Unity connects → BiomataAgent.MarkBoundToExisting()
    ↓
Visual shell receives decisions each tick

[Ownership]
  Mode:     BindToExisting
  ℹ Agent is pre-declared on the backend; no registration RPC is sent.

[Identity]
  Agent ID:  gate_guard_left   ← must match sim.yaml id exactly
  Name:      Aldric

[Debug]
  Auto Bind: ✓

// EngineOwnedManager.cs
private void HandleConnected()
{
    // Nothing. BiomataAgent.Start() calls MarkBoundToExisting() for each agent.
    // No register_agent RPC is ever sent in this mode.
}

Backend starts with no agents
    ↓
Unity connects → agent.register RPC for each prefab
    ↓
Backend creates agent (imports brain, initializes memory)
    ↓
Agent participates in ticks
    ↓
Prefab destroyed → agent.unregister RPC → backend removes agent

[Ownership]
  Mode:     CreateAtRuntime
  ℹ Unity owns this agent. Registered on connect, unregistered on destroy. Brain Class required.

[Identity]
  Agent ID:  scout_001
  Name:      Scout

[Role]
  Role:         patrol
  Capabilities: patrol

[Brain]
  Brain Class:  src.plugins.builtin.ollama.brain.OllamaLLMBrain
  Brain Config: {"model": "qwen2.5:14b"}

[Debug]
  Auto Register: ✓

// HostOwnedManager.cs
private void HandleConnected()
{
    SpawnAgents();
}

private void SpawnAgent(AgentSpawnData data)
{
    var go    = Instantiate(npcPrefab, data.position, Quaternion.identity);
    var agent = go.GetComponent<BiomataAgent>();

    agent.Configure(
        agentId:       data.agentId,
        displayName:   data.displayName,
        autoRegister:  true,
        ownershipMode: AgentOwnershipMode.CreateAtRuntime);
    // BiomataAgent.Start() fires RegisterAsync → backend creates the agent.
    // BiomataAgent.OnDestroy() fires TryRemoveAsync → backend removes the agent.
}

await biomata.Client.Agents.RegisterAsync(new AgentRegistration
{
    AgentId    = "scout_001",
    AgentName  = "Scout",
    BrainClass = "src.plugins.builtin.idle_brain.brain.IdleBrain",
    Reconnect  = true,   // safe to call even if already registered
});

sim.yaml defines:          Unity defines:
  gate_guard_left            player_summoned_companion_001
  gate_guard_right           player_summoned_companion_002
  market_merchant            (spawned from inventory, unique per session)
  (static, always there)

var manager = GetComponent<UnitySimulationManager>();

// Register your agent bridges
manager.RegisterBridge(guardBridge);
manager.RegisterBridge(archerBridge);

// Call from FixedUpdate or a coroutine
await manager.TickAsync();

public class MoveActionHandler : ActionHandlerBase
{
    [SerializeField] private NavMeshAgent _navMeshAgent;

    protected override string CommandType => "navigate";

    protected override void Execute(Dictionary<string, object> command)
    {
        float x = Convert.ToSingle(command.GetValueOrDefault("x", 0f));
        float z = Convert.ToSingle(command.GetValueOrDefault("z", 0f));
        _navMeshAgent.SetDestination(new Vector3(x, 0f, z));
    }
}

// UnitySimulationManager
var go  = new GameObject("SimulationManager");
_simMgr = go.AddComponent<UnitySimulationManager>();
_simMgr.Configure(host: "localhost", port: 8765, tickRate: 2f, autoConnect: false);

// UnityAgentBridge (one per NPC)
var bridge = npc.AddComponent<UnityAgentBridge>();
bridge.Configure(agentId: "guard_001", agentName: "Aldric", autoRegister: false);

// MoveActionHandler
var mover = npc.AddComponent<MoveActionHandler>();
mover.Configure(moveSpeed: 3.5f, arrivalThreshold: 0.8f, rotateSpeed: 360f);

// SpeakActionHandler
var speaker = npc.AddComponent<SpeakActionHandler>();
speaker.Configure(logToConsole: true, speechDuration: 4f);

// EventVisualizer
var viz = go.AddComponent<EventVisualizer>();
viz.Configure(showOverlay: true, showSpeechBubbles: true, showInteractionLines: true,
              maxEventLines: 20, toggleKey: KeyCode.F2);

var events = client.Events;

// Register handlers (dispatched on main thread via MainThreadDispatcher)
events.On("tick_end",         ev => Debug.Log($"Tick {ev.Tick} complete"));
events.On("action_completed", ev =>
{
    var action = ev.Data.GetString("action") ?? "?";
    Debug.Log($"{ev.AgentId} performed {action}");
});
events.On("agent_step_error", ev =>
    Debug.LogWarning($"Step error for {ev.AgentId}: {ev.Data.GetString("error")}"));

// Start streaming (subscribe_events + receive loop)
await events.StartAsync(cancellationToken);

// Disconnect handling
events.OnDisconnected += ex => Debug.LogWarning("Stream dropped");
events.OnFailed       += ex => Debug.LogError($"Stream failed: {ex.Message}");

// Stop
await events.StopAsync();

var snapshots = client.Snapshots;

// Capture current simulation state
SnapshotData snap = await snapshots.CaptureAsync();
Debug.Log($"Snapshot at tick {snap.Tick}, created {snap.CreatedAt}");

// Save to disk (optional — the blob is opaque)
PlayerPrefs.SetString("last_snapshot", snap.DataB64);

// Restore (can be called at any time while connected)
await snapshots.RestoreAsync(snap);
Debug.Log($"Restored to tick {snap.Tick}");