# Characters

Characters are the primary entities in Storybook—the people, creatures, and beings that inhabit your world. Each character has a set of attributes that define who they are, what they can do, and how they relate to the world around them.

## Syntax

```bnf
<character-decl> ::= "character" <identifier> <species-clause>? <template-clause>? <body>

<species-clause> ::= ":" <qualified-path>

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

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

<body-item> ::= <field>
              | <uses-behaviors>
              | <uses-schedule>

<uses-behaviors> ::= "uses" "behaviors" ":" <behavior-link-list>

<uses-schedule> ::= "uses" ("schedule" | "schedules") ":" (<qualified-path> | <schedule-list>)

<behavior-link-list> ::= "[" <behavior-link> ("," <behavior-link>)* "]"

<behavior-link> ::= "{" <behavior-link-field>* "}"

<behavior-link-field> ::= "tree" ":" <qualified-path>
                        | "when" ":" <expression>
                        | "priority" ":" ("low" | "normal" | "high" | "critical")

<schedule-list> ::= "[" <qualified-path> ("," <qualified-path>)* "]"

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

<value> ::= <literal>
          | <qualified-path>
          | <list>
          | <object>
          | <prose-block>
          | <override>

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

## Components

### Name
The character's identifier. Must be unique within its scope and follow standard identifier rules (alphanumeric + underscore, cannot start with digit).

### Species (Optional)
The species clause (`: SpeciesName`) defines what the character fundamentally *is*. This is distinct from templates, which define what attributes they *have*.

- **Purpose**: Ontological typing—what kind of being this is
- **Validation**: Must reference a defined `species` declaration
- **Single inheritance**: A character can only have one species
- **Default behavior**: Species fields are inherited automatically

Example:
```storybook
character Martha: Human {
    age: 34
}
```

### Template Inheritance (Optional)
The template clause (`from Template1, Template2`) specifies templates from which the character inherits fields. Templates provide reusable attribute sets.

- **Purpose**: Compositional inheritance—mix-and-match capabilities and traits
- **Multiple inheritance**: Characters can inherit from multiple templates
- **Merge semantics**: Fields from later templates override earlier ones
- **Override allowed**: Character fields override all inherited fields

Example:
```storybook
character Martha: Human from Baker, BusinessOwner {
    specialty: "sourdough"
}
```

### Fields
Fields define the character's attributes using the standard field syntax. All [value types](./18-value-types.md) are supported.

**Common field categories:**
- **Physical traits**: `height`, `weight`, `age`, `eye_color`
- **Personality**: `confidence`, `patience`, `dedication`
- **Professional**: `skill_level`, `specialty`, `recipes_mastered`
- **State tracking**: `energy`, `mood`, `orders_today`
- **Capabilities**: `can_teach`, `can_work_independently`

### Prose Blocks
Characters can contain multiple prose blocks for narrative content. Common tags:

- `---backstory`: Character history and origin
- `---appearance`: Physical description
- `---personality`: Behavioral traits and quirks
- `---motivation`: Goals and desires
- `---secrets`: Hidden information

Prose blocks are narrative-only and do not affect simulation logic.

### Behavior Integration
Characters can link to [behavior trees](./14-behavior-trees.md) using the `uses behaviors` clause.

```storybook
character Guard {
    uses behaviors: [
        {
            tree: combat::patrol_route
            priority: normal
        },
        {
            tree: combat::engage_intruder
            when: threat_detected
            priority: high
        }
    ]
}
```

Each behavior link includes:
- **`tree`**: Qualified path to the behavior tree (required)
- **`when`**: Condition expression for activation (optional)
- **`priority`**: Execution priority (optional, default: `normal`)

See [Behavior Trees](./11-behavior-trees.md) for details on behavior tree syntax and semantics.

### Schedule Integration
Characters can follow [schedules](./16-schedules.md) using the `uses schedule` or `uses schedules` clause.

```storybook
character Baker {
    uses schedule: BakerySchedule
}

character Innkeeper {
    uses schedules: [WeekdaySchedule, WeekendSchedule]
}
```

- Single schedule: `uses schedule: ScheduleName`
- Multiple schedules: `uses schedules: [Schedule1, Schedule2]`

The runtime selects the appropriate schedule based on temporal constraints. See [Schedules](./14-schedules.md) for composition and selection semantics.

## Species vs. Templates

The distinction between species (`:`) and templates (`from`) reflects ontological vs. compositional typing:

| Feature | Species (`:`) | Templates (`from`) |
|---------|--------------|-------------------|
| **Semantics** | What the character *is* | What the character *has* |
| **Cardinality** | Exactly one | Zero or more |
| **Example** | `: Human`, `: Dragon` | `from Warrior, Mage` |
| **Purpose** | Fundamental nature | Reusable trait sets |
| **Override** | Can override species fields | Can override template fields |

Example showing both:
```storybook
species Dragon {
    max_lifespan: 1000
    can_fly: true
}

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

template Ancient {
    age: 500..1000
    wisdom: 0.8..1.0
}

character Smaug: Dragon from Hoarder, Ancient {
    age: 850
    treasure_value: 500000
    greed_level: 0.95
}
```

## Field Resolution Order

When a character inherits from species and templates, fields are resolved in this order (later overrides earlier):

1. **Species fields** (base ontology)
2. **Template fields** (left to right in `from` clause)
3. **Character fields** (highest priority)

Example:
```storybook
species Human {
    lifespan: 80
    speed: 1.0
}

template Warrior {
    speed: 1.5
    strength: 10
}

