storybook/docs/advanced/22-integration.md

# 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

```bash
# 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:

```rust
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](./21-sbir-format.md) - The compiled binary format
- [Validation Rules](../reference/19-validation.md) - What the compiler checks
- [Language Overview](../reference/09-overview.md) - Compilation pipeline