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

12 KiB

Raw Permalink Blame History

Species

Species define the fundamental ontological categories of beings in your world. A species represents what a character or entity is at its core—human, dragon, sentient tree, animated playing card. Unlike templates (which provide compositional trait sets), species provide singular, essential identity.

Syntax

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

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

<body> ::= "{" <species-body-item>* "}"

<species-body-item> ::= <field>
                      | <prose-block>

<field> ::= <identifier> ":" <value>

<prose-block> ::= "---" <identifier> <content> "---"

Components

Name

The species identifier. Must be unique within its module and follow standard identifier rules.

Naming conventions:

Use PascalCase: Human, Dragon, PlayingCardPerson
Be specific: BakeryCat vs. generic Cat if varieties exist
Avoid abbreviations: ElderDragon not EldDrgn

Includes Clause (Optional)

Species can include other species to inherit their fields. This enables species composition without deep hierarchies.

species Mammal {
    warm_blooded: true
    has_fur: true
}

species Carnivore includes Mammal {
    diet: "meat"
    has_claws: true
}

species Feline includes Carnivore {
    retractable_claws: true
    purrs: true
}

Semantics:

Multiple includes: species X includes A, B, C
Resolution order: Left-to-right (later overrides earlier)
Transitive: Including Feline also brings in Carnivore and Mammal
No circular includes: Compiler rejects circular dependencies

Fields

Species fields define the default attributes shared by all members of that species.

Common field categories:

Biological: lifespan, reproductive_cycle, diet
Physical: has_fur, warm_blooded, can_fly
Cognitive: sapience_level, intelligence_range
Special abilities: can_vanish, breathes_fire, regenerates

All value types are supported. Unlike templates, species fields should use concrete values rather than ranges (templates handle variation).

Prose Blocks

Species can include narrative descriptions. Common tags:

---description: What this species is and how it behaves
---ecology: Habitat, diet, lifecycle
---culture: Social structures (if sapient)
---notes: Design notes or inspirations

Species vs. Templates

Understanding the distinction is crucial for effective modeling:

Aspect	Species (`:`)	Templates (`from`)
Question	"What is it?"	"What traits does it have?"
Cardinality	One per character	Zero or more
Inheritance	`includes` (species from species)	Characters inherit from templates
Variation	Concrete defaults	Ranges allowed
Example	`species Human`	`template Warrior`
Override	Characters can override	Characters can override

When to use species:

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

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

When to use templates:

template Hoarder {
    treasure_value: 0..1000000
    greed_level: 0.5..1.0
}

character Smaug: Dragon from Hoarder {
    // Smaug HAS hoarder traits
    greed_level: 0.95
}

Field Resolution with Includes

When a species includes other species, fields are merged in declaration order:

Base species (leftmost in includes)
Middle species (middle in includes)
Rightmost species (rightmost in includes)
Current species fields (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 Aquatic and Reptile
}

// Resolved fields:
// 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)

Validation Rules

Unique names: Species names must be unique within their module
No circular includes: Cannot form include cycles (compile-time error)
Includes exist: All included species must be defined
Field type consistency: Field values must be well-typed
Reserved keywords: Cannot use reserved keywords as field names
Prose tag uniqueness: Each prose tag can appear at most once per species

Examples

Simple Species

species Human {
    lifespan: 70

    ---description
    Bipedal mammals with complex language and tool use.
    Highly variable in cultures and capabilities.
    ---
}

Species with Includes

species Mammal {
    warm_blooded: true
    has_fur: true
    reproductive_cycle: "live_birth"
}

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,
    complex social structures, and symbolic communication.
    ---
}

Domestic Species

species Cat {
    lifespan: 15

    ---description
    Domestic cats often found in bakeries and shops for pest
    control and companionship. Independent and territorial.
    ---
}

species Dog {
    lifespan: 12

    ---description
    Loyal companion animals. Some breeds are working dogs
    found on farms and in family households.
    ---
}

Fantasy Species Hierarchy

species Draconic {
    lifespan: 1000
    magic_affinity: true
    scales: true

    ---description
    Ancient lineage of magical reptilian beings.
    ---
}

species Dragon includes Draconic {
    can_fly: true
    breathes_fire: true
    hoard_instinct: 0.8

    ---description
    The apex predators of the sky. Territorial, intelligent,
    and obsessed with collecting treasure.
    ---
}

species Drake includes Draconic {
    can_fly: false
    breathes_fire: false
    pack_hunting: true

    ---description
    Smaller, land-bound cousins of true dragons. Hunt in packs
    and lack the fire breath of their larger kin.
    ---
}

