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:
492
docs/reference/11-species.md
Normal file
492
docs/reference/11-species.md
Normal file
@@ -0,0 +1,492 @@
|
||||
# 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
|
||||
|
||||
```bnf
|
||||
<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.
|
||||
|
||||
```storybook
|
||||
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](./18-value-types.md) 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:**
|
||||
```storybook
|
||||
species Dragon {
|
||||
lifespan: 1000
|
||||
can_fly: true
|
||||
breathes_fire: true
|
||||
}
|
||||
|
||||
character Smaug: Dragon {
|
||||
// Smaug IS a Dragon
|
||||
age: 850
|
||||
}
|
||||
```
|
||||
|
||||
**When to use templates:**
|
||||
```storybook
|
||||
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:
|
||||
|
||||
1. **Base species** (leftmost in `includes`)
|
||||
2. **Middle species** (middle in `includes`)
|
||||
3. **Rightmost species** (rightmost in `includes`)
|
||||
4. **Current species fields** (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 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
|
||||
|
||||
1. **Unique names**: Species names must be unique within their module
|
||||
2. **No circular includes**: Cannot form include cycles (compile-time error)
|
||||
3. **Includes exist**: All included species must be defined
|
||||
4. **Field type consistency**: Field values must be well-typed
|
||||
5. **Reserved keywords**: Cannot use reserved keywords as field names
|
||||
6. **Prose tag uniqueness**: Each prose tag can appear at most once per species
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple Species
|
||||
```storybook
|
||||
species Human {
|
||||
lifespan: 70
|
||||
|
||||
---description
|
||||
Bipedal mammals with complex language and tool use.
|
||||
Highly variable in cultures and capabilities.
|
||||
---
|
||||
}
|
||||
```
|
||||
|
||||
### Species with Includes
|
||||
```storybook
|
||||
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
|
||||
```storybook
|
||||
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
|
||||
```storybook
|
||||
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
|
||||
```storybook
|
||||
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
|
||||
```storybook
|
||||
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:
|
||||
```storybook
|
||||
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:
|
||||
```storybook
|
||||
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:
|
||||
```storybook
|
||||
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:
|
||||
```storybook
|
||||
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:**
|
||||
```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
|
||||
language: true
|
||||
}
|
||||
|
||||
// Use templates for capabilities
|
||||
template Climber { ... }
|
||||
template SocialCreature { ... }
|
||||
|
||||
character Jane: Human from Climber, SocialCreature { ... }
|
||||
```
|
||||
|
||||
### Use Species for Ontology, Templates for Variation
|
||||
```storybook
|
||||
// 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](./10-characters.md) - How characters use species with `:` syntax
|
||||
- [Templates](./16-other-declarations.md#templates) - Compositional alternative to species
|
||||
- [Value Types](./18-value-types.md) - All supported field value types
|
||||
- [Use Statements](./16-other-declarations.md#use-statements) - Importing species from other modules
|
||||
- [Enums](./16-other-declarations.md#enums) - Defining controlled vocabularies for species fields
|
||||
|
||||
## Related Concepts
|
||||
|
||||
- **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)
|
||||
Reference in New Issue
Block a user