Sienna Meridian Satterwhite
16deb5d237
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
493 lines
12 KiB
Markdown
493 lines
12 KiB
Markdown
# 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)
|