Sienna Meridian Satterwhite
16deb5d237
BREAKING CHANGES: - Relationship syntax now requires blocks for all participants - Removed self/other perspective blocks from relationships - Replaced 'guard' keyword with 'if' for behavior tree decorators Language Features: - Add tree-sitter grammar with improved if/condition disambiguation - Add comprehensive tutorial and reference documentation - Add SBIR v0.2.0 binary format specification - Add resource linking system for behaviors and schedules - Add year-long schedule patterns (day, season, recurrence) - Add behavior tree enhancements (named nodes, decorators) Documentation: - Complete tutorial series (9 chapters) with baker family examples - Complete reference documentation for all language features - SBIR v0.2.0 specification with binary format details - Added locations and institutions documentation Examples: - Convert all examples to baker family scenario - Add comprehensive working examples Tooling: - Zed extension with LSP integration - Tree-sitter grammar for syntax highlighting - Build scripts and development tools Version Updates: - Main package: 0.1.0 → 0.2.0 - Tree-sitter grammar: 0.1.0 → 0.2.0 - Zed extension: 0.1.0 → 0.2.0 - Storybook editor: 0.1.0 → 0.2.0
3.0 KiB
The SBIR Binary Format
SBIR (Storybook Intermediate Representation) is the compiled binary format produced by the Storybook compiler. It transforms human-readable .sb files into an optimized, machine-consumable format for simulation runtimes.
Compilation Pipeline
.sb files → Lexer → Parser → AST → Resolver → SBIR Binary
- Lexer: Tokenizes raw text into tokens
- Parser: Builds an Abstract Syntax Tree (AST) from tokens
- Resolver: Validates, resolves cross-references, merges templates, and produces SBIR
What SBIR Contains
SBIR represents the fully resolved state of a Storybook project:
- Characters: All fields resolved (species + templates merged, overrides applied)
- Behaviors: Behavior trees with all subtree references inlined
- Life Arcs: State machines with validated transitions
- Schedules: Time blocks with resolved action references
- Relationships: Participants with resolved entity references
- Institutions: Fully resolved field sets
- Locations: Fully resolved field sets
- Species: Fully resolved inheritance chains
- Enums: Complete variant lists
Resolution Process
Template Merging
When a character uses templates, SBIR contains the fully merged result:
Source:
species Human { lifespan: 70, speed: 1.0 }
template Warrior { speed: 1.5, strength: 10 }
character Conan: Human from Warrior {
strength: 20
}
In SBIR, Conan's fields are:
lifespan: 70(from Human)speed: 1.5(Warrior overrides Human)strength: 20(Conan overrides Warrior)
Cross-File Reference Resolution
SBIR resolves all use statements and qualified paths. A relationship referencing Martha in a different file is resolved to the concrete character definition.
Validation
Before producing SBIR, the resolver validates all constraints documented in Validation Rules:
- All references resolve to defined declarations
- No circular dependencies
- Type consistency
- Domain constraints (bond ranges, schedule validity)
Design Goals
Compact: SBIR strips comments, whitespace, and redundant structure.
Self-contained: No external references -- everything is resolved and inlined.
Fast to load: Simulation runtimes can load SBIR without re-parsing or re-resolving.
Validated: If SBIR was produced, the source was valid. Runtimes do not need to re-validate.
Usage
SBIR is consumed by simulation runtimes that drive character behavior, schedule execution, life arc transitions, and relationship queries. The specific binary format is implementation-defined and may evolve between versions.
For the current SBIR specification, see the SBIR v0.2.0 Spec.
Cross-References
- Language Overview - Compilation model
- Validation Rules - What is validated before SBIR production
- Integration Guide - How runtimes consume SBIR