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
951 lines
20 KiB
Markdown
951 lines
20 KiB
Markdown
# 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
|