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:
```storybook
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:

```storybook
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
```storybook
character Name: Species from Template {
    field: value
    field: value
    ---prose_tag
    Text content
    ---
}
```

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

### Life Arc
```storybook
life_arc Name {
    state StateName {
        on condition -> NextState
    }
}
```

### Schedule
```storybook
schedule Name {
    08:00 -> 12:00: activity { }
    12:00 -> 13:00: lunch { }
}
```

### Relationship
```storybook
relationship Name {
    Person1 as role
    Person2 as role
    bond: 0.85
}
```

## Next Steps

Dive deeper into each declaration type:

- [Characters](10-characters.md) - Detailed character syntax
- [Behavior Trees](11-behavior-trees.md) - Complete behavior node reference
- [Decorators](12-decorators.md) - All decorator types
- [Life Arcs](13-life-arcs.md) - State machine semantics
- [Schedules](14-schedules.md) - Time-based planning
- [Relationships](15-relationships.md) - Connection modeling
- [Other Declarations](16-other-declarations.md) - Templates, institutions, etc.
- [Expressions](17-expressions.md) - Full expression language
- [Value Types](18-value-types.md) - All field value types
- [Validation](19-validation.md) - 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.