# Storybook Language Guide

> **Create rich narrative simulations through code that reads like stories.**

Welcome to the complete guide for the Storybook narrative simulation language! Whether you're a creative writer bringing characters to life or a developer building simulation systems, this documentation will help you master Storybook.

---

**⚠️ Alpha Software Notice**

Storybook is currently in **alpha** and under active development at [r3t Studios](https://r3t.io). While the core language features are stable and ready to use, you should expect:

- **New features** to be added as we expand the language capabilities
- **Minor syntax adjustments** as we refine the design based on real-world usage
- **API changes** in the compiled output format as we optimize for game engine integration

We're committed to a thoughtful path toward version 1.0. Breaking changes will be clearly documented, and we'll provide migration guides when syntax evolves. Your feedback during this alpha period is invaluable in shaping the language's future!

---

## What is Storybook?

Storybook is a **compiled simulation language** designed for **open-world, autonomous game simulations**. While it includes a basic embedded virtual machine for terminal-based debugging, it's built to be integrated into game engines and developed hand-in-hand with technical game developers.

Storybook defines characters, behaviors, relationships, and narrative events for autonomous agents in dynamic worlds. It bridges the gap between storytelling and technical simulation through:

- **Readable syntax** - Code that looks like natural descriptions, but compiles to efficient bytecode
- **Type system** - Species, concepts, and sub-concepts for compile-time validation
- **Behavior trees** - Named nodes you can read as stories, that drive AI decision-making
- **Prose blocks** - Embed narrative directly in definitions for context-aware storytelling
- **Rich semantics** - From simple traits to complex state machines and schedules
- **Game engine integration** - Designed to power autonomous NPCs in Unity, Unreal, Godot, and custom engines

## Choose Your Path

### 🎨 For Storytellers

**New to programming?** Start with the [Tutorial Track](tutorial/01-welcome.md) for a gentle, example-driven introduction. Learn by building a bakery simulation!

### 💻 For Developers

**Need technical precision?** Jump to the [Reference Guide](reference/09-overview.md) for complete syntax specifications and semantic details.

### ✨ For Everyone

**Want inspiration?** Browse the [Examples Gallery](examples/24-baker-family-complete.md) to see what's possible!

## What's New in v0.3

Storybook v0.3 introduces a **compile-time type system** for stronger validation and richer world modeling:

- **`species`** - Define base archetypes with default fields that characters inherit
- **`concept` / `sub_concept`** - Algebraic data types with dot notation (`sub_concept Cup.Size { Small, Medium, Large }`)
- **`definition`** - Compile-time pattern matching over concept variants
- **Template species inheritance** - Templates extend species for layered defaults (`template Person: Human { ... }`)
- **Life arc field requirements** - `life_arc Career requires { skill: Number }` validates fields at compile time

v0.3 is a clean break from v0.2. See the [Type System reference](TYPE-SYSTEM.md) for full details.

## Quick Start

```storybook
// Define a species with default fields
species Human {
    age: 0
    energy: 0.5
    mood: 0.5
}

// Template inheriting from species
template Baker: Human {
    baking_skill: 0.0..1.0
    specialty: "bread"
}

// Character from template
character Martha from Baker {
    age: 34
    baking_skill: 0.9
    specialty: "sourdough"

    ---backstory
    A master baker who learned from her grandmother
    and now runs the most popular bakery in town.
    ---
}

// Type-safe concepts
concept BakedGood
sub_concept BakedGood.Category { Bread, Pastry, Cake }

// Behavior trees
behavior BakingWork {
    choose daily_priority {
        then prepare_sourdough
        then serve_customers
        then restock_display
    }
}
```

[Continue to Tutorial →](tutorial/01-welcome.md)

## Documentation Structure

- **Part I: Getting Started** - Tutorials for learning Storybook
- **Part II: Complete Reference** - Technical specifications
- **Part III: Advanced Topics** - Patterns and integration
- **Part IV: Examples Gallery** - Complete working examples

## Getting Help

- **In-Editor**: Hover over keywords for quick help
- **Search**: Use the search box (top right) to find anything
- **Examples**: Working code is the best teacher!

---

**Ready to begin?** [Start with the Tutorial →](tutorial/01-welcome.md)
