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

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

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