species Wyrm includes Draconic {
    can_fly: false
    breathes_fire: true
    burrows_underground: true

    ---description
    Serpentine dragons without legs or wings. Burrow through
    earth and stone with ease.
    ---
}

Composed Species

species ElementalBeing {
    physical_form: false
    elemental_affinity: "none"
    lifespan: 500
}

species FireElemental includes ElementalBeing {
    elemental_affinity: "fire"
    temperature: 1500  // Celsius

    ---ecology
    Born from volcanic eruptions and wildfires. Feed on combustion
    and heat. Hostile to water and ice.
    ---
}

species WaterElemental includes ElementalBeing {
    elemental_affinity: "water"
    fluidity: 1.0

    ---ecology
    Manifest in rivers, lakes, and oceans. Can assume any liquid
    form. Vulnerable to extreme heat.
    ---
}

Species with Rich Metadata

species Elf {
    lifespan: 1000
    aging_rate: 0.1  // Relative to humans
    magic_sensitivity: 0.9
    height_range: 160..190  // cm

    ---description
    Long-lived humanoids with innate magical abilities and
    connection to ancient forests.
    ---

    ---culture
    Elven societies value art, music, and the preservation of
    knowledge. They see the rise and fall of human kingdoms as
    fleeting moments in the great tapestry of time.
    ---

    ---ecology
    Elves are closely tied to the health of forests. When
    woodlands are destroyed, nearby elven communities weaken
    and may fade entirely.
    ---

    ---notes
    Inspired by Tolkien's concept of immortal sadness—the burden
    of watching all mortal things pass away.
    ---
}

Use Cases

Taxonomy Systems

Build biological hierarchies:

species Vertebrate {
    has_spine: true
    bilateral_symmetry: true
}

species Fish includes Vertebrate {
    breathes_underwater: true
    fins: true
}

species Amphibian includes Vertebrate {
    metamorphosis: true
    moist_skin: true
}

species Reptile includes Vertebrate {
    cold_blooded: true
    scales: true
}

species Bird includes Vertebrate {
    feathers: true
    lays_eggs: true
}

species Mammal includes Vertebrate {
    warm_blooded: true
    mammary_glands: true
}

Fantasy Races

Define playable races or NPC types:

species Dwarf {
    lifespan: 300
    height_range: 120..150
    darkvision: true
    stone_affinity: 0.9

    ---culture
    Master craftsmen who live in underground mountain halls.
    Value honor, loyalty, and fine metalwork.
    ---
}

species Orc {
    lifespan: 60
    height_range: 180..220
    strength_bonus: 2
    darkvision: true

    ---culture
    Tribal warriors with strong oral traditions. Misunderstood
    by outsiders as brutal savages; actually have complex honor
    codes and shamanistic practices.
    ---
}

Sci-Fi Species

Model alien life:

species Crystalline {
    silicon_based: true
    communicates_via: "resonance"
    reproduction: "budding"
    lifespan: 10000

    ---ecology
    Crystalline beings grow slowly in high-pressure environments.
    They communicate through harmonic vibrations and perceive
    electromagnetic spectra invisible to carbon-based life.
    ---
}

Surreal Species

For absurdist or dreamlike worlds:

species SentientColor {
    has_physical_form: false
    wavelength: 400..700  // nanometers
    emotional_resonance: true

    ---description
    Living colors that exist as pure wavelengths of light.
    They experience emotions as shifts in frequency and can
    paint themselves onto surfaces to communicate.
    ---
}

Design Patterns

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
    language: true
}

// Use templates for capabilities
template Climber { ... }
template SocialCreature { ... }

character Jane: Human from Climber, SocialCreature { ... }

Use Species for Ontology, Templates for Variation

// Species: What they are
species Wolf {
    pack_animal: true
    carnivore: true
}

// Templates: Different wolf types
template AlphaWolf {
    dominance: 0.9..1.0
    pack_size: 5..15
}

template LoneWolf {
    dominance: 0.3..0.5
    pack_size: 0..2
}

character Fenrir: Wolf from AlphaWolf { ... }
character Outcast: Wolf from LoneWolf { ... }

Cross-References

Characters - How characters use species with : syntax
Templates - Compositional alternative to species
Value Types - All supported field value types
Use Statements - Importing species from other modules
Enums - Defining controlled vocabularies for species fields

Taxonomic thinking: Species form natural hierarchies mirroring biological classification
Essence vs. Traits: Species capture essence (what something is); templates capture traits (what it has)
Single inheritance for identity: A character can only be one species (you can't be both Human and Dragon)
Multiple inheritance for capabilities: A character can have many templates (a Human can be both Warrior and Mage)

12 KiB Raw Permalink Blame History