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:
213
docs/reference/09-overview.md
Normal file
213
docs/reference/09-overview.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Language Overview
|
||||
|
||||
> **The Storybook language enables narrative simulation through structured declarations of characters, behaviors, relationships, and events.**
|
||||
|
||||
## Philosophy
|
||||
|
||||
Storybook is a domain-specific language for narrative simulation, influenced by:
|
||||
|
||||
- **Rust**: Strong typing, explicit declarations, and clear ownership semantics
|
||||
- **C#**: Object-oriented patterns with declarative syntax
|
||||
- **Python**: Readable, accessible syntax that prioritizes clarity
|
||||
|
||||
The language balances **technical precision** with **narrative expressiveness**, making it accessible to storytellers while maintaining the rigor developers need.
|
||||
|
||||
## Design Principles
|
||||
|
||||
### 1. Code as Narrative
|
||||
Named nodes and prose blocks let code read like stories:
|
||||
```storybook
|
||||
behavior Baker_MorningRoutine {
|
||||
choose daily_priority {
|
||||
then prepare_sourdough { ... }
|
||||
then serve_customers { ... }
|
||||
then restock_display { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Explicit is Better Than Implicit
|
||||
Every declaration is self-documenting:
|
||||
- Character fields show what defines them
|
||||
- Behavior trees show decision structures
|
||||
- Relationships name their participants
|
||||
|
||||
### 3. Progressive Disclosure
|
||||
Simple cases are simple, complex cases are possible:
|
||||
- Basic characters need just a name and fields
|
||||
- Templates enable inheritance and reuse
|
||||
- Advanced features (state machines, decorators) available when needed
|
||||
|
||||
### 4. Semantic Validation
|
||||
The compiler catches narrative errors:
|
||||
- Bond values must be 0.0..1.0
|
||||
- Schedule blocks can't overlap
|
||||
- Life arc transitions must reference valid states
|
||||
|
||||
## Language Structure
|
||||
|
||||
### Declaration Types
|
||||
|
||||
Storybook has 10 top-level declaration types:
|
||||
|
||||
| Declaration | Purpose | Example |
|
||||
|-------------|---------|---------|
|
||||
| `character` | Define entities with traits and behaviors | A baker with skills and schedule |
|
||||
| `template` | Reusable patterns with ranges | A generic NPC template |
|
||||
| `behavior` | Decision trees for actions | How a character responds to events |
|
||||
| `life_arc` | State machines for life stages | Apprentice → Baker → Master |
|
||||
| `schedule` | Time-based activities | Daily routine from 6am to 10pm |
|
||||
| `relationship` | Connections between entities | Parent-child with bond values |
|
||||
| `institution` | Organizations and groups | A bakery with employees |
|
||||
| `location` | Places with properties | The town square |
|
||||
| `species` | Type definitions with traits | Human vs Cat vs Rabbit |
|
||||
| `enum` | Named value sets | EmotionalState options |
|
||||
|
||||
### Value Types
|
||||
|
||||
Fields can contain:
|
||||
|
||||
- **Primitives**: `42`, `3.14`, `"text"`, `true`
|
||||
- **Time**: `08:30:00`, `14:15`
|
||||
- **Duration**: `2h30m`, `45s`
|
||||
- **Ranges**: `20..40` (for templates)
|
||||
- **Identifiers**: `OtherCharacter`, `path::to::Thing`
|
||||
- **Lists**: `[1, 2, 3]`
|
||||
- **Objects**: `{ field: value }`
|
||||
- **Prose blocks**: ` ---tag\nMulti-line\ntext\n---`
|
||||
|
||||
### Expression Language
|
||||
|
||||
Conditions and queries use:
|
||||
|
||||
- **Comparisons**: `age > 18`, `energy <= 0.5`
|
||||
- **Equality**: `status is active`, `ready is true`
|
||||
- **Logic**: `tired and hungry`, `rich or lucky`, `not ready`
|
||||
- **Field access**: `self.health`, `other.bond`
|
||||
- **Quantifiers**: `forall x in children: x.happy`
|
||||
|
||||
## Compilation Model
|
||||
|
||||
### Source → AST → SBIR → Runtime
|
||||
|
||||
```
|
||||
.sb files → Parser → Abstract Syntax Tree → Resolver → SBIR Binary
|
||||
```
|
||||
|
||||
**SBIR** (Storybook Intermediate Representation) is a compact binary format that:
|
||||
- Resolves all cross-file references
|
||||
- Validates semantic constraints
|
||||
- Optimizes for simulation runtime
|
||||
|
||||
### Validation Layers
|
||||
|
||||
1. **Lexical**: Valid tokens and syntax
|
||||
2. **Syntactic**: Correct grammar structure
|
||||
3. **Semantic**: Type checking, reference resolution
|
||||
4. **Domain**: Narrative constraints (bond ranges, schedule overlaps)
|
||||
|
||||
## File Organization
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
my-storybook/
|
||||
├── characters/
|
||||
│ ├── baker.sb
|
||||
│ └── family.sb
|
||||
├── behaviors/
|
||||
│ └── daily_routine.sb
|
||||
├── world/
|
||||
│ ├── locations.sb
|
||||
│ └── institutions.sb
|
||||
└── schema/
|
||||
├── species.sb
|
||||
└── templates.sb
|
||||
```
|
||||
|
||||
### Import System
|
||||
|
||||
Use `use` statements to reference definitions from other files:
|
||||
|
||||
```storybook
|
||||
use schema::species::Human;
|
||||
use schema::templates::Adult;
|
||||
|
||||
character Baker: Human from Adult {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution order:**
|
||||
1. Same file
|
||||
2. Explicitly imported
|
||||
3. Error if not found
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Character Declaration
|
||||
```storybook
|
||||
character Name: Species from Template {
|
||||
field: value
|
||||
field: value
|
||||
---prose_tag
|
||||
Text content
|
||||
---
|
||||
}
|
||||
```
|
||||
|
||||
### Behavior Tree
|
||||
```storybook
|
||||
behavior Name {
|
||||
choose label { // Selector
|
||||
then label { ... } // Sequence
|
||||
if (condition) // Condition
|
||||
ActionName // Action
|
||||
include path // Subtree
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Life Arc
|
||||
```storybook
|
||||
life_arc Name {
|
||||
state StateName {
|
||||
on condition -> NextState
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Schedule
|
||||
```storybook
|
||||
schedule Name {
|
||||
08:00 -> 12:00: activity { }
|
||||
12:00 -> 13:00: lunch { }
|
||||
}
|
||||
```
|
||||
|
||||
### Relationship
|
||||
```storybook
|
||||
relationship Name {
|
||||
Person1 as role
|
||||
Person2 as role
|
||||
bond: 0.85
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Dive deeper into each declaration type:
|
||||
|
||||
- [Characters](10-characters.md) - Detailed character syntax
|
||||
- [Behavior Trees](11-behavior-trees.md) - Complete behavior node reference
|
||||
- [Decorators](12-decorators.md) - All decorator types
|
||||
- [Life Arcs](13-life-arcs.md) - State machine semantics
|
||||
- [Schedules](14-schedules.md) - Time-based planning
|
||||
- [Relationships](15-relationships.md) - Connection modeling
|
||||
- [Other Declarations](16-other-declarations.md) - Templates, institutions, etc.
|
||||
- [Expressions](17-expressions.md) - Full expression language
|
||||
- [Value Types](18-value-types.md) - All field value types
|
||||
- [Validation](19-validation.md) - Error checking rules
|
||||
|
||||
---
|
||||
|
||||
**Philosophy Note**: Storybook treats narrative as data. Characters aren't objects with methods - they're **declarations** of traits, connected by **behaviors** and **relationships**. This separation enables rich analysis, modification, and simulation of narrative worlds.
|
||||
Reference in New Issue
Block a user