Examples

Biomata Engine ships with two canonical Python examples and two Unity SDK samples. Each pair teaches one ownership model — pick the one that matches your project architecture.

Python examples: engine_owned, host_owned
Unity SDK samples: Engine Owned Demo, Host Owned Demo

Engine Owned

Source: examples/engine_owned/

The canonical Engine-Owned ownership example. Three agents (two guards, one merchant) are declared in sim.yaml using IdleBrain — no Ollama required. The backend ticks whether or not a Unity client is connected. This is the starting point for any project with a fixed NPC roster.

Run it

bash

biomata-ws --config examples/engine_owned/sim.yaml --port 8765

Configuration

The engine-owned example uses a roles system — role definitions bundle capabilities and brain config together so agents can be declared with a single role: reference.

yaml

# examples/engine_owned/sim.yaml (abbreviated)
engine:
  ticks: 99999
  seed:  1
  scheduler: simultaneous

world:
  class: src.plugins.external.world.HostedWorld

registry:
  class: src.plugins.builtin.ollama.registry.build_hosted_registry

roles:
  Guard:
    capabilities: [guard, patrol, authority]
    brain:
      provider: idle   # shorthand for IdleBrain
  Merchant:
    capabilities: [trade, social]
    brain:
      provider: idle

agents:
  - id: gate_guard_left
    name: Aldric
    role: Guard

  - id: gate_guard_right
    name: Berna
    role: Guard

  - id: gate_captain
    name: Hector
    role: Guard
    capabilities: [guard, patrol, authority, commander]  # additive: extends Guard's set

  - id: market_merchant
    name: Silas
    role: Merchant

  - id: villager_01
    name: Mira
    role: Villager

To swap any agent's brain to Ollama, change the role's brain.provider from idle to ollama — or override an individual agent's brain.class inline:

yaml

agents:
  - id: gate_guard_left
    name: Aldric
    role: Guard
    brain:
      class: src.plugins.builtin.ollama.brain.OllamaLLMBrain
      personality:
        traits: [vigilant, loyal]
        goals: [protect the gate, report threats]

In Unity, set Ownership Mode = BindToExisting on each NPC prefab and match the Agent ID field exactly to the id in the YAML. No code in HandleConnected() — agents bind themselves. See the Unity SDK Engine-Owned section for the full Inspector layout.

Host Owned

Source: examples/host_owned/

The canonical Host-Owned ownership example. The sim.yaml has no agents: block — the backend starts empty. Unity connects and registers agents at runtime; the backend creates them on demand. This is the starting point for any project with procedural spawning, level-load agent sets, or player-chosen brains.

Run it

bash

biomata-ws --config examples/host_owned/sim.yaml --port 8765

Configuration

yaml

# examples/host_owned/sim.yaml (abbreviated)
engine:
  ticks: 99999
  seed:  1
  scheduler: simultaneous

world:
  class: src.plugins.external.world.HostedWorld

registry:
  class: src.plugins.builtin.ollama.registry.build_hosted_registry

roles:
  Villager:
    capabilities: [social]
    brain:
      provider: ollama

# No agents: block — Unity registers agents at runtime via agent.register

In Unity, set Ownership Mode = CreateAtRuntime on each NPC prefab and fill in Brain Class. The coordinator calls agent.Configure() after Instantiate(); BiomataAgent.Start() fires RegisterAsync; BiomataAgent.OnDestroy() fires TryRemoveAsync. See the Unity SDK Host-Owned section for the full Inspector layout.

Unity SDK Samples

Both samples live in unity_sdk/samples/. Import via Package Manager → Biomata Simulation SDK → Samples → [Sample Name] → Import.

Engine Owned Demo

Source: unity_sdk/samples/EngineOwned/ · Backend: examples/engine_owned/sim.yaml

Demonstrates the BindToExisting ownership model. Three pre-declared agents (two guards, one merchant) tick from backend startup. Unity connects and binds visual shells — no register_agent RPC is sent. Requires no Ollama. The key pedagogical point is that HandleConnected() contains zero agent-management code.

Start the backend first — the simulation runs regardless of whether Unity is connected. Swap IdleBrain for OllamaLLMBrain in sim.yaml without touching any Unity code.

Host Owned Demo

Source: unity_sdk/samples/HostOwned/ · Backend: examples/host_owned/sim.yaml

Demonstrates the CreateAtRuntime ownership model. The backend starts empty. Unity connects, spawns prefabs, and registers agents via agent.Configure() + BiomataAgent.Start(). Destroying a prefab automatically unregisters the agent.

The AgentSpawnData[] inspector array drives spawning — designers can add NPC rows without code changes. The sample guards against double-spawn on reconnect. On disconnect, it intentionally does not implement a specific reconnect strategy — see the Transport docs for reconnect=true options.