Files

Sienna Meridian Satterwhite 16deb5d237

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

2026-02-13 21:52:03 +00:00

20 KiB

Raw Blame History

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 (which define what an entity is), templates define what an entity has—capabilities, traits, and characteristics.

Syntax

<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

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:

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:

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:

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):

template Flexible {
    base_stat: 10
}

character Custom from Flexible {
    base_stat: 15      // Override
    extra_field: 42    // Allowed in non-strict
}

Strict:

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+):

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:

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

Includes exist: All included templates must be defined
No circular includes: Cannot form cycles
Range validity: min ≤ max for all ranges
Strict enforcement: Strict templates reject extra fields in characters
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

<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

institution BakersGuild {
    type: trade_guild
    members: 50
    founded: "1450-03-15"
    reputation: 0.85
}

Institutions with Fields

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:

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:

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

Unique names: Institution names must be unique
Resource links valid: Behaviors/schedules must exist
Field types: All fields must have valid values

Locations

Locations define places in your world—rooms, buildings, cities, landscapes, or abstract spaces.

Syntax

<location-decl> ::= "location" <identifier> <body>

<body> ::= "{" <field>* <prose-block>* "}"

Basic Location

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

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:

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

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

Unique names: Location names must be unique
Field types: All fields must have valid values
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

<species-decl> ::= "species" <identifier> <includes-clause>? <body>

<includes-clause> ::= "includes" <identifier> ("," <identifier>)*

<body> ::= "{" <field>* <prose-block>* "}"

Basic Species

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:

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:

Base species (leftmost in includes)
Middle species
Rightmost species
Current species (highest priority)

Example:

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:

species Dragon {
    lifespan: 1000
    can_fly: true
    breathes_fire: true
}

character Smaug: Dragon {
    age: 850  // Smaug IS a Dragon
}

When to use templates:

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:

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:

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

Unique names: Species names must be unique
No circular includes: Cannot form cycles
Includes exist: All included species must be defined
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

<enum-decl> ::= "enum" <identifier> "{" <variant>+ "}"

<variant> ::= <identifier> ","?

Basic Enum

enum Size {
    tiny,
    small,
    normal,
    large,
    huge
}

Using Enums

Enums are used as field values throughout the system:

character Martha: Human {
    skill_level: master     // References SkillLevel enum
    specialty: sourdough    // References Specialty enum
}

Common Enum Patterns

Emotional States:

enum EmotionalState {
    curious,
    frightened,
    confused,
    brave,
    angry,
    melancholy,
    amused
}

Card Suits:

enum CardSuit {
    hearts,
    diamonds,
    clubs,
    spades
}

enum CardRank {
    two, three, four, five, six, seven, eight, nine, ten,
    knave, queen, king
}

Time States:

enum TimeState {
    normal,
    frozen,
    reversed,
    accelerated
}

Government Types:

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:

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:

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:

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

Unique enum names: Enum names must be unique
Unique variants: Variant names must be unique within the enum
Non-empty: Enums must have at least one variant
Valid identifiers: Variants must follow identifier rules

Use Statements

Use statements import definitions from other files, enabling modular organization and code reuse.

Syntax

<use-decl> ::= "use" <use-path> <use-kind>

<use-path> ::= <identifier> ("::" <identifier>)*

<use-kind> ::= ";"                                   // Single import
             | "::{" <identifier> ("," <identifier>)* "}" ";"  // Grouped import
             | "::*" ";"                             // Wildcard import

Single Import

use schema::beings::Human;

Imports the Human species from schema/beings.sb.

Grouped Import

use schema::core_enums::{Size, EmotionalState};

Imports multiple items from the same module.

Wildcard Import

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:

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

Relative to file's module path: Imports are resolved relative to the current file's location
Module hierarchy: schema::beings maps to schema/beings.sb
Transitive imports: Imported modules can themselves import others

Common Patterns

Schema organization:

// 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:

// In schema/templates.sb
template SkilledWorker { ... }
template Baker {
    include SkilledWorker
    ...
}

// In world/characters/martha.sb
use schema::templates::Baker;

Cross-file references:

// In world/characters/martha.sb
character Martha { ... }

// In world/relationships/bakery.sb
use world::characters::Martha;

relationship MarthaAndJane {
    Martha
    Jane
}

Validation Rules

Path exists: Imported paths must reference defined modules/items
No circular imports: Modules cannot form circular dependency chains
Valid identifiers: All path segments must be valid identifiers
Grouped import validity: All items in {} must exist

Best Practices

1. Group related imports:

use schema::core_enums::{SkillLevel, Specialty, Confidence};
use schema::beings::{Human, Cat};

2. Explicit over wildcard:

// Prefer:
use schema::core_enums::{SkillLevel, Specialty};

// Over:
use schema::core_enums::*;  // Imports everything

3. Organize by hierarchy:

// 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:

character Elena: Human from Baker, Apprentice {
    // Human is species (from schema::beings)
    // Baker, Apprentice are templates (from schema::templates)
}

Cross-References

Characters - Using templates and species
Relationships - Institutions can participate
Schedules - Resource linking
Behavior Trees - Resource linking
Value Types - Field value types

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

20 KiB Raw Blame History

Other Declarations

Templates

Syntax

Basic Template

Template Includes

Range Values

Strict Mode

Resource Linking in Templates

Templates vs. Species

Validation Rules

Institutions

Syntax

Basic Institution

Institutions with Fields

Resource Linking

Prose Blocks

Use Cases

Validation Rules

Locations

Syntax

Basic Location

Location with Structure

Geographic Hierarchy

Location with State

Use Cases

Validation Rules

Species

Syntax

Basic Species

Species with Includes

Field Resolution with Includes

Species vs. Templates

Design Pattern: Prefer Composition Over Deep Hierarchies

Validation Rules

Enums

Syntax

Basic Enum

Using Enums

Common Enum Patterns

Calendar Enums (Configurable)

Validation Integration

Use Cases

Validation Rules

Use Statements

Syntax

Single Import

Grouped Import

Wildcard Import

Qualified Paths

Path Resolution

Common Patterns

Validation Rules

Best Practices

Cross-References

Related Concepts

20 KiB

Raw Blame History