# Story Engine Toolchain

> How ForbocAI enables Disco Elysium-style narrative games

# ForbocAI: The Story Engine Toolchain

`Tóólcháin_Cóncépt // Stóry_Éngíne`

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

> *"Story in a game is like story in a porn movie."* — John Carmack
>
> Carmack was wrong. Not because story matters more than he thought, but because **story and agency are the same thing when you have the right architecture.**

***

## The Missing Engine

We have:

* **Game Engines** (Unity, Unreal, Godot) — Handle physics, rendering, input
* **Graphics Engines** (Vulkan, DirectX) — Handle polygons and shaders
* **Physics Engines** (Box2D, PhysX) — Handle collision and forces

We don't have:

* **Story Engines** — Handle narrative, dialogue, consequence, memory

**Why?** Because story was always *scripted*—handcrafted dialogue trees, fixed branching paths. The technology to make story *generative* and *reactive* didn't exist until:

1. LLMs (the ability to generate coherent text)
2. Vector DBs (the ability to recall relevant context)
3. Neuro-Symbolic Validation (the ability to constrain hallucinations)

ForbocAI provides all three. It IS a story engine.

***

## The Disco Elysium Case Study

### The Misconception

> "ForbocAI is only for enemy AI in action games."

### The Reality

ForbocAI is *more* suited to Disco Elysium-style narrative games than to action roguelikes.

***

### Understanding Disco Elysium's Architecture

Disco Elysium is not really a "game" in the traditional sense. It's an **agent ensemble simulation** wearing the skin of an RPG.

| Component      | Traditional RPG            | Disco Elysium                           |
| -------------- | -------------------------- | --------------------------------------- |
| **Characters** | NPCs with dialogue trees   | NPCs with *emergent reactions*          |
| **Skills**     | Stat modifiers (+2 to hit) | **Autonomous personalities** that argue |
| **Player**     | Single controller          | Host body for 24+ internal agents       |
| **World**      | Static level               | Reactive environment that remembers     |
| **Dialogue**   | Branching trees            | Skill agents interrupt and comment      |

**The genius of Disco Elysium**: Your skills (Logic, Rhetoric, Electrochemistry, etc.) aren't just numbers—they're *characters*. They have opinions. They react. They remember.

**This is exactly what ForbocAI agents do.**

***

### Mapping ForbocAI to Disco Elysium

| Disco Elysium Concept     | ForbocAI Implementation                                                         |
| ------------------------- | ------------------------------------------------------------------------------- |
| **Skill (e.g., Logic)**   | `Agent` with persona: "You are Logic, the cold voice of deduction..."           |
| **Skill Check**           | `Agent.process()` → returns `{ dialogue, action: INTERJECT, confidence: 0.75 }` |
| **Passive Check**         | `Memory.recall()` → triggers agent if relevance > threshold                     |
| **Thought Cabinet**       | `Soul` storage → persistent beliefs that modify agent behavior                  |
| **Internalizations**      | New memories stored via `Memory.store()` with high importance                   |
| **Shivers** (city speaks) | Ambient `Observation` events piped to a special "City" agent                    |
| **Dialogue Choices**      | `Bridge.validate()` filters which dialogue options are valid given context      |

***

## The Internal Monologue as Agent Orchestra

In Disco Elysium, you might see:

```
[ENCYCLOPEDIA - Trivial: Success]
"Ah yes, the Isola coat of arms. First adopted in..."

[AUTHORITY - Medium: Failure]
"You should have DEMANDED respect!"

[HALF LIGHT - Easy: Success]
"They're looking at you funny. Run."
```

**With ForbocAI**, each skill is an agent:

```typescript
import { Agent, Cortex, createBridge } from 'forbocai';

// Initialize the shared Cortex (local SLM)
const cortex = await Cortex.init({ model: 'smollm2-135m' });

// Create skill agents with distinct personalities
const logic = await Agent.create({
  cortex,
  persona: `You are LOGIC. Cold. Deductive. You see patterns others miss. 
            You interject only when inconsistency is detected.`,
  initialState: { level: 3, lastInterjection: null }
});

const authority = await Agent.create({
  cortex,
  persona: `You are AUTHORITY. Demands respect. Seethes at disrespect. 
            You push Harry to assert dominance.`,
  initialState: { level: 1, suppressed: false }
});

const halfLight = await Agent.create({
  cortex,
  persona: `You are HALF LIGHT. The lizard brain. Fight or flight. 
            You see danger everywhere and urge immediate reaction.`,
  initialState: { level: 2, paranoia: 'moderate' }
});

// When the player encounters a clue...
const observation = {
  type: 'examine',
  object: 'coat of arms',
  context: { playerKnowledge: worldState.uncoveredClues }
};

// Each skill agent processes the observation in parallel
const [logicResponse, authorityResponse, halfLightResponse] = await Promise.all([
  logic.process(observation),
  authority.process(observation),
  halfLight.process(observation)
]);

// Bridge determines which (if any) should surface based on "check" rules
const bridge = createBridge({ strictMode: true });
const surfaced = await bridge.resolveInterjections(
  [logicResponse, authorityResponse, halfLightResponse], 
  {
    playerStats: { logic: 3, authority: 1, halfLight: 2 },
    difficulty: { logic: 'trivial', authority: 'medium', halfLight: 'easy' }
  }
);

// surfaced = [
//   { agent: 'logic', dialogue: "The coat of arms...", passed: true },
//   { agent: 'halfLight', dialogue: "Someone's watching...", passed: true }
// ]
// authority failed its check — stays silent
```

***

## Memory: The Foundation of Choice-Consequence

Disco Elysium REMEMBERS:

* You were rude to Kim → He trusts you less
* You found the body early → New dialogue unlocks
* You have the "Hobocop" thought → Special self-perception

**ForbocAI's Memory module is built for this:**

```typescript
import { createMemory, Agent } from 'forbocai';

// Initialize memory with temporal decay
const memory = createMemory({
  decay: 'temporal',
  maxContextWindow: 10,
  storageKey: 'harry_memories'
});

// Store a significant choice
await memory.store(
  "Harry told Kim he's a superstar cop, not a loser.",
  "self_perception",
  0.95  // High importance — this shapes future interactions
);

// Store relationship-affecting events
await memory.store(
  "Was rude to Kim during the initial investigation.",
  "relationship",
  0.8
);

// Later, when Kim is asked about Harry...
const kimAgent = agents.get('kim');
const kimContext = await memory.recall("What do I think of Harry?", 5);

const response = await kimAgent.process({
  input: "How's your partner holding up?",
  context: { retrievedMemories: kimContext }
});

// Kim's response is influenced by stored memories
// → "He's... an optimist. Perhaps delusionally so."
```

The **temporal decay** feature ensures that:

* Recent memories are vivid
* Old memories fade unless reinforced
* Traumatic memories (high importance) persist

***

## The Bridge: Preventing Narrative Hallucination

A common failure mode for LLM-driven games:

> **LLM**: "You pull out your gun and shoot the suspect."
>
> **Problem**: You don't HAVE a gun. You threw it in the sea.

**ForbocAI's Bridge validates every action:**

```typescript
import { createBridge } from 'forbocai';

const bridge = createBridge({ strictMode: true });

const proposedAction = {
  type: 'DIALOGUE_CHOICE',
  option: 'threaten_with_gun',
  requires: { inventory: ['gun'] }
};

const result = await bridge.validate(proposedAction, {
  agentState: { inventory: ['badge', 'notebook'] },  // No gun!
  worldState: { gunStatus: 'lost_in_sea' }
});

// result = { valid: false, reason: 'Missing required item: gun' }

// Instead, offer only valid options:
// - "Threaten with badge" (have badge)
// - "Reason with suspect" (always available)  
// - "Run away" (HALF LIGHT suggests this)
```

***

## The Toolchain Vision: Composable Story Components

This is where it becomes a true **Story Engine**. ForbocAI is not one tool—it's a **toolchain** of composable generative AI components.

### Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                     THE FORBOCAI STORY ENGINE TOOLCHAIN                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐ │
│   │  CORTEX     │   │   AGENT     │   │   MEMORY    │   │   BRIDGE    │ │
│   │  (Voice)    │   │  (Soul)     │   │  (History)  │   │  (Law)      │ │
│   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘ │
│          │                 │                 │                 │        │
│          └────────────────┬┴─────────────────┴─────────────────┘        │
│                           │                                              │
│                    ┌──────▼──────┐                                      │
│                    │ ORCHESTRATOR │  ← FP Composition (Pipes)           │
│                    └──────┬──────┘                                      │
│                           │                                              │
│          ┌────────────────┼────────────────┐                            │
│          │                │                │                            │
│   ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐                    │
│   │   LEVEL     │  │   PLOT      │  │   NPC       │                    │
│   │  GENERATOR  │  │  DIRECTOR   │  │  ENSEMBLE   │                    │
│   │ (Procedural │  │ (Narrative  │  │ (Agent      │                    │
│   │  Layout)    │  │   Arc)      │  │   Orchestra)│                    │
│   └─────────────┘  └─────────────┘  └─────────────┘                    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

