Introduction

An overview of Obscurum AI — the idea, the architecture, and what the survivors can do.

AI survivors, indistinguishable from human. Obscurum populates a survival-game server with AI players that talk, remember, get tired, panic, hold grudges and team up — live, over proximity voice. To the people in the server, they're just other survivors.

Obscurum is a clean-room, game-agnostic AI-NPC brain. The reactive core runs deterministically with no network or GPU; a deliberative LLM tier and a full voice pipeline layer on top, every part optional and configurable from a single source of truth.

The idea

Most game bots are state machines reading canned lines. Obscurum's survivors are rolled from a full psychological model and behave like a real human at a keyboard — and they speak and listen over the game's own proximity voice. The product's whole thesis: you can't tell which survivors are AI.

Architecture at a glance

   ┌─────────────────────────┐        Layer A — embodiment (per game)
   │  Game server + @mod      │        DayZ / Rust / ARK Enforce/script mod:
   │  (Enforce / script)      │        senses → snapshot, intents → actions, VoN I/O
   └───────────┬─────────────┘
               │ HTTP (game-agnostic JSON bridge)        Layer B — transport
   ┌───────────┴─────────────┐
   │   brain  (Rust crate)    │        Layer C — reactive core (deterministic, GPU-free)
   │  world · threat · decide │        + Layer D — deliberative LLM tier (off the hot path)
   │  steering · relationships│
   │  psyche · memory · …     │
   └─────┬───────────────┬────┘
         │               │
   ┌─────┴─────┐   ┌─────┴───────────────┐
   │ LLM router│   │ voice pipeline (ops) │   in: VoN→STT · out: TTS→VoN · emotes · mic-fx
   │ SaaS/BYOK │   │ Fish · ElevenLabs    │
   │ /local    │   │ Kokoro · routing     │
   └───────────┘   └─────────────────────┘

The reactive tier always works on its own. Everything above it — dialogue, voice, emotions, memory, squads — is opt-in, gated per game by a FeaturePolicy and per bot by its profile.

Deep dive

The full four-layer stack, module list, and build roadmap live in Architecture.

What the survivors have

Area	What it does
Personality	Big Five (OCEAN) + rolled traits (patience, greed, vengefulness, humour…) → a D&D-style alignment. Every bot is a distinct person.
Human factors	Fatigue over a session, wandering focus, tilt after deaths, AFK in a bush, breaks, log-off near bedtime.
Emotion	Mood swings and discrete events — snapping, withdrawing, elation, panic — surfaced into the dialogue prompt.
Memory	Generative-agent memory (importance · recency · relevance) that scales past 10k events with chronological compaction.
Dialogue	Optional LLM tier, off the hot path, provider-agnostic, cost-tiered by cognition mode.
Voice	Decode players' proximity voice to text (VoN→STT, Opus) and speak back over VoN (TTS), emotional + multilingual, one consistent voice per character.
Goals & squads	Self-set standing goals; squads that mix bots and humans (to a bot, both are just other players).
Game knowledge	Novice → expert, injected into the prompt — no per-game knowledge base required.
Economy	Cached phrase pool, per-bot speech budgets, cost-tiered cognition (Reactive→Chatter→Respond→Plan).
Safety	Prompt-injection input fence + an output guard that drops any line breaking character or leaking the prompt.
Per-game	One brain, many games; a config bundle exposes only the policies a game supports.

Repo layout

brain/          Rust crate — the reactive core + deliberative tier (the product's heart)
  src/          world, threat, decide, steering, relationships, psyche, human, memory,
                llm, llm_router, cognition_mode, global_goal, squad, dialogue, flavor,
                config, policy, speech_budget, speech_gate, phrase_cache, security, …
  examples/     personas.rs — roll bots, print alignments, drive a live emotional snap
ops/tools/voice/  voice pipeline + tooling (Python):
                von_tts (routing) · von_caps (per-model prompt augments) · von_emotes ·
                von_fx (mic realism) · fish_catalog · base_set (cost estimator) · obsconfig
dayz/ , mod-src/  Layer-A embodiment mod scaffold (@ObscurumAI, Enforce)
web/            premium landing page (self-contained index.html)
docs/           clean-room architecture, recon, performance, anti-cheat plan
docker-compose* brain sidecar deployment (dev / staging / prod)

Conventions

Deterministic: every roll is seeded; same seed ⇒ same bot, same timeline. No Date.now/rand in the core.
Serde-persistable: psyche, memory, relationships, squads, phrase cache survive restarts.
Tested + lint-clean: the full suite is green and clippy is warning-free before anything ships.
Single source of truth: one config bundle drives flavor, population, economy, voice and policy.
Swappable by traits: threat / decision / steering / transport each ship a default impl, replaceable without forking the orchestrator.
Clean-room IP: inspired by the genre, none of its code.

Status

The brain is feature-complete and green. The remaining work is live in-game orchestration — wiring the Layer-A embodiment mod to drive mode-selection, planning and squad steering on a running modded server. Guardian anti-cheat is a later phase. See the Architecture page.