Biomata Engine Overview

Biomata Engine

Biomata Engine is an open-source Python runtime for autonomous agents in simulated environments. It decouples the simulation runtime from domain-specific logic — world models, agent brains, action handlers — through well-defined Protocol-based contracts. Connect any game engine (Unity, Godot, custom) via the open WebSocket protocol, or run standalone headless simulations from the CLI.

Apache 2.0 licensed. Self-hostable. No accounts required. Deterministic by default.

Key concepts

Biomata Engine separates what agents do from how they decide and what world they inhabit. Six core abstractions cover everything:

Concept	Interface	Responsibility
`World`	`src/contracts/world.py`	Owns or proxies world state. Provides observations per agent. Two modes: local-authoritative (Python owns state) or host-authoritative (game engine owns state).
`Brain`	`src/contracts/brain.py`	Async cognition. Receives observation + memory + actions, returns an `Intent`. Can be LLM, rule-based, scripted, or an RL policy.
`Memory`	`src/contracts/memory.py`	Per-agent episodic memory. `store()` each tick, `recall()` for brain context. Serializable for checkpoints.
`ActionHandler`	`src/contracts/action.py`	Pure function: maps `Intent` → `ActionResult` with state_mutations and optional engine_commands for the host.
`AgentStateExtension`	`src/contracts/state.py`	Domain-specific per-agent vitals (health, stress, energy). Engine calls `tick()` and `apply_mutations()` automatically.
`SocialSystem`	`src/contracts/social.py`	Inter-agent relationship graph. Updated via `side_effects` in `ActionResult`. Default: `WeightedGraphSocial`.
`ObservationProvider`	`src/contracts/observation.py`	Produces named observation slices merged into each agent's perception dict before brain call. Registered in `ObservationRegistry` with capability filtering and fault isolation.

Quick links

▶

Quickstart

Autonomous agents running in under 2 minutes. No Ollama required.

◻

Docker Quickstart

Full stack with docker compose up — engine, WebSocket server, engine-owned sim.

⬡

Examples

Engine-Owned and Host-Owned — two canonical simulations teaching dual ownership.

⬦

Unity SDK

C# package for Unity 6. BiomataManager, AgentClient, TickClient, sample scenes.

⟷

WebSocket Protocol

Engine-agnostic Protocol v1 spec. Implement it for any engine — not just Unity.

◎

Contracts

Protocol interfaces for World, Brain, Memory, Actions, State, and Social.

⊕

Plugins

OllamaLLMBrain, HostedWorld, SimpleMemory, ReplayBrain, and custom plugin authoring.

⟳

Contributing

Apache 2.0. How to write plugins, run tests, and submit a PR.

Authority models

Biomata Engine supports two orthogonal authority models that can be combined:

World authority

Mode	Who owns world state	Use case
Local-authoritative	Python (custom `World` implementation)	Self-contained simulations run from CLI or tests
Host-authoritative	External engine (`HostedWorld`)	Unity/Unreal integration — host pushes observations, Python runs cognition, commands flow back

Tick authority

Mode	Who calls tick	Use case
HOST_DRIVEN	Client sends `tick` request	Unity FixedUpdate, Unreal Tick — synchronized to game loop
AUTONOMOUS	Backend runs `session.run()` loop	Headless research, batch runs — client subscribes to events

Quick install

bash

# Clone and install (no external dependencies)
git clone https://github.com/smithd36/biomata-engine.git
cd biomata-engine
pip install -e ".[websocket]"

# Engine-Owned — 3 pre-declared agents, no Ollama required
biomata-ws --config examples/engine_owned/sim.yaml --port 8765

# Host-Owned — backend starts empty; Unity registers agents at runtime
biomata-ws --config examples/host_owned/sim.yaml --port 8765

Start here

Both examples use IdleBrain — a deterministic brain that requires no external dependencies. Swap in OllamaLLMBrain in the YAML when you're ready to add language model cognition. Ollama is an optional upgrade, not a requirement.

Repository structure

text

biomata-engine/
  src/
    contracts/          World, Brain, Memory, Action, State, Social, Snapshot, Observation protocols
    engine/             Simulation, AgentRuntime, Scheduler, EventBus, ActionRegistry
                        ObservationRegistry, ConversationInbox
    service/            SimulationSession, DTOs, EventStreamAdapter
    transport/
      websocket/        WebSocketServer, ConnectionHandler, Protocol v1
    plugins/
      builtin/          OllamaLLMBrain, IdleBrain, SimpleMemory, WeightedGraphSocial
                        ReplayBrain, JSONReplayRecorderSubscriber
                        Observation providers (SimulationTime, SocialContext, IncomingMessages)
      external/         HostedWorld
    cli/                Command-line entry points
  examples/
    engine_owned/       3 pre-declared agents, BindToExisting ownership model
    host_owned/         Empty backend, CreateAtRuntime ownership model
  unity_sdk/            C# Unity 6 package
  docs/                 websocket-protocol.md (authoritative wire spec)
  tests/                pytest test suite