# Language Overview - Storybook Language Guide
Comprehensive documentation for the Storybook narrative simulation language

# 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.