# 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:**
- Number ranges: `min..max` (inclusive)
- Decimal 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