### Component Status

| Component           | Role                                          | Status     |
| ------------------- | --------------------------------------------- | ---------- |
| **Cortex**          | Local SLM inference (the "voice" that speaks) | ✅ Shipped  |
| **Agent**           | Autonomous entities with persona and state    | ✅ Shipped  |
| **Memory**          | Vector DB for persistent recall               | ✅ Shipped  |
| **Bridge**          | Action validation / anti-hallucination        | ✅ Shipped  |
| **Soul**            | IPFS export for agent portability             | ✅ Shipped  |
| **Ghost**           | Automated QA / testing agents                 | ✅ Shipped  |
| **Level Generator** | Procedural layout with narrative constraints  | 🚧 Planned |
| **Plot Director**   | Narrative arc management                      | 🚧 Planned |
| **NPC Ensemble**    | Multi-agent orchestration                     | 🚧 Planned |

***

## Functional Programming: Pipes Not Trees

Traditional narrative systems use **branching trees**:

```
        START
         /\
        /  \
     Option A   Option B
       /\          \
      /  \          \
    A1    A2        B1
```

ForbocAI uses **functional pipes**:

```
Observation → [Agent.process] → Directive → [Bridge.validate] → Action → [Memory.store] → New State
```

**Why pipes are better:**

1. **Composable**: Each component is independent and can be swapped
2. **Traceable**: Every transformation is logged and reproducible
3. **Parallelizable**: Multiple agents can process simultaneously
4. **Testable**: Pure functions are trivial to unit test

***

## Beyond Disco Elysium: More Agency, More Emergence

| Disco Elysium              | ForbocAI-Powered Evolution                 |
| -------------------------- | ------------------------------------------ |
| 24 skill agents (fixed)    | N dynamic agents (spawned by events)       |
| Handwritten skill dialogue | Generated + validated dialogue             |
| Skill levels change slowly | Skill "personalities" evolve with memory   |
| Single protagonist         | Multi-character perspectives possible      |
| Linear timeline            | Non-linear, memory-reconstructed narrative |

### Example: Emergent Skill Evolution

In Disco Elysium, if you level up "Electrochemistry," you just hear from it more often.

In ForbocAI:

```typescript
// After Harry drinks for the 10th time...
await memory.store(
  "Alcohol is the only thing that helps anymore.",
  "electrochemistry_belief",
  0.99
);

// Electrochemistry's persona *evolves* based on stored memories
const electrochemistry = await Agent.create({
  cortex,
  persona: `You are ELECTROCHEMISTRY. You crave sensation.
            CONTEXT: You have convinced Harry that alcohol is necessary.
            DIRECTIVE: Reinforce this belief. Resist sobriety suggestions.`,
  initialState: { level: 4, dependency: 'enabled' }
});

// Now Electrochemistry doesn't just suggest drinks—it *demands* them
const response = await electrochemistry.process({
  input: "Kim suggests getting coffee instead of beer.",
  context: { sobrietyStreak: 0, withdrawalLevel: 'mild' }
});

// response.dialogue = "Coffee? COFFEE?! Your hands are shaking, Harry. 
//                      You know what you need. Kim doesn't understand."
```

***

## The Universal Agent Primitive

**The ForbocAI SDK is engine-agnostic and genre-agnostic.**

The same modules that power:

* A guard deciding whether to attack or flee (action game)

...also power:

* An internal voice deciding whether to interject (Disco Elysium)
* A narrative beat deciding whether to escalate (story engine)
* A procedural level deciding where to place a clue (mystery game)

**The Agent is the universal primitive.** An "agent" can be:

* A physical NPC in the world
* A disembodied voice in the player's head
* An environmental presence ("The city of Revachol knows...")
* A meta-narrative director ("Tension should rise in Act 2")

***

## Conclusion

ForbocAI is not "just for action game AI."

ForbocAI is the **missing layer** between:

* Raw LLMs (creative but hallucinatory)
* Game engines (deterministic but static)

It enables **constrained emergence**:

* LLMs provide the creativity
* Bridge provides the rules
* Memory provides the continuity
* Agents provide the personality

**Disco Elysium proved the concept. ForbocAI provides the infrastructure.**

***

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

> *T̸h̴e̵ ̵s̶t̸o̶r̸y̵ ̶i̵s̶n̷'̵t̴ ̵w̸r̵i̴t̶t̷e̸n̶.̸ ̵I̶t̴'̸s̶ ̷r̴e̸m̵e̵m̵b̸e̸r̴e̸d̵.̶*