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

Lexical: Valid tokens and syntax
Syntactic: Correct grammar structure
Semantic: Type checking, reference resolution
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:

Same file
Explicitly imported
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.

Storybook Language Guide