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
83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 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
|
|
```
|
|
|
|
1. **Lexer**: Tokenizes raw text into tokens
|
|
2. **Parser**: Builds an Abstract Syntax Tree (AST) from tokens
|
|
3. **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:**
|
|
```storybook
|
|
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](../reference/19-validation.md):
|
|
- 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](../SBIR-v0.2.0-SPEC.md).
|
|
|
|
## Cross-References
|
|
|
|
- [Language Overview](../reference/09-overview.md) - Compilation model
|
|
- [Validation Rules](../reference/19-validation.md) - What is validated before SBIR production
|
|
- [Integration Guide](./22-integration.md) - How runtimes consume SBIR
|