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

# Integration Guide

This chapter covers how to integrate Storybook into larger systems – game engines, simulation frameworks, and custom applications.

## Architecture Overview

Storybook operates in two phases:

1. Compile time: `.sb` files are parsed, validated, and compiled into SBIR
2. Runtime: A simulation engine consumes SBIR and drives character behavior

                        Compile Time                    Runtime
    .sb files → [Storybook Compiler] → SBIR → [Simulation Engine] → Character Actions

## The Storybook Compiler

The compiler is a Rust library and CLI tool that processes `.sb` files.

### CLI Usage

    # Compile a directory of .sb files
    storybook compile path/to/project/

    # Compile with output path
    storybook compile path/to/project/ -o output.sbir

    # Validate without producing output
    storybook check path/to/project/

### As a Library

The compiler can be embedded as a Rust dependency:

    #![allow(unused)]
    fn main() {
    use storybook::syntax::parse_file;
    use storybook::resolve::resolve_files;

    // Parse .sb files into ASTs
    let ast = parse_file(source_code)?;

    // Resolve across multiple files
    let resolved = resolve_files(vec![ast1, ast2, ast3])?;

    // Access resolved data
    for character in resolved.characters() {
        println!("{}: {:?}", character.name, character.fields);
    }
    }

### Key Types

The resolved output provides these primary types:

Type | Description
--- | ---
`ResolvedFile` | Container for all resolved declarations
`ResolvedCharacter` | Character with merged species/template fields
`ResolvedBehavior` | Behavior tree with resolved subtree references
`ResolvedLifeArc` | State machine with validated transitions
`ResolvedSchedule` | Schedule with resolved time blocks
`ResolvedRelationship` | Relationship with resolved participant references
`ResolvedInstitution` | Institution with resolved fields
`ResolvedLocation` | Location with resolved fields
`ResolvedSpecies` | Species with resolved includes chain
`ResolvedEnum` | Enum with variant list

## Runtime Integration

### Behavior Tree Execution

Runtimes are responsible for:

1. Tick-based evaluation: Call the behavior tree root each frame/tick
2. Action execution: Interpret action nodes (e.g., `MoveTo`, `Attack`)
3. Condition evaluation: Evaluate expression nodes against current state
4. Decorator state: Maintain timer/counter state for stateful decorators

### Life Arc Execution

1. Track the current state for each life arc instance
2. Evaluate transition conditions each tick
3. Execute on-enter actions when transitioning
4. Maintain state persistence across ticks

### Schedule Execution

1. Get the current simulation time
2. Find the matching schedule block (considering temporal constraints and recurrences)
3. Execute the associated behavior tree action

### Relationship Queries

Provide APIs for querying the relationship graph:

- Find all relationships for a character
- Get bond strength between two entities
- Query perspective fields (self/other)

## LSP Integration

Storybook includes a Language Server Protocol (LSP) implementation for editor support:

- Hover information: Documentation for keywords and declarations
- Go to definition: Navigate to declaration sources
- Diagnostics: Real-time error reporting
- Completions: Context-aware suggestions

The LSP server reuses the compiler’s parser and resolver, providing the same validation as the CLI.

### Editor Setup

The Storybook LSP works with any editor that supports LSP:

- VS Code: Via the Storybook extension
- Zed: Via the zed-storybook extension
- Other editors: Any LSP-compatible editor

## Tree-sitter Grammar

A Tree-sitter grammar is provided for syntax highlighting and structural queries:

    tree-sitter-storybook/
      grammar.js          # Grammar definition
      src/                # Generated parser

The Tree-sitter grammar supports:

- Syntax highlighting in editors
- Structural code queries
- Incremental parsing for large files

## File Organization for Integration

Organize your project to support both authoring and runtime consumption:

    my-game/
      storybook/              # Storybook source files
        schema/
          core_enums.sb
          templates.sb
          beings.sb
        world/
          characters/
          behaviors/
          relationships/
      assets/
        narrative.sbir        # Compiled output for runtime
      src/
        narrative_engine.rs   # Runtime that consumes SBIR

## Cross-References

- SBIR Format - The compiled binary format
- Validation Rules - What the compiler checks
- Language Overview - Compilation pipeline