template Berserker {
    speed: 2.0
    strength: 15
}

character Conan: Human from Warrior, Berserker {
    strength: 20
}

// Resolved fields:
// lifespan: 80     (from Human)
// speed: 2.0       (Berserker overrides Warrior overrides Human)
// strength: 20     (character overrides Berserker)
```

## Validation Rules

The Storybook compiler enforces these validation rules:

1. **Unique names**: Character names must be unique within their module
2. **Species exists**: If specified, the species must reference a defined `species` declaration
3. **Templates exist**: All templates in the `from` clause must reference defined `template` declarations
4. **No circular inheritance**: Templates cannot form circular dependency chains
5. **Field type consistency**: Field values must match expected types from species/templates
6. **Reserved fields**: Cannot use reserved keywords as field names
7. **Behavior trees exist**: All behavior tree references must resolve to defined `behavior` declarations
8. **Schedules exist**: All schedule references must resolve to defined `schedule` declarations
9. **Prose tag uniqueness**: Each prose tag can appear at most once per character

## Examples

### Basic Character
```storybook
character SimpleMerchant {
    name: "Gregor"
    occupation: "Fish Merchant"
    wealth: 50

    ---personality
    A straightforward fish seller at the market. Honest, hardworking,
    and always smells faintly of mackerel.
    ---
}
```

### Character with Species
```storybook
character Martha: Human {
    age: 34
    skill_level: 0.95
    specialty: "sourdough"

    ---backstory
    Martha learned to bake from her grandmother, starting at age
    twelve. She now runs the most popular bakery in town.
    ---
}
```

### Character with Template Inheritance
```storybook
character Jane: Human from Baker, PastrySpecialist {
    age: 36
    specialty: "pastries"
    recipes_mastered: 120

    years_experience: 18
    can_teach: true

    ---appearance
    A focused woman with flour-dusted apron and steady hands.
    Known for her intricate pastry decorations and precise
    temperature control.
    ---
}
```

### Character with All Features
```storybook
character CityGuard: Human from CombatTraining, LawEnforcement {
    age: 30
    rank: "Sergeant"

    // Physical traits
    height: 175
    strength: 12

    // Equipment
    has_weapon: true
    armor_level: 2

    // Behavior integration
    uses behaviors: [
        {
            tree: guards::patrol_route
            priority: normal
        },
        {
            tree: guards::engage_hostile
            when: threat_detected
            priority: high
        },
        {
            tree: guards::sound_alarm
            when: emergency
            priority: critical
        }
    ]

    // Schedule integration
    uses schedules: [guards::day_shift, guards::night_shift]

    ---backstory
    A veteran of the city watch, now responsible for training new recruits
    while maintaining order in the merchant district.
    ---

    ---personality
    Gruff exterior with a hidden soft spot for street children. Follows
    the rules but knows when to look the other way.
    ---
}
```

### Character with Overrides
```storybook
template WeaponUser {
    damage: 5..15
    accuracy: 0.7
}

character MasterSwordsman: Human from WeaponUser {
    // Override template range with specific value
    damage: 15
    accuracy: 0.95

    // Add character-specific fields
    signature_move: "Whirlwind Strike"
}
```

## Use Cases

### Protagonist Definition
Define rich, dynamic protagonists with complex attributes:
```storybook
character Elena: Human from Scholar, Diplomat {
    age: 28
    intelligence: 18
    charisma: 16

    languages_known: ["Common", "Elvish", "Draconic"]
    books_read: 347

    current_quest: "Broker peace between warring kingdoms"

    ---backstory
    Raised in the Grand Library, Elena discovered ancient texts that
    hinted at a forgotten alliance between humans and dragons. She now
    seeks to revive that alliance to end the current war.
    ---
}
```

### NPC Templates
Create diverse NPCs from templates:
```storybook
template Villager {
    occupation: "Farmer"
    wealth: 10..50
    disposition: 0.0..1.0  // 0=hostile, 1=friendly
}

character Oswald: Human from Villager {
    occupation: "Blacksmith"
    wealth: 45
    disposition: 0.8
}

character Mildred: Human from Villager {
    occupation: "Baker"
    wealth: 35
    disposition: 0.95
}
```

### Ensemble Casts
Define multiple related characters:
```storybook
template BakeryStaff {
    punctuality: 0.5..1.0
    teamwork: 0.5..1.0
}

template Apprentice {
    skill_level: 0.0..0.5
    dedication: 0.5..1.0
}

character Elena: Human from BakeryStaff, Apprentice {
    age: 16
    natural_talent: 0.8
    dedication: 0.9

    ---backstory
    Elena comes from a family of farmers who could never afford to
    buy bread from the bakery. When Martha offered her an apprenticeship,
    she jumped at the chance to learn a trade.
    ---
}
```

## Cross-References

- [Species](./16-other-declarations.md#species) - Species declarations
- [Templates](./16-other-declarations.md#templates) - Template definitions and strict mode
- [Value Types](./18-value-types.md) - All supported value types
- [Behavior Trees](./11-behavior-trees.md) - Character behavior integration
- [Schedules](./14-schedules.md) - Character schedule integration
- [Relationships](./15-relationships.md) - Relationships between characters
- [Life Arcs](./13-life-arcs.md) - Character state machines over time

## Related Concepts

- **Instantiation**: Characters are concrete instances; they cannot be instantiated further
- **Composition**: Prefer template composition over deep species hierarchies
- **Modularity**: Characters can reference behaviors and schedules from other modules
- **Narrative-driven**: Use prose blocks to embed storytelling directly with data
