storybook/docs/reference/09-overview.md

Language Overview

The Storybook language enables narrative simulation through structured declarations of characters, behaviors, relationships, and events.

Philosophy

Storybook is a domain-specific language for narrative simulation, influenced by:

• Rust: Strong typing, explicit declarations, and clear ownership semantics
• C#: Object-oriented patterns with declarative syntax
• Python: Readable, accessible syntax that prioritizes clarity

The language balances technical precision with narrative expressiveness, making it accessible to storytellers while maintaining the rigor developers need.

Design Principles

1. Code as Narrative

Named nodes and prose blocks let code read like stories:

behavior Baker_MorningRoutine {
    choose daily_priority {
        then prepare_sourdough { ... }
        then serve_customers { ... }
        then restock_display { ... }
    }
}

2. Explicit is Better Than Implicit

Every declaration is self-documenting:

• Character fields show what defines them
• Behavior trees show decision structures
• Relationships name their participants

3. Progressive Disclosure

Simple cases are simple, complex cases are possible:

• Basic characters need just a name and fields
• Templates enable inheritance and reuse
• Advanced features (state machines, decorators) available when needed

4. Semantic Validation

The compiler catches narrative errors:

• Bond values must be 0.0..1.0
• Schedule blocks can't overlap
• Life arc transitions must reference valid states

Language Structure

Declaration Types

Storybook has 10 top-level declaration types:

Declaration	Purpose	Example
character	Define entities with traits and behaviors	A baker with skills and schedule
template	Reusable patterns with ranges	A generic NPC template
behavior	Decision trees for actions	How a character responds to events
life_arc	State machines for life stages	Apprentice → Baker → Master
schedule	Time-based activities	Daily routine from 6am to 10pm
relationship	Connections between entities	Parent-child with bond values
institution	Organizations and groups	A bakery with employees
location	Places with properties	The town square
species	Type definitions with traits	Human vs Cat vs Rabbit
enum	Named value sets	EmotionalState options

Value Types

Fields can contain:

• Primitives: 42, 3.14, "text", true
• Time: 08:30:00, 14:15
• Duration: 2h30m, 45s
• Ranges: 20..40 (for templates)
• Identifiers: OtherCharacter, path::to::Thing
• Lists: [1, 2, 3]
• Objects: { field: value }
• Prose blocks: ---tag\nMulti-line\ntext\n---

Expression Language

Conditions and queries use:

• Comparisons: age > 18, energy <= 0.5
• Equality: status is active, ready is true
• Logic: tired and hungry, rich or lucky, not ready
• Field access: self.health, other.bond
• Quantifiers: forall x in children: x.happy

Compilation Model

Source → AST → SBIR → Runtime

.sb files → Parser → Abstract Syntax Tree → Resolver → SBIR Binary

SBIR (Storybook Intermediate Representation) is a compact binary format that:

• Resolves all cross-file references
• Validates semantic constraints
• Optimizes for simulation runtime

Validation Layers

1. Lexical: Valid tokens and syntax
2. Syntactic: Correct grammar structure
3. Semantic: Type checking, reference resolution
4. Domain: Narrative constraints (bond ranges, schedule overlaps)

File Organization

Project Structure

my-storybook/
├── characters/
│   ├── baker.sb
│   └── family.sb
├── behaviors/
│   └── daily_routine.sb
├── world/
│   ├── locations.sb
│   └── institutions.sb
└── schema/
    ├── species.sb
    └── templates.sb

Import System

Use use statements to reference definitions from other files:

use schema::species::Human;
use schema::templates::Adult;

character Baker: Human from Adult {
    // ...
}

Resolution order:

1. Same file
2. Explicitly imported
3. Error if not found

Quick Reference

Character Declaration

character Name: Species from Template {
    field: value
    field: value
    ---prose_tag
    Text content
    ---
}

Behavior Tree

behavior Name {
    choose label {           // Selector
        then label { ... }   // Sequence
        if (condition)       // Condition
        ActionName          // Action
        include path        // Subtree
    }
}

Life Arc

life_arc Name {
    state StateName {
        on condition -> NextState
    }
}

Schedule

schedule Name {
    08:00 -> 12:00: activity { }
    12:00 -> 13:00: lunch { }
}

Relationship

relationship Name {
    Person1 as role
    Person2 as role
    bond: 0.85
}

Next Steps

Dive deeper into each declaration type:

• Characters - Detailed character syntax
• Behavior Trees - Complete behavior node reference
• Decorators - All decorator types
• Life Arcs - State machine semantics
• Schedules - Time-based planning
• Relationships - Connection modeling
• Other Declarations - Templates, institutions, etc.
• Expressions - Full expression language
• Value Types - All field value types
• Validation - Error checking rules

---

Philosophy Note: Storybook treats narrative as data. Characters aren't objects with methods - they're declarations of traits, connected by behaviors and relationships. This separation enables rich analysis, modification, and simulation of narrative worlds.