release: Storybook v0.2.0 - Major syntax and features update
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
This commit is contained in:
160
docs/advanced/22-integration.md
Normal file
160
docs/advanced/22-integration.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user