Character

Character

"File is identity. Location is presence. Relationships are memory."

Characters are entities that exist in the world. Players, NPCs, companions, cats — all are characters.

Home vs Location

The critical distinction:

player:
  home: characters/don-hopkins/   # Where FILE lives (never moves)
  location: pub/                  # Where CHARACTER is (changes)

Why: Stability, safety, git-friendly diffs.

Character State Ownership (CANONICAL vs MIRROR)

Characters own their own state. The CHARACTER.yml file is CANONICAL for:

ADVENTURE.yml (or other world state files) may MIRROR some state for convenience, but CHARACTER.yml is always the source of truth.

# CHARACTER.yml (CANONICAL — edit this first)
player:
  location: coatroom/  # CANONICAL — character owns their location
  inventory: [lamp]    # CANONICAL — character owns their inventory

# ADVENTURE.yml (MIRROR — optional convenience copy)
player:
  location: coatroom/  # Mirror of CHARACTER.yml

When updating state:

1. Edit CHARACTER.yml first (canonical)
2. Optionally update ADVENTURE.yml mirror for convenience
3. If conflict, CHARACTER.yml wins

Why this matters:

• Characters can be used across multiple adventures
• Character state persists independent of adventure state
• Clear ownership prevents conflicts

Directory Structure

Players (Need Junk Storage)

characters/
  don-hopkins/           # Directory name = character ID
    CHARACTER.yml        # The character file
    CARD.yml             # Optional: makes character a playable card
    cookie-1.yml         # Dispensed items
    notes.yml            # Personal stuff

Sidecar Cards

Any character directory can have a CARD.yml sidecar to make the character card-playable:

# characters/don-hopkins/CARD.yml
card:
  for: ./CHARACTER.yml
  type: hero-story
  tradition: "Pie menus, SimCity, constructionism"
  
  advertisements:
    SUMMON:
      description: "Activate Don's design traditions"

See card skill for full pattern.

Embedded NPCs (Room is Home)

pub/
  bartender.yml          # Lightweight NPC
  cat-cave/
    terpie.yml           # Full family as single files
    stroopwafel.yml
    kitten-myrcene.yml

Rule: Need junk storage? → directory/CHARACTER.yml. Just a character in a room? → character-name.yml.

File Belonging

"Does this character BELONG to a place, or VISIT places?"

Relationships

Key = other entity ID. From is implicit (file owner).

# In marieke.yml
relationships:
  don-hopkins:
    feeling: "A regular now. One of the good ones."
    memories:
      - "The day he sat with Myr for three hours"
    hopes: "I hope he keeps coming back."
    
  self:  # Private inner data!
    identity: "Third generation. This is who I am."
    fears: "That I'm not enough."
    mantra: "The cats need me. I need them."

Targets

Relationships can point to anything:

• Characters (don-hopkins)
• Objects (brass-lamp)
• Locations (pub/, maze/)
• Concepts (acme-corporation)
• Yourself (self) — private storage!

Levels

Inventory (Bidirectional)

Objects stay in their home. Picking up = references, not file moves.

# Don picks up kitten:

# In don-hopkins.yml
inventory:
  - pub/cat-cave/kitten-myrcene.yml
  
# In kitten-myrcene.yml
location: characters/don-hopkins/inventory

# File didn't move. Location changed.

Reset: Snap objects back home: location = home.

Inventory Protocol (Objects vs Refs)

Items in inventory can be OBJECTS or REFS:

Refs are perfect for: catalogs, manuals, maps, guides — things you reference but don't physically carry.

inventory:
  # Full object
  - item: "Brass Lantern"
    type: object
    source: start/lamp.yml
    weight: 2
    fuel: 100
    
  # Lightweight ref
  - item: "ACME Catalog"
    type: ref
    prototype: street/lane-neverending/w1/acme-catalog.yml
    annotations: ["circled portable hole", "margin notes on physics"]

Dispenser Protocol

Some objects dispense refs (like the ACME Catalog Dispenser):

1. TEAR OFF / TAKE at dispenser
2. Receive REF in inventory (weight: 0)
3. REF points to prototype for full content
4. REF can accumulate instance-specific data (annotations, condition)

Drop Protocol

When dropping a ref in a room:

1. Remove from inventory
2. Create pointer file in room directory: [item-name].yml
3. Pointer contains: prototype path, dropped_by, condition, annotations
4. Item now lives in that room (can be picked up again)

# kitchen/acme-catalog.yml — dropped instance
object:
  name: "ACME Catalog"
  type: instance
  prototype: ../street/lane-neverending/w1/acme-catalog.yml
  origin: "Torn from dispenser at 4 Lane Neverending"
  dropped_by: "don-hopkins"
  annotations: ["DO NOT ORDER Rocket Skates", "circled portable hole"]

Capacity

inventory_capacity:
  max_weight: 45    # Varies by character
  max_bulk: 10
  refs_free: true   # Refs don't count!

Dispensers (Full Objects)

Some objects clone full objects on pickup. Original stays, you get instance.

# pub/cookie-jar.yml
object:
  id: cookie-jar
  dispenser: true
  instance_template: cookie

When picked up:

1. Original stays
2. Instance created: characters/don-hopkins/cookie-1.yml
3. Instance inherits from prototype

Ephemeral vs Persistent

Rule: Will this matter in 5 minutes? No → ephemeral. Yes → persistent.

Stats

Two systems:

Sims Traits

• Neat — Sloppy ↔ Organized
• Outgoing — Shy ↔ Social
• Active — Lazy ↔ Energetic
• Playful — Serious ↔ Fun-loving
• Nice — Grouchy ↔ Kind

Distribution: Original Sims used 25 points across 5 traits. Good guideline.

Commands

External Homes

Characters can live in other repositories:

player:
  home: github:donhopkins/characters/don.yml
  location: pub/

Code Locations

Characters can be "at" a specific line in a file:

character:
  name: schema-expert
  home: characters/experts/schema-expert/
  location: "@central/apps/insights/pyleela/brain/Schema.py:142"
  # Currently examining line 142 of Schema.py

Location path syntax for code:

• @repo/path/to/file.py — at a file
• @repo/path/to/file.py:42 — at specific line
• @repo/path/to/file.py:42-67 — examining line range
• @repo/path/dir/ — in a directory (room)

> where is schema-expert?
schema-expert is at @central/apps/insights/pyleela/brain/Schema.py:142
examining the createSyntheticItemIfNeeded method

See room/ for directories as rooms and files as objects.

Party-Based Code Review

Form parties of expert characters to explore code together:

> summon drescher-expert, devops-expert, security-auditor
Party formed: [drescher-expert, devops-expert, security-auditor]

> party: review @central/tools/edgebox/scripts/ingest.py
drescher-expert: "The claim_task function is a schema pattern..."
devops-expert: "The PostgreSQL SKIP LOCKED is elegant..."
security-auditor: "I see proper parameter binding, good..."

> party: focus on lines 280-350
[Multi-perspective analysis of the code section]

Party Navigation:

> go to @central/apps/insights/pyleela/brain/
> enter Schema.py
> look at lines 140-180
> search for "synthetic"
> follow import ExtendedContext
> back
> party: gather here

Each party member brings their expertise. The LLM simulates all perspectives in a single call (see speed-of-light/).

Inner Voice (YAML Jazz)

Comments ARE the character's thoughts:

needs:
  hunger: 3
  # I could eat. But I'm comfortable here.
  # The kittens are asleep on my lap.