Biomata · Apache 2.0

Build autonomous
simulated agents.

A pluggable simulation runtime, documented WebSocket protocol, and Unity SDK. Drop in your world, connect your brain, ship agents. No SaaS. Self-hostable.

Read the Docs View on GitHub

Quickstart

Autonomous agents in under 2 minutes.

No Ollama. No API keys. No Unity required. Clone, install, run.

terminal 
# Clone and install (< 1 min)
git clone https://github.com/smithd36/biomata-engine.git
cd biomata-engine
pip install -e .

# Run the engine-owned demo — no dependencies
python -m src.cli.main run examples/engine_owned/sim.yaml
output 
Tick 1 | Aldric | patrol → gate_post    | holding position at gate
Tick 1 | Berna  | patrol → gate_post    | holding position at gate
Tick 1 | Silas  | trade  → market_stall | idle at market stall
Tick 2 | Aldric | patrol → gate_post    | holding position at gate
...
Full quickstart guide · Docker Compose alternative →

Deterministic by default

Seed the RNG, run the same config twice, get identical outcomes. Research-grade reproducibility without extra configuration.

Swap brains via YAML

One agent runs OllamaLLMBrain, another runs IdleBrain. Change the class path in config — no code changes required.

Engine-agnostic protocol

WebSocket Protocol v1 is fully documented. Unity implements it. You can implement it for Godot, Bevy, Unreal, or a browser client.

Local-first, no accounts

Clone and run. No cloud. No auth. No LLM required for the deterministic quickstart. Host it yourself.

Architecture

Three layers.
Plug in any of them.

Biomata separates what the simulation contains, how agents decide, and what they can do. Implement any layer with a Python Protocol class. The engine handles everything else.

World

Owns or proxies simulation state. Provides per-agent observations. Can be local Python or a remote game engine.

Brain

Async cognition. Receives observation + memory, returns an Intent. LLM, rule-based, scripted, or RL policy.

Actions

Maps Intent → ActionResult with state mutations and optional engine commands. Pure functions.

Full architecture docs
biomata-engine · protocol diagram
Biomata Engine Architecture TRANSPORT · WebSocket WebSocketServer · ConnectionHandler · Protocol SimulationController SERVICE LAYER SimulationSession · EventStreamAdapter · DTOs Simulation API ENGINE CORE Simulation · Scheduler · AgentRuntime · Registry · EventBus World Protocol Brain Protocol WORLD IMPLS HostedWorld BRAIN IMPLS OllamaLLMBrain · IdleBrain Unity / Unreal / Godot External Game Engine

Local-authoritative

Python owns world state. Run standalone from CLI.

Host-authoritative

Game engine owns state. HostedWorld proxies observations.

HOST_DRIVEN ticks

Client calls tick. Synchronized to game loop.

AUTONOMOUS ticks

Engine drives its own loop. Headless and batch-ready.

Who it's for

One runtime. Three use cases.

The shared problem: building autonomous agents in a simulated environment means rebuilding the same runtime infrastructure every time. Biomata is that runtime.

Game Developers

Stop scripting. Start simulating.

Drop the Unity SDK into your project, point agents at the Python runtime, and let Biomata handle cognition loops, memory, and action dispatch. Your NPCs start reasoning in minutes.

Unity SDK quickstart

AI Engineers

An agent runtime you can actually control.

Swap brains via YAML config. Drive ticks over WebSocket from any client. Replay deterministically. Extend with custom actions, worlds, and observation providers.

Protocol docs

Researchers

Reproducible by default.

Seeded RNG. Deterministic schedulers. Isolated cognition modules. Run the same sim with rule-based and LLM brains and compare results. Export decision traces for analysis.

View examples

Examples

Two simulations. Ready to run.

Engine Owned

START HERE

Three pre-declared agents (two guards, one merchant) with IdleBrain. No Ollama. First-run in under 2 minutes.

Agents 3 agents
Brain Deterministic
Requires Nothing
biomata-ws --config examples/engine_owned/sim.yaml --port 8765

Host Owned

Backend starts empty. Unity connects and registers agents at runtime — ideal for procedural spawning.

Agents Dynamic
Brain Deterministic
Requires Nothing
biomata-ws --config examples/host_owned/sim.yaml --port 8765
All examples with full source

What you get

Everything the runtime handles.

01

Pluggable Brains

Swap LLM, rule-based, scripted, or RL cognition via YAML config. One agent can run OllamaLLMBrain; another runs IdleBrain.

02

Open Protocol

WebSocket Protocol v1 is fully documented and engine-agnostic. Unity SDK implements it. Implement it for any engine.

03

Deterministic Replay

Seed the RNG, run the same config twice, get identical outcomes. Required for research and debugging.

04

Composable Worlds

Local-authoritative (Python owns state) or host-authoritative (Unity/engine owns state). Same agent runtime either way.

05

Self-Hostable

Clone the repo, install with pip, run. No accounts. No cloud dependency. No LLM required for the deterministic quickstart.

Open Source

Built in the open.
Apache 2.0.

The engine and Unity SDK are fully open source. Fork it, extend it, build your own worlds and brains. Contributions welcome — especially protocol client implementations for other engines.

View on GitHub Contributing guide
License Apache 2.0 Use commercially. Fork freely.
Engine version v0.5.0 Pre-1.0. Expect iteration.
Runtime Python 3.11+ Protocol classes + asyncio
Unity SDK Unity 6 C# package, host-authoritative
Quickstart < 2 min No Ollama, no accounts
Protocol WebSocket Engine-agnostic. Open spec.

Get Started

Clone and run in under 2 minutes.

No Ollama required. Start with the engine-owned example, then swap in your own world, brain, or actions. 

git clone https://github.com/smithd36/biomata-engine.git
cd biomata-engine && pip install -e .
python -m src.cli.main run examples/engine_owned/sim.yaml
Full quickstart guide Star on GitHub