studio/storybook
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release: Storybook v0.2.0 - Major syntax and features update

Browse Source 
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:
Sienna Meridian Satterwhite
2026-02-13 21:52:03 +00:00
parent 80332971b8
commit 16deb5d237
290 changed files with 90316 additions and 5827 deletions
Download Patch File Download Diff File Expand all files Collapse all files

950
docs/reference/16-other-declarations.md Normal file
View File

@@ -0,0 +1,950 @@
# Other Declarations
This chapter covers six utility declaration types that complete the Storybook language: Templates, Institutions, Locations, Species, Enums, and Use statements. These declarations enable code reuse, organizational modeling, world-building, type safety, and modular file organization.
---
## Templates
Templates are reusable field sets that characters inherit using the `from` keyword. Unlike [species](./10-characters.md#species-optional) (which define what an entity *is*), templates define what an entity *has*—capabilities, traits, and characteristics.
### Syntax
```bnf
<template-decl> ::= "template" <identifier> <strict-clause>? <resource-links>? <includes-clause>? <body>
<strict-clause> ::= "strict"
<resource-links> ::= "uses" "behaviors" ":" <behavior-list>
| "uses" "schedule" ":" <schedule-ref>
| "uses" "schedules" ":" <schedule-list>
<includes-clause> ::= "include" <identifier> ("," <identifier>)*
<body> ::= "{" <field>* "}"
<field> ::= <identifier> ":" <value>
```
### Basic Template
```storybook
template Warrior {
strength: 10..20
dexterity: 8..15
weapon_proficiency: 0.7..1.0
}
```
Characters inheriting this template get these fields with values selected from the specified ranges.
### Template Includes
Templates can include other templates to compose functionality:
```storybook
template SkilledWorker {
skill_level: SkillLevel
confidence: Confidence
years_experience: 0..50
can_work_independently: false
}
template Baker {
include SkilledWorker
specialty: Specialty
recipes_mastered: 0..200
sourdough_starter_health: 0.0..1.0
}
```
**Semantics:**
- `include SkilledWorker` brings in all fields from that template
- Fields are merged left-to-right (later overrides earlier)
- Transitive includes supported
- Multiple includes allowed: `include A, B, C`
### Range Values
Templates can specify ranges for procedural variation:
```storybook
template Villager {
age: 18..65
wealth: 10..100
height: 150.0..190.0
disposition: 0.0..1.0
}
```
**Range syntax:**
- Integer ranges: `min..max` (inclusive)
- Float ranges: `min..max` (inclusive)
- Both bounds must be same type
- min ≤ max required
When a character uses this template, the runtime selects specific values within each range.
### Strict Mode
Strict templates enforce that characters using them can only have fields defined in the template:
```storybook
template RecipeCard strict {
include SkilledWorker
recipe_name: string
difficulty: Difficulty
prep_time_minutes: 10..180
requires_starter: false
}
```
**Strict semantics:**
- Characters using strict templates cannot add extra fields
- All template fields must be present in the character
- Enables type safety for well-defined schemas
- Use for controlled domains (game cards, rigid categories)
**Non-strict (default):**
```storybook
template Flexible {
base_stat: 10
}
character Custom from Flexible {
base_stat: 15 // Override
extra_field: 42 // Allowed in non-strict
}
```
**Strict:**
```storybook
template Rigid strict {
required_stat: 10
}
character Constrained from Rigid {
required_stat: 15 // OK: Override
extra_field: 42 // ERROR: Not allowed in strict template
}
```
### Resource Linking in Templates
Templates can link to behaviors and schedules (v0.2.0+):
```storybook
template BakeryStaffMember
uses behaviors: DailyBakingRoutine, CustomerService
uses schedule: BakerySchedule
{
include SkilledWorker
on_shift: true
orders_completed: 0..1000
current_station: 0..4
}
```
Characters inheriting this template automatically get the linked behaviors and schedule.
### Templates vs. Species
| Aspect | Templates (`from`) | Species (`:`) |
|--------|-------------------|---------------|
| Semantics | What entity *has* | What entity *is* |
| Cardinality | Multiple inheritance | Single inheritance |
| Ranges | Allowed | Not allowed |
| Strict mode | Supported | Not supported |
| Use case | Compositional traits | Ontological identity |
**Example combining both:**
```storybook
species Dragon {
lifespan: 1000
can_fly: true
}
template Hoarder {
treasure_value: 0..1000000
greed_level: 0.5..1.0
}
character Smaug: Dragon from Hoarder {
age: 850
greed_level: 0.95
}
```
### Validation Rules
1. **Includes exist**: All included templates must be defined
2. **No circular includes**: Cannot form cycles
3. **Range validity**: min ≤ max for all ranges
4. **Strict enforcement**: Strict templates reject extra fields in characters
5. **Resource links valid**: Behavior/schedule references must resolve
---
## Institutions
Institutions define organizations, groups, and systems—entities that function like characters but represent collectives rather than individuals.
### Syntax
```bnf
<institution-decl> ::= "institution" <identifier> <resource-links>? <body>
<resource-links> ::= "uses" "behaviors" ":" <behavior-list>
| "uses" "schedule" ":" <schedule-ref>
| "uses" "schedules" ":" <schedule-list>
<body> ::= "{" <field>* <prose-block>* "}"
```
### Basic Institution
```storybook
institution BakersGuild {
type: trade_guild
members: 50
founded: "1450-03-15"
reputation: 0.85
}
```
### Institutions with Fields
```storybook
institution BakersGuild {
type: professional_guild
government_style: elected_board
hierarchy: flat
standards_enforcement: true
// Leadership
board_chair: Martha
vice_chair: Henri
board_temperament: collegial
// Membership
master_bakers: 12
journeymen: 25
apprentices: 8
honorary_members: 3
// Standards
certification_process: "practical exam and peer review"
quality_standard: "excellence"
annual_competition: true
scholarships_offered: 2
---description
The local bakers' guild that sets quality standards, organizes
competitions, and mentors apprentices. Martha has been a board
member for three years.
---
}
```
### Resource Linking
Institutions can use behaviors and schedules:
```storybook
institution MarthasBakery
uses behaviors: DailyBakingRoutine, CustomerService
uses schedule: BakerySchedule
{
type: small_business
purpose: bread_and_pastry_production
family_owned: true
established: 2018
permanent_staff: 4
seasonal_helpers: 0..3
---description
A beloved neighborhood bakery run by Martha and Jane,
known for its sourdough bread and artisan pastries.
---
}
```
### Prose Blocks
Institutions support rich narrative documentation:
```storybook
institution TownCulinaryScene {
type: cultural_ecosystem
governs: "local food culture"
// Characteristics
farm_to_table: true
artisan_focus: strong
seasonal_menus: true
community_events: monthly
---description
The overarching culinary culture of the town -- a network
of bakeries, farms, and food artisans that sustain each other.
---
---philosophy
The town's food scene operates on relationships: farmers
supply bakers, bakers feed families, families support farms.
Quality and trust are the currency of this ecosystem.
---
}
```
### Use Cases
- **Organizations**: Guilds, companies, governments
- **Systems**: Magical systems, physical laws, economies
- **Social structures**: Families, tribes, castes
- **Abstract entities**: Dream logic, fate, chaos
### Validation Rules
1. **Unique names**: Institution names must be unique
2. **Resource links valid**: Behaviors/schedules must exist
3. **Field types**: All fields must have valid values
---
## Locations
Locations define places in your world—rooms, buildings, cities, landscapes, or abstract spaces.
### Syntax
```bnf
<location-decl> ::= "location" <identifier> <body>
<body> ::= "{" <field>* <prose-block>* "}"
```
### Basic Location
```storybook
location MarthasBakery {
square_feet: 1200
type: commercial
established: "2018"
has_storefront: true
---description
A warm, inviting bakery on Main Street. The aroma of fresh
bread wafts out the door every morning. Exposed brick walls,
a glass display case, and a view into the open kitchen.
---
}
```
### Location with Structure
```storybook
location BakeryKitchen {
type: "commercial kitchen"
ovens: 3
prep_stations: 4
walk_in_cooler: true
// Equipment
has_proofing_cabinet: true
mixer_capacity_kg: 20
starter_shelf: true
// Storage
flour_bins: 6
ingredient_shelves: 12
cold_storage: true
---description
The heart of the bakery. Three professional ovens line the
back wall. The sourdough starter sits on a shelf near the
warmest oven, bubbling contentedly in its ceramic crock.
---
}
```
### Geographic Hierarchy
Locations can reference other locations:
```storybook
location MainStreet {
type: commercial_district
shops: 15
foot_traffic: high
}
location BakeryStorefront {
part_of: MainStreet
seating_capacity: 12
display_case: true
---description
The customer-facing area with a glass display case full
of fresh bread, pastries, and seasonal specials.
---
}
location FarmersMarket {
part_of: MainStreet
operates_on: saturday
stalls: 30
---description
The weekly Saturday market where Martha sells bread directly
to the community. Her stall is always the first to sell out.
---
}
```
### Location with State
```storybook
location BakeryWarehouse {
temperature: controlled
square_feet: 400
humidity_controlled: true
shelving_units: 8
// Storage state
flour_stock_kg: 200
yeast_supply_days: 14
packaging_materials: true
---description
The storage area behind the kitchen. Climate-controlled to
keep flour dry and ingredients fresh. Martha takes inventory
every Monday morning.
---
---logistics
Deliveries arrive Tuesday and Friday mornings. The walk-in
cooler holds butter, eggs, and cream. Dry goods are rotated
on a first-in-first-out basis.
---
}
```
### Use Cases
- **Physical places**: Cities, buildings, rooms
- **Geographic features**: Mountains, rivers, forests
- **Abstract spaces**: Dream realms, pocket dimensions
- **Game boards**: Arenas, dungeons, maps
### Validation Rules
1. **Unique names**: Location names must be unique
2. **Field types**: All fields must have valid values
3. **References valid**: Location references (like `part_of`) should resolve
---
## Species
Species define the fundamental ontological categories of beings. A species represents what an entity *is* at its core—human, dragon, sentient tree, animated playing card.
### Syntax
```bnf
<species-decl> ::= "species" <identifier> <includes-clause>? <body>
<includes-clause> ::= "includes" <identifier> ("," <identifier>)*
<body> ::= "{" <field>* <prose-block>* "}"
```
### Basic Species
```storybook
species Human {
lifespan: 70
---description
Bipedal mammals with complex language and tool use.
Highly variable in cultures and capabilities.
---
}
```
### Species with Includes
Species can include other species for composition:
```storybook
species Mammal {
warm_blooded: true
has_fur: true
}
species Primate includes Mammal {
opposable_thumbs: true
sapience_potential: 0.5..1.0
}
species Human includes Primate {
sapience_potential: 1.0
language_complexity: "high"
---description
Highly intelligent primates with advanced tool use.
---
}
```
### Field Resolution with Includes
When a species includes others, fields are merged in declaration order:
1. **Base species** (leftmost in `includes`)
2. **Middle species**
3. **Rightmost species**
4. **Current species** (highest priority)
Example:
```storybook
species Aquatic {
breathes_underwater: true
speed_in_water: 2.0
}
species Reptile {
cold_blooded: true
speed_in_water: 1.0
}
species SeaTurtle includes Aquatic, Reptile {
has_shell: true
speed_in_water: 1.5 // Overrides both
}
// Resolved:
// breathes_underwater: true (from Aquatic)
// cold_blooded: true (from Reptile)
// speed_in_water: 1.5 (SeaTurtle overrides Reptile overrides Aquatic)
// has_shell: true (from SeaTurtle)
```
### Species vs. Templates
| Aspect | Species (`:`) | Templates (`from`) |
|--------|--------------|-------------------|
| Question | "What *is* it?" | "What *traits* does it have?" |
| Cardinality | One per character | Zero or more |
| Inheritance | `includes` (species → species) | Characters inherit from templates |
| Variation | Concrete defaults | Ranges allowed |
| Example | `species Human` | `template Warrior` |
**When to use species:**
```storybook
species Dragon {
lifespan: 1000
can_fly: true
breathes_fire: true
}
character Smaug: Dragon {
age: 850 // Smaug IS a Dragon
}
```
**When to use templates:**
```storybook
template Hoarder {
treasure_value: 0..1000000
greed_level: 0.5..1.0
}
character Smaug: Dragon from Hoarder {
greed_level: 0.95 // Smaug HAS hoarder traits
}
```
### Design Pattern: Prefer Composition Over Deep Hierarchies
**Avoid:**
```storybook
species Being { ... }
species LivingBeing includes Being { ... }
species Animal includes LivingBeing { ... }
species Vertebrate includes Animal { ... }
species Mammal includes Vertebrate { ... }
species Primate includes Mammal { ... }
species Human includes Primate { ... } // Too deep!
```
**Prefer:**
```storybook
species Mammal {
warm_blooded: true
live_birth: true
}
species Human includes Mammal {
sapient: true
}
// Use templates for capabilities
template Climber { ... }
template SocialCreature { ... }
character Jane: Human from Climber, SocialCreature { ... }
```
### Validation Rules
1. **Unique names**: Species names must be unique
2. **No circular includes**: Cannot form cycles
3. **Includes exist**: All included species must be defined
4. **Field types**: All fields must have valid values
---
## Enums
Enums define controlled vocabularies—fixed sets of named values. They enable type-safe categorization and validation.
### Syntax
```bnf
<enum-decl> ::= "enum" <identifier> "{" <variant>+ "}"
<variant> ::= <identifier> ","?
```
### Basic Enum
```storybook
enum Size {
tiny,
small,
normal,
large,
huge
}
```
### Using Enums
Enums are used as field values throughout the system:
```storybook
character Martha: Human {
skill_level: master // References SkillLevel enum
specialty: sourdough // References Specialty enum
}
```
### Common Enum Patterns
**Emotional States:**
```storybook
enum EmotionalState {
curious,
frightened,
confused,
brave,
angry,
melancholy,
amused
}
```
**Card Suits:**
```storybook
enum CardSuit {
hearts,
diamonds,
clubs,
spades
}
enum CardRank {
two, three, four, five, six, seven, eight, nine, ten,
knave, queen, king
}
```
**Time States:**
```storybook
enum TimeState {
normal,
frozen,
reversed,
accelerated
}
```
**Government Types:**
```storybook
enum GovernmentType {
monarchy,
democracy,
anarchy,
tyranny,
oligarchy
}
enum GovernmentStyle {
absolute_tyranny,
benevolent_dictatorship,
constitutional_monarchy,
direct_democracy,
representative_democracy
}
```
### Calendar Enums (Configurable)
Define custom calendars for your world:
```storybook
enum Season {
spring,
summer,
fall,
winter
}
enum DayOfWeek {
monday,
tuesday,
wednesday,
thursday,
friday,
saturday,
sunday
}
enum Month {
january, february, march, april,
may, june, july, august,
september, october, november, december
}
```
**Custom calendars:**
```storybook
enum EightSeasons {
deep_winter,
late_winter,
early_spring,
late_spring,
early_summer,
late_summer,
early_fall,
late_fall
}
```
### Validation Integration
Enums enable compile-time validation:
```storybook
enum Size {
tiny, small, normal, large, huge
}
character Martha {
skill_level: medium // ERROR: 'medium' not in SkillLevel enum
}
```
### Use Cases
- **Controlled vocabularies**: Prevent typos and invalid values
- **Schema constraints**: Temporal systems, card decks, status types
- **Type safety**: Catch errors at compile time
- **Documentation**: Enumerate all valid options
### Validation Rules
1. **Unique enum names**: Enum names must be unique
2. **Unique variants**: Variant names must be unique within the enum
3. **Non-empty**: Enums must have at least one variant
4. **Valid identifiers**: Variants must follow identifier rules
---
## Use Statements
Use statements import definitions from other files, enabling modular organization and code reuse.
### Syntax
```bnf
<use-decl> ::= "use" <use-path> <use-kind>
<use-path> ::= <identifier> ("::" <identifier>)*
<use-kind> ::= ";" // Single import
| "::{" <identifier> ("," <identifier>)* "}" ";" // Grouped import
| "::*" ";" // Wildcard import
```
### Single Import
```storybook
use schema::beings::Human;
```
Imports the `Human` species from `schema/beings.sb`.
### Grouped Import
```storybook
use schema::core_enums::{Size, EmotionalState};
```
Imports multiple items from the same module.
### Wildcard Import
```storybook
use schema::beings::*;
```
Imports all public items from `schema/beings.sb`.
### Qualified Paths
**Module structure:**
```
examples/alice-in-wonderland/
├─ schema/
│ ├─ core_enums.sb
│ ├─ templates.sb
│ └─ beings.sb
└─ world/
├─ characters/
│ └─ alice.sb
└─ locations/
└─ wonderland_places.sb
```
**In `martha.sb`:**
```storybook
use schema::core_enums::{SkillLevel, Specialty};
use schema::templates::Baker;
use schema::beings::Human;
character Martha: Human from Baker {
skill_level: master
specialty: sourdough
}
```
### Path Resolution
1. **Relative to file's module path**: Imports are resolved relative to the current file's location
2. **Module hierarchy**: `schema::beings` maps to `schema/beings.sb`
3. **Transitive imports**: Imported modules can themselves import others
### Common Patterns
**Schema organization:**
```storybook
// In schema/core_enums.sb
enum SkillLevel { novice, beginner, intermediate, advanced, master }
enum Specialty { sourdough, pastries, cakes, general }
// In world/characters/martha.sb
use schema::core_enums::{SkillLevel, Specialty};
```
**Template composition:**
```storybook
// In schema/templates.sb
template SkilledWorker { ... }
template Baker {
include SkilledWorker
...
}
// In world/characters/martha.sb
use schema::templates::Baker;
```
**Cross-file references:**
```storybook
// In world/characters/martha.sb
character Martha { ... }
// In world/relationships/bakery.sb
use world::characters::Martha;
relationship MarthaAndJane {
Martha
Jane
}
```
### Validation Rules
1. **Path exists**: Imported paths must reference defined modules/items
2. **No circular imports**: Modules cannot form circular dependency chains
3. **Valid identifiers**: All path segments must be valid identifiers
4. **Grouped import validity**: All items in `{}` must exist
### Best Practices
**1. Group related imports:**
```storybook
use schema::core_enums::{SkillLevel, Specialty, Confidence};
use schema::beings::{Human, Cat};
```
**2. Explicit over wildcard:**
```storybook
// Prefer:
use schema::core_enums::{SkillLevel, Specialty};
// Over:
use schema::core_enums::*; // Imports everything
```
**3. Organize by hierarchy:**
```storybook
// Schema imports first
use schema::core_enums::SkillLevel;
use schema::templates::Baker;
// Then world imports
use world::characters::Martha;
```
**4. Use qualified paths for clarity:**
```storybook
character Elena: Human from Baker, Apprentice {
// Human is species (from schema::beings)
// Baker, Apprentice are templates (from schema::templates)
}
```
---
## Cross-References
- [Characters](./10-characters.md) - Using templates and species
- [Relationships](./15-relationships.md) - Institutions can participate
- [Schedules](./14-schedules.md) - Resource linking
- [Behavior Trees](./11-behavior-trees.md) - Resource linking
- [Value Types](./18-value-types.md) - Field value types
## Related Concepts
- **Modularity**: Use statements enable file organization
- **Composition**: Templates provide trait-based composition
- **Type safety**: Enums prevent invalid values
- **World-building**: Locations and institutions model environments
- **Ontology**: Species define entity essence