Elf Revel Wiki

Welcome to the comprehensive reference for Elf Revel, a colony sim where elves compose music, throw revels, and argue about art.

This wiki documents every game system in detail — exact formulas, tick-level behavior, hidden mechanics, and strategy advice. Whether you're a new player figuring out the controls or an optimizer calculating revel satisfaction scores, you'll find what you need here.

The Three-Tier Model

Elf Revel has three levels of intentionality:

1. You (the Patron) — provide taste, artistic direction, and broad guidance via the chat panel and keyboard commands
2. The AI Advisor (Curator) — translates your preferences into concrete cultural policies: role assignments, revel scheduling, build orders
3. The Elves — execute autonomously at the tick level: gather resources, compose music, attend revels, form relationships

The human has taste, the AI has hands, the elves have lives.

How to Use This Wiki

New players — start with Controls and Your First Settlement.

Understanding mechanics — each system page in Core Systems and Art & Culture covers mechanics from overview down to exact formulas.

Optimizing play — the Strategy Guides connect game systems into practical advice.

Every page follows the same structure:

1. Overview — what the system does
2. How It Works — mechanics description
3. Values & Formulas — tables with exact numbers from the source code
4. Interactions — how it connects to other systems
5. Tips — practical advice

Game Timing

All game mechanics run on ticks. One day = 100 ticks. One season = 25 days. One year = 100 days (4 seasons). The game starts in Spring.

Controls

Complete keybinding reference for Elf Revel. The game is controlled entirely via keyboard.

Core

Elf Selection

Screens (Full Overlays)

Each screen opens a full overlay. Press the same key again or Esc to close. You can switch directly between screens by pressing another screen key.

All screens support Up/Down to scroll.

Work Assignments Screen

The Work Assignments screen (w) uses a cursor-based grid:

Current assignment shows as [X] in green. Cursor cell is highlighted in cyan.

Panels & Modes

Look Mode

In look mode, a cursor appears on the map for tile inspection:

Chat (AI Advisor)

See How the Curator Works for what the advisor can do.

Actions

Tips

• Pause often (Space) — the simulation runs even while you browse screens
• Events panel (e) is the most informative panel — it shows compositions, relationships, mood shifts, spirit warnings, and season changes
• Name locations via look mode (l → navigate → n) — named spots persist and appear on the map

UI Guide

The main screen is a terminal interface with several panels and overlay screens.

Main View

Map (Center)

The map shows your settlement on a procedurally generated terrain grid. Elves are colored letters moving across the landscape.

See Terrain for full details on each tile type.

Status Bar (Top)

Displays the current game state at a glance:

• Season and day: e.g., "Spring Day 12 (Day)"
• Weather icon: current weather condition
• Curator mode: which advisor is active (Dummy or LLM)
• Speed: current simulation speed (1x-8x)
• Pause indicator: shows when paused

Footer Bar (Bottom)

Shows resource counts (Wood, Stone, Food, FineWood) and a condensed status line with season and temperature.

Elf Detail Panel (Right, when selected)

Select an elf (1-9 or ,/.) then press Enter to see:

• Mood — current morale state and active modifiers
• Needs — bar display for Rest, Sustenance, Beauty, Stimulation, Company
• Current task — what the elf is doing right now
• Skills — Music, Building, Gathering levels with XP progress
• Compositions — portfolio of works (navigate with j/k, favorite with f)
• Relationships — bonds with other elves
• Aesthetic position — four-axis position (structure, tradition, emotion, social)

Events Panel (Right, toggle with e)

A scrolling log of settlement events:

• Composition completions
• Relationship changes (new bonds, breakups, mentoring)
• Mood shifts and need warnings
• Revel announcements and results
• Forest spirit warnings
• Season changes and notable weather
• Departure warnings and departures

Roster Sidebar (Right, toggle with r)

List of all elves with mood indicator icons. Quick way to scan settlement morale at a glance.

Overlay Screens

Press any screen key to open a full overlay. Overlays replace the main view until closed with Esc or by pressing another screen key.

Settlement Overview (s)

Population count, resource stockpiles with daily production/consumption rates, and a list of completed and in-progress buildings.

Art Gallery (a)

Every composition in the settlement, showing:

• Title (three-part procedural name)
• Composer
• Genre family and base type
• Quality scores (mastery, originality, emotional)
• Properties (up to 15 attributes)

Relationships (x)

Grid of all elf-to-elf bonds with type (Friend, Rival, Mentor) and strength value. See Relationships.

Revel History (v)

Record of past revels: date, location, attendees, performances, and audience satisfaction. See Revels.

Build Management (b)

Build queue showing pending construction with progress bars, plus completed buildings.

Work Assignments (w)

Interactive elf-by-role grid. Cursor navigation to reassign elves between Gatherer, Builder, Composer, and Unassigned. See Roles.

Chat Panel (Bottom)

The chat panel shows your conversation with the AI cultural advisor. Press / or Tab to focus, type a message, and press Enter to send.

The curator responds based on settlement state and your artistic direction. See How the Curator Works.

Your First Settlement

A walkthrough of your first game session, covering what happens in the first 50 ticks and the key decisions that shape your colony.

Starting State

When you begin a new game, you have:

• 5-8 elves with randomized skills, aesthetic positions, and starting needs
• Resources: a small starting stockpile of Wood, Stone, and Food
• No buildings — your elves are in the open
• Season: Spring (the most forgiving season — resource regeneration is doubled)
• Forest Spirit: at 0 (Harmony)

The Dummy Curator is active by default and will auto-assign initial roles based on each elf's highest skill.

First 25 Ticks: Establish Basics

Priority 1: Check Your Elves

Press 1-9 to select each elf, then Enter to see their detail panel. Note:

• Who has the highest Music skill? They should be composing.
• Who has the highest Gathering skill? They should be gathering.
• The curator usually handles this, but check the Work Assignments screen (w) to verify.

Priority 2: Watch the Events Panel

Press e to open the events panel. Early events tell you what's happening:

• Role assignments from the curator
• Elves starting to forage and gather
• Social interactions as elves meet each other

Priority 3: Start Building

The curator will typically queue a Dwelling first (10 Wood). Dwellings provide shelter and faster rest recovery (+5/tick vs. base rate). Check the Build Management screen (b) to see the queue.

If you have a Builder-role elf, they'll start quarrying stone and constructing automatically.

Suggested early build order:

1. Dwelling — shelter from weather, faster rest
2. Workshop — composing station, stimulation boost
3. Garden — beauty +3/tick, calms forest spirit -2/dawn

Ticks 25-50: First Compositions and Social Bonds

Compositions Begin

Composer-role elves will start creating music once they have enough inspiration. Watch for "composed" events in the event panel. Early compositions are typically low quality (skill level 1-3), but they improve as elves gain XP.

XP note: each level costs level × 50 XP. A level 1 elf needs just 50 XP to reach level 2. See Skills.

Relationships Form

Elves form bonds through proximity and shared experiences. After ~25 ticks, you'll see Friend and occasionally Rival relationships appearing. Elves with similar aesthetic positions bond more easily. See Relationships.

Watch the Needs

Needs decay continuously:

If any elf's morale drops below 50 (Stressed tier), they'll appear with a warning indicator in the roster (r).

First Revel

The Dummy Curator schedules a revel when:

• A Feast Hall exists (15 Wood, 5 Stone), or the curator decides to hold one anyway
• Food stockpile is sufficient (>= 5, or >= 15 in Winter)
• Cooldown from last revel has expired

Revels are the core social event — they satisfy Beauty and Stimulation needs, generate mood modifiers, and reveal how your elves react to each other's compositions.

See Revels for the full lifecycle.

Key Milestones

What to Watch For

• Forest Spirit: if you clear too much forest, the spirit meter rises. Stay below 20 for Harmony. See Forest Spirit.
• Discontented elves: if an elf shows the discontented indicator, their satisfaction has been low for 300 ticks. You have 500 more ticks before they depart. Prioritize their needs.
• Seasonal shift: Winter starts at day 75. Foraging drops to ×0.5 (halved again with snow). Summer (×1.5) and Autumn (×1.25) are your stockpiling windows. See Seasons & Weather.

Tips for New Players

• Pause early and often (Space) — take time to explore screens and understand the UI
• Don't clear Ancient Forest unless necessary — it gives the most wood but angers the spirit the most (+5 anger, +7 in Spring)
• Gardens are powerful — +3 beauty/tick for nearby elves AND -2 spirit anger/dawn, even in Winter
• Let the curator work — the Dummy Curator makes reasonable decisions. Override via Work Assignments (w) only when you disagree
• Use artistic direction (d) to guide the colony's cultural output without micromanaging

Needs & Mood

Overview

Every elf has five basic needs and a mood stack that together determine their morale -- the single number (0-100) that governs behavior, work speed, and departure risk. Needs decay at different rates; mood modifiers stack additively; and morale tiers have hysteresis bands to prevent flickering when an elf hovers near a boundary.

How It Works

Needs

Needs live on a 0-100 scale. Each need decays automatically every tick (or every Nth tick). When a need drops below a threshold, the elf's behavior tree redirects them toward satisfying it before doing productive work.

(Source: crates/er-sim/src/sim/components.rs, Needs::full(); crates/er-sim/src/sim/systems/needs.rs, rest_decay_system(), sustenance_decay_system(), beauty_decay_system(), stimulation_decay_system(), company_system())

Need Status Labels

The game displays a named tier for each need value:

(Source: src/sim/components.rs, need_label(), need_char())

Company (the 5th Need)

Company is unique: its behavior depends on the elf's Social aesthetic axis (0.0 = Personal, 1.0 = Social).

The proximity check uses Manhattan distance. Company ticks every 2nd tick, same as Beauty and Stimulation.

(Source: crates/er-sim/src/sim/systems/needs.rs, company_system())

Mood Stack

Mood is a collection of active MoodModifiers. Each modifier has:

• description -- human-readable label (e.g. "Ate a meal")
• value -- signed integer bonus/penalty (i8)
• ticks_remaining -- countdown to expiry

Every tick, the mood system decrements ticks_remaining by 1 and removes expired modifiers. Modifiers stack additively.

Morale is computed as:

morale = clamp(base + sum(modifier.value), 0, 100)

where base = 50 (constant).

(Source: src/sim/components.rs, Mood::compute_morale(), Mood::net_mood())

Common Mood Modifiers

(Source: crates/er-sim/src/sim/systems/gathering.rs, eating_system(), resting_system(); crates/er-sim/src/sim/systems/mood.rs, weather_mood_system(), seasonal_mood_system(); crates/er-sim/src/sim/systems/satisfaction.rs, favorite_places_system(), personal_time_system(); crates/er-sim/src/sim/components.rs, Mourning)

Replace vs Push Semantics

• mood.push() -- always adds a new modifier (stacks with existing same-name entries).
• mood.replace() -- if a modifier with the same description exists, refreshes its value and duration; otherwise inserts. Weather modifiers use replace to avoid stacking.

(Source: src/sim/components.rs, Mood::push(), Mood::replace())

Values & Formulas

Morale Tiers

Work Speed Modifier = match morale_state: Inspired => +2, Stressed => -1, else => 0

(Source: crates/er-sim/src/sim/systems/helpers.rs, work_speed_modifier(); crates/er-sim/src/sim/components.rs, morale_state())

Hysteresis Bands

To prevent rapid tier-flickering, transitions require crossing a threshold 3 points beyond the nominal boundary:

If no previous tier exists (e.g. first evaluation), the nominal thresholds (80, 50, 20) are used directly.

(Source: src/sim/components.rs, morale_state_with_hysteresis())

Interactions

• Roles -- morale determines which tasks an elf will accept; Breaking-tier elves refuse all non-critical work.
• Buildings -- Dwellings speed rest recovery (+5/tick vs +2 outdoors); buildings within Manhattan distance 2 count as "shelter" for weather mood modifiers.
• Skills -- work speed modifier from morale applies to gathering and building progress rates.
• Terrain -- terrain beauty values passively restore the Beauty need.
• Resources -- eating consumes 1 Food and restores +30 Sustenance (capped at 100).

Tips

• Rest decays fastest (every tick). Prioritize building Dwellings early to keep rest recovery efficient (+5/tick indoors vs +2 outdoors).
• Sustenance decays slowest (every 4th tick). In a pinch, elves can survive a long time on foraging alone.
• Beauty and Stimulation both decay every 2nd tick starting from 60 (not 100). Build a Garden and Workshop early to prevent mid-game mood dips.
• Company is personality-driven. Social elves (Social > 0.7) need companions nearby; personal elves (Social < 0.3) want solitude. Keep an eye on the aesthetic axes of your colony members.
• Hysteresis means momentum matters. An elf who climbs to Inspired will stay there until morale drops below 77. Plan mood boosts in clusters rather than spreading them thin.
• Weather modifiers use replace semantics, so you will never see "Caught in rain" stacked five times. But one-time events (first ancient grove visit) do stack with ongoing weather effects.

Resources

Overview

The settlement stockpile holds four resource types used for construction, feeding, and crafting. Resources are gathered from map sources, deposited at buildings, and consumed by various systems. Seasonal multipliers and passive foraging prevent hard starvation while still making resource management meaningful.

How It Works

Resource Types

(Source: src/sim/world.rs, Resources::starting())

Gathering Pipeline

The full resource loop is:

1. Task Decision -- an idle elf decides to gather a resource type based on role, policy priority, or the most_needed_resource() fallback.
2. Pathfinding -- the elf walks to the nearest ResourceSource of that type.
3. Gathering -- once at the source and with no remaining path, the elf accumulates progress each tick.
4. Pickup -- at progress >= 100, the elf picks up 5 units of the resource and the source loses 1 amount.
5. Return -- the elf pathfinds back to the nearest building.
6. Deposit -- at a building tile, carried resources are added to the stockpile.

Gathering Progress Rate = (5 + gathering_skill) + work_speed_modifier (minimum 1)

At completion, the elf gains 10 XP toward the Gathering skill.

(Source: crates/er-sim/src/sim/systems/gathering.rs, gathering_system(), deposit_system(), return_to_stockpile_system())

Most-Needed Resource Fallback

When no role or policy dictates a specific resource, the system picks the resource with the lowest current stock:

if food <= wood && food <= stone -> Food
else if wood <= stone            -> Wood
else                             -> Stone

FineWood is never selected by this fallback.

(Source: crates/er-sim/src/sim/systems/helpers.rs, most_needed_resource())

Resource Priority Override

Cultural policies can set a resource_priority list. If the top-priority resource has stock < 10, it overrides the elf's role-based gathering choice.

(Source: crates/er-sim/src/sim/systems/behavior.rs, decide_default())

Values & Formulas

Passive Foraging

Elves with Sustenance < 40 passively forage every 10th tick when standing on a walkable, non-stone, non-wall tile. This is an automatic safety net -- no task decision required.

Foraging restores Sustenance directly (not stockpile Food). It caps at 60, preventing full satisfaction from foraging alone.

(Source: crates/er-sim/src/sim/systems/gathering.rs, foraging_system())

Eating

When an elf performs the Eat task at a building with Food in the stockpile:

• Consumes 1 Food from stockpile
• Restores +30 Sustenance (capped at 100)
• Applies mood modifier: "Ate a meal" +5 for 50 ticks

(Source: crates/er-sim/src/sim/systems/gathering.rs, eating_system())

Season Foraging Multiplier

The climate system provides a seasonal multiplier that affects foraging yields:

(Source: src/sim/climate.rs, Climate::season_foraging_multiplier())

Note: Seasons last 25 days each (100 days per year).

(Source: src/sim/climate.rs, SEASON_LENGTH, YEAR_LENGTH)

Resource Source Regeneration

At dawn each day, resource sources regenerate +1 amount, up to a cap:

(Source: crates/er-sim/src/sim/systems/building.rs, regeneration_system())

Gathering Yield

When gathering completes (progress reaches 100):

• Elf picks up 5 units of the resource
• Source loses 1 amount
• Elf gains 10 Gathering XP

(Source: crates/er-sim/src/sim/systems/gathering.rs, gathering_system())

Daily Rate Tracking

The stockpile tracks net change per resource per day. At each dawn, Resources::snapshot_day() computes the delta from the previous day's snapshot. This powers the daily rate display in the UI.

(Source: src/sim/world.rs, Resources::snapshot_day(), Resources::daily_rate())

Interactions

• Needs & Mood -- Sustenance below 20 triggers critical need behavior; eating gives a +5 mood boost.
• Roles -- Gatherer role defaults to Wood; Builder role defaults to Stone. Resource priority can override both.
• Buildings -- construction consumes resources from the stockpile; deposits require proximity to a building.
• Skills -- Gathering skill increases collection speed via the progress rate formula.
• Terrain -- foraging yields differ by terrain type; forest tiles give +8, other walkable tiles give +5.

Tips

• Build a Feast Hall early -- elves performing the Eat task need to be at a building tile. Without buildings, the eating pipeline stalls even with Food in the stockpile.
• Watch the daily rates. Negative Food rate means you are consuming faster than you gather. Assign a Gatherer role or raise Food in the priority list.
• FineWood is scarce. Sources cap at 5 and it starts at only 3 in the stockpile. Treat it as a strategic reserve.
• Foraging caps at 60 Sustenance. Elves can survive on foraging alone, but they will never be "Fulfilled" (80+) without proper meals from the stockpile.
• Winter halves foraging. Stockpile Food in Autumn (1.25x) to buffer the Winter deficit (0.5x).
• Resource priority < 10 triggers override. If your top-priority resource drops below 10, all Unassigned elves switch to gathering it regardless of their normal behavior.

Roles

Overview

Each elf can be assigned one of four roles that influence their task selection, default gathering target, and behavior under the Cultural Policies system. Roles are assigned by the patron (or AI curator) and stored in the CulturalPolicies::workshop_assignments map. Unassigned elves follow a general-purpose behavior tree.

How It Works

Role Types

(Source: src/sim/components.rs, enum ElfRole)

Role Assignment

Roles are set via CulturalPolicies::workshop_assignments, a map from elf name to ElfRole. If an elf's name is not in the map, they default to ElfRole::Unassigned.

role = workshop_assignments.get(name).unwrap_or(Unassigned)

(Source: src/sim/world.rs, CulturalPolicies::role_for())

Role-Resource Linkage

Each role has a default resource it will gather when sent to decide_default():

(Source: src/sim/world.rs, CulturalPolicies::role_resource())

Values & Formulas

Task Decision Priority

The behavior tree (task_decision_system) evaluates priorities in strict order. Roles only matter at Steps 3c and 4 -- critical needs always come first.

(Source: crates/er-sim/src/sim/systems/behavior.rs, task_decision_system())

Default Behavior (decide_default)

When an elf reaches the default branch:

1. Check resource_priority[0] -- if that resource stock < 10, gather it (override).
2. Otherwise, if the elf's role has a role_resource, gather that.
3. Otherwise, use resource_priority[0] if set.
4. Otherwise, gather most_needed_resource() (lowest stock of Food/Wood/Stone).
5. If no source exists for the chosen resource, fall back to most-needed.
6. If still no source, Wander.

(Source: crates/er-sim/src/sim/systems/behavior.rs, decide_default())

Build Queue Assignment

When the build queue is non-empty and resources are available:

1. Prefer idle elf with Builder role.
2. Then any idle elf.
3. Then any Builder-role elf on a non-critical task (Sustenance >= 40 and Rest >= 40).
4. Only one elf builds at a time (no double-assignment).

(Source: crates/er-sim/src/sim/systems/building.rs, build_queue_system())

Preemption Rules

Active tasks can be interrupted when needs become critical:

When preempted, the elf's task is set to Idle, their path is canceled, and any carried resources are dropped (lost). Construction tasks get a lower preemption threshold to avoid interrupting nearly-finished builds.

(Source: crates/er-sim/src/sim/systems/behavior.rs, task_decision_system(), Phase 0)

Revel Attendance Override

Elves attending an active revel skip the entire behavior tree. The RevelAttending marker component is checked first, and those elves are excluded from all task decisions until the revel ends.

(Source: crates/er-sim/src/sim/systems/behavior.rs, task_decision_system())

Role Behavior Summary Table

Interactions

• Needs & Mood -- critical needs always override role behavior; morale tier affects willingness to work.
• Resources -- role determines which resource an elf gathers by default; resource priority can override role.
• Skills -- high Music skill (>= 7) self-selects to Compose regardless of role; high Building skill (>= 7) self-selects to Build.
• Buildings -- Builders are prioritized for the build queue; Composers require a Workshop.

Tips

• Composer is the only role that directly affects task selection at Step 4. Builder and Gatherer mostly influence which resource is gathered in the default branch.
• Skill-driven preferences (Step 3c) bypass role. An elf with Music 7+ will self-select to compose even if unassigned. Assign roles primarily for lower-skill elves.
• Aspirations (Step 3b) also bypass role. Elves pursuing a "compose works" aspiration will compose without needing the Composer role.
• Builders get pulled from non-critical tasks to fill the build queue. Make sure your Builder has adequate Sustenance and Rest (>= 40 each) or they will be skipped.
• Unassigned is not idle. Unassigned elves still gather the most-needed resource or follow the resource priority list. In a small settlement, leaving everyone Unassigned is a valid strategy.
• Resource priority override is powerful. Setting a priority resource effectively overrides all non-Builder roles when that resource drops below 10 units.

Skills

Overview

Every elf has four skill proficiencies -- Music, Building, Gathering, and Stewardship -- each on a 1-10 scale. Skills level up through XP accumulation, improve task efficiency, and influence composition quality. At higher levels, skills can drive autonomous behavior: a Music-7 elf will self-select to compose even without a role assignment.

How It Works

Skill Types

All skills start at level 1 with 0 XP.

(Source: src/sim/components.rs, struct Skills, impl Default for Skills)

XP and Leveling

XP accumulates per-skill. When accumulated XP reaches the threshold for the current level, the elf levels up and excess XP carries over.

XP Threshold = level x 50

(Source: src/sim/components.rs, Skills::xp_threshold())

The maximum skill level is 10. XP gains are ignored at level 10.

(Source: src/sim/components.rs, Skills::add_xp())

Full XP Table

Formula: Cumulative XP to reach level L = sum(i=1..L-1) of i*50 = 25 * L * (L-1).

XP Sources

(Source: crates/er-sim/src/sim/systems/gathering.rs, gathering_system(); crates/er-sim/src/sim/systems/building.rs, building_progress_system(); crates/er-sim/src/sim/systems/compose.rs, compose_system(); crates/er-sim/src/sim/fauna_systems.rs, animal_bond_system())

Values & Formulas

Gathering Progress

progress_rate = (5 + gathering_skill) + work_speed_modifier

Progress starts at 0 and completes at 100. At completion, the elf picks up 5 units and gains 10 Gathering XP.

work_speed_modifier: Inspired = +2, Normal = 0, Stressed = -1. Minimum rate is 1.

(Source: crates/er-sim/src/sim/systems/gathering.rs, gathering_system(); crates/er-sim/src/sim/systems/helpers.rs, work_speed_modifier())

Building Progress

progress_rate = (5 + building_skill) + work_speed_modifier

Same formula as gathering. Completes at 100. Grants 15 Building XP.

(Source: crates/er-sim/src/sim/systems/building.rs, building_progress_system())

Composition Speed

Composition duration scales inversely with Music skill:

duration = max(50 - music_skill * 2, 30)

Progress rate per tick = 100 / duration (minimum 1).

(Source: src/sim/art.rs, compose_duration())

Composition Quality

Music skill directly drives the mastery quality axis:

mastery = clamp(music_skill * 10 + random(-5..+5), 0, 100)

A level-10 musician produces mastery scores around 95-105 (clamped to 100). A level-1 musician produces mastery around 5-15.

Originality depends on inspiration total; emotional depends on net mood.

(Source: src/sim/art.rs, compute_quality())

Stewardship and Animal Bonding

Stewardship governs how quickly an elf can bond with settlement animals and which species they can bond with at all.

Bond growth rate = 1 + (stewardship_level / 3), clamped to 1--5 per bonding tick (every 50 ticks).

Curious species can be bonded by any elf. Tolerant species require Stewardship >= 3. Shy species cannot be bonded.

When an animal bond reaches strength 60, the animal becomes a companion -- it receives a name and the elf gets a +20 Stewardship XP bonus.

See Fauna for the full animal bonding system.

(Source: crates/er-sim/src/sim/fauna_systems.rs, animal_bond_system())

Skill-Driven Behavior Thresholds

These thresholds bypass role assignment -- the elf follows their expertise automatically.

(Source: crates/er-sim/src/sim/systems/behavior.rs, task_decision_system(), Step 3c skill-driven branch)

Interactions

• Roles -- roles provide a suggestion for default behavior; high skill levels provide an override at Step 3c.
• Needs & Mood -- morale affects work speed modifier: Inspired (+2), Stressed (-1).
• Resources -- gathering skill controls how fast resources are collected.
• Buildings -- building skill controls construction speed; completion awards 15 XP.
• Fauna -- stewardship skill gates bonding with settlement animals. Higher levels bond faster and can bond Tolerant species.

Tips

• XP scales quadratically. Getting from level 1 to 5 takes 550 cumulative XP. Getting from 5 to 10 takes another 1,950. Late levels are a long grind.
• Music XP trickles in at 1/tick while composing. Even at the slow rate, a composer working full-time levels up steadily. Building XP comes in bigger chunks (15 per completion) but less frequently.
• Level 7 is the magic number. At Music 7 or Building 7, elves start self-directing. This is the threshold where specialization pays off without needing explicit role assignment.
• Work speed modifier matters most at low skill. The Inspired +2 bonus on a skill-1 elf increases their rate from 6 to 8 (33% faster). On a skill-10 elf, it goes from 15 to 17 (13% faster). Keep your rookies happy.
• Composition quality tracks mastery closely with music skill. A skill-10 composer produces consistently excellent mastery. Invest in your top musician for the best compositions.

Terrain

Overview

The map is a 2D grid of terrain tiles that determine movement, beauty, foraging yields, and resource placement. Six terrain types form three functional zones: the settlement clearing (Meadow), the surrounding forest ring (Ancient and Young Forest), and the outer wilderness (mixed, with obstacles).

How It Works

Terrain Types

(Source: src/sim/components.rs, enum Terrain, walkable(), is_forest(), beauty_value())

Walkability

Elves can move on any tile except Water and Wall. The pathfinding system uses walkability to compute valid routes.

walkable = !matches!(terrain, Water | Wall)

(Source: src/sim/components.rs, Terrain::walkable())

Beauty Restoration

Each tick, the terrain_effect_system checks the elf's current tile and all four adjacent tiles (N, S, E, W). The highest beauty value among these five tiles is added to the elf's Beauty need.

beauty_gain = max(current_tile.beauty_value, adjacent_tiles.beauty_value)

Seasonal overrides:

(Source: crates/er-sim/src/sim/systems/terrain.rs, terrain_effect_system())

Stream Adjacency

If any adjacent tile is Water, the elf gains a solitude inspiration bonus (+1 every 10 ticks).

(Source: crates/er-sim/src/sim/systems/terrain.rs, terrain_effect_system())

Inspiration from Terrain

Every 10 ticks:

(Source: crates/er-sim/src/sim/systems/terrain.rs, terrain_effect_system())

First-Visit Mood

The first time an elf enters an AncientForest tile, they receive:

• Mood modifier: "Awed by ancient grove" +2 for 200 ticks

This is tracked per-elf via VisitedTerrains and only fires once.

(Source: crates/er-sim/src/sim/systems/terrain.rs, terrain_effect_system(); src/sim/components.rs, VisitedTerrains)

Values & Formulas

Foraging Yields by Terrain

Foraging caps at 60 Sustenance (elves cannot reach "Fulfilled" from foraging). Stone is explicitly excluded from foraging despite being walkable.

Wait -- re-reading the source: Stone is excluded in foraging_system() by the check !matches!(terrain, Terrain::Stone | Terrain::Wall).

(Source: crates/er-sim/src/sim/systems/gathering.rs, foraging_system())

Resource Sources

Resource sources are separate entities placed on map tiles. Their type determines what can be gathered there. Sources regenerate +1 per dawn, up to a cap of 10 (5 for FineWood).

(Source: crates/er-sim/src/sim/systems/building.rs, regeneration_system())

Map Generation

Maps are generated with three concentric zones:

Zone 1: Settlement Clearing (center)

• Radius: max(min(width, height) * 0.15, 5.0) tiles from center
• Mostly Meadow
• A narrow stream (Water) runs through the center

Zone 2: Forest Ring

• Extends 3 tiles beyond the clearing radius
• 65% forest (inner half = AncientForest, outer half = YoungForest)
• 10% Stone
• 25% Meadow

Zone 3: Outer Wilderness

• Everything beyond the forest ring
• Distribution:

(Source: src/sim/map.rs, generate_map())

Default map size: 40 x 30.

Interactions

• Needs & Mood -- terrain beauty restores the Beauty need; first-visit moods add to the mood stack.
• Resources -- foraging yields vary by terrain; resource sources are placed on specific tiles.
• Buildings -- buildings are placed on walkable tiles; the settlement clearing provides the main building area.
• Skills -- terrain does not directly affect skill gains, but proximity to forest tiles enables passive beauty restoration that keeps elves happy and productive.

Tips

• AncientForest is the most valuable terrain. Beauty 2, +1 Nature inspiration every 10 ticks, first-visit mood bonus, and best foraging yield. Build paths (or settle) near AncientForest tiles.
• Autumn is peak beauty season. AncientForest beauty jumps to 3 in Autumn. Plan revels and creative work for this season.
• Winter kills YoungForest beauty. Bare branches mean 0 beauty value. Make sure you have a Garden or AncientForest access to compensate.
• The center stream is a double-edged tile. Water blocks movement but gives adjacent elves solitude inspiration. Build near it, not on it.
• Stone terrain is walkable but not forageable. Elves can cross Stone tiles freely but will not passively forage there.
• Wall tiles (2% of outer wilderness) are impassable obstacles. They can block pathfinding to outer resource sources. Scout the map for bottlenecks.

Buildings

Overview

Buildings are permanent structures placed on the map via the build queue. They provide shelter from weather, enable critical tasks (eating, resting, composing), and buff nearby elves. Four building types cover the settlement's needs: housing, crafting, aesthetics, and communal gathering.

How It Works

Building Types

(Source: src/sim/components.rs, enum BuildingType)

Build Costs

(Source: crates/er-sim/src/sim/systems/building.rs, build_cost())

Build Queue

Buildings are constructed through the build queue system:

1. The patron or AI curator adds a QueuedBuild (type + site position) to CulturalPolicies::build_queue.
2. build_queue_system() checks if the settlement can afford the top item.
3. If affordable, it assigns an idle elf (preferring Builders) and deducts resources immediately.
4. The assigned elf pathfinds to the build site and begins construction.
5. Only one build is active at a time (no double-assignment).

(Source: crates/er-sim/src/sim/systems/building.rs, build_queue_system())

Builder Assignment Priority

When a build is ready to start:

Builder-role elves on critical tasks (Eat, Rest, Build, ClearForest) or with low needs are not reassigned.

(Source: crates/er-sim/src/sim/systems/building.rs, build_queue_system())

Values & Formulas

Construction Progress

progress_rate = (5 + building_skill) + work_speed_modifier

Construction completes when progress reaches 100. Minimum rate is 1.

work_speed_modifier: Inspired = +2, Normal = 0, Stressed = -1.

On completion, the builder gains 15 Building XP.

(Source: crates/er-sim/src/sim/systems/building.rs, building_progress_system(); crates/er-sim/src/sim/components.rs, Skills::add_xp())

Shelter Radius

Buildings classified as shelter (Dwelling, Workshop, Feast Hall) protect elves within Manhattan distance <= 2 from weather penalties.

is_indoors = any shelter building within Manhattan distance 2 of elf

Garden does not count as shelter.

(Source: crates/er-sim/src/sim/systems/mood.rs, weather_mood_system())

Weather Mood Effects (Shelter-Dependent)

(Source: crates/er-sim/src/sim/systems/mood.rs, weather_mood_system())

Rest Recovery

Resting elves recover at different rates depending on proximity to a Dwelling:

Resting completes when Rest reaches 80 ("Fulfilled" threshold).

(Source: crates/er-sim/src/sim/systems/gathering.rs, resting_system())

Eating

Elves perform the Eat task at any building tile (not just Feast Halls). Eating consumes 1 Food from the stockpile and restores +30 Sustenance.

(Source: crates/er-sim/src/sim/systems/gathering.rs, eating_system())

Composing

Composing requires presence at a Workshop tile with no remaining path. Composition duration scales with Music skill (see Skills for the formula).

(Source: crates/er-sim/src/sim/systems/compose.rs, compose_system())

Garden and Creative Block

Elves with Creative Block seek a Garden. The Garden does not directly restore beauty via a building buff -- instead, Gardens are typically placed near forest tiles where the terrain_effect_system provides passive beauty restoration. Creative Block drives the elf to the Garden as a waypoint.

(Source: crates/er-sim/src/sim/systems/behavior.rs, task_decision_system(), Step 2)

Interactions

• Resources -- build costs are deducted from the stockpile when construction starts; deposits require proximity to any building.
• Needs & Mood -- Dwellings provide faster rest recovery (+5 vs +2) and a positive mood modifier; sheltered buildings prevent rain mood penalties.
• Roles -- Builder role elves are prioritized for construction assignments.
• Skills -- Building skill determines construction speed; completion grants 15 XP.
• Terrain -- buildings must be placed on walkable tiles; Gardens are most effective near forest terrain for beauty synergy.

Tips

• Build order matters. A Dwelling first ensures Rest recovery is efficient. A Workshop second enables composing and Stimulation restoration. Garden third handles Beauty needs.
• Feast Hall is expensive but versatile. At 15 Wood + 5 Stone, it is the costliest building. But it serves as shelter, eating location, and social gathering point for elves pursuing social aspirations.
• Garden is cheap and essential. At only 5 Wood, it is the most cost-effective building. Place it adjacent to AncientForest tiles to maximize beauty synergy.
• Shelter radius is Manhattan 2. Buildings placed 1 tile apart create overlapping shelter zones. Cluster buildings to cover the most elves.
• One build at a time. The system prevents multiple simultaneous constructions. Queue your builds in priority order; the next one starts automatically when the current one finishes.
• Resources are deducted immediately when a build starts, not when it finishes. If a builder gets interrupted, the resources are still consumed. Make sure your builder has adequate needs before starting expensive constructions.
• Outdoor resting gives a mood penalty. Without a Dwelling, elves who rest get "Slept on ground" (-3 for 50 ticks). This stacks with weather effects and can spiral morale downward in early game.

Compositions

Overview

Compositions are the primary creative output of an elven settlement. When an elf with the Composer role (or any elf choosing to compose) finishes a composing task, the simulation generates a unique musical work with a procedurally generated name, title, description, quality scores, and special properties. Compositions are permanent artifacts stored in the settlement's portfolio and performed at Revels.

Every composition encodes the emotional and aesthetic state of its creator at the moment of creation. Two compositions by the same elf in different moods will sound completely different.

How It Works

Composing Duration

The time to compose is determined by music skill. Higher skill means faster work, but there is a floor of 30 ticks:

Duration = max(50 - skill x 2, 30) ticks

Source: src/sim/art.rs, compose_duration

Genre Families

Every composition belongs to one of three genre families, selected based on the composer's Aesthetic Position and Inspiration.

Genre Selection Algorithm

Genre selection proceeds in two stages: a cross-genre surprise check, then a weighted probability roll with seasonal bias.

Stage 1 -- Cross-genre surprise (8%)

Before any probability calculation, the system rolls a uniform random check. If the roll is below 0.08 (8% chance), a genre is picked uniformly at random from all three families, ignoring the composer's aesthetic position, inspiration, and season entirely. This means roughly once per 20-day session, even a deeply traditional elf might compose something radical.

Source: src/sim/art.rs, select_genre_seasonal -- if surprise < 0.08 at line 97.

Stage 2 -- Weighted probability

If the surprise check does not fire (92% of the time), base probabilities are computed from the composer's state:

All three probabilities are then adjusted by seasonal bias:

After bias is applied, the three values are summed to a total and a weighted random roll selects the genre. The probabilities are not renormalized to 1.0 before rolling -- the roll range is [0, total), so seasonal bias effectively increases the absolute weight of one family rather than redistributing from others.

Example at tradition=0.5, no nature dominance, Summer:

Source: src/sim/art.rs, select_genre (base logic, lines 55--85) and select_genre_seasonal (with season, lines 89--128)

Base Types (Skill Tiers)

Within each genre, the composer's music skill determines which tier of base type is available. There are 4 tiers per genre (12 total):

Source: src/sim/art.rs, select_base_type

Values & Formulas

Quality Scores

Each composition has three quality dimensions scored 0-100:

Average quality = (mastery + originality + emotional) / 3

Elegy bonus: Compositions created while an elf is mourning a departed friend receive +15 to the emotional score.

Source: src/sim/art.rs, compute_quality; src/sim/components.rs, quality_avg, quality_tier

Composition Properties

Properties are special tags earned from creation conditions. Each composition carries up to 2 behavioral properties plus an always-present seasonal property and an optional Stormborn premiere marker.

Condition properties (checked in order):

Compound inspiration properties (require two channels both > 30):

Source: crates/er-sim/src/sim/systems/compose.rs; crates/er-sim/src/sim/components.rs, CompositionProperty

Seasonal Properties

Every composition automatically receives one seasonal property based on the season it was completed in. This does not count toward the 2-property cap -- it's always first in the property list.

Seasonal properties interact with the resonance scoring system at performance time. A Vernal composition performed in Spring gets +5 audience goodwill; the same composition in Winter gets -1.

Stormborn is a special premiere-time property. When a composition is performed for the first time during Storm weather, it gains the Stormborn property. This is permanent, rare, and stacks with the seasonal property. A "Hibernal Stormborn" composition is a winter piece that debuted in a storm -- the kind of memorable event that defines a colony's cultural history.

Source: crates/er-sim/src/sim/components.rs, CompositionProperty::for_season; crates/er-sim/src/sim/systems/revel.rs, Stormborn attachment.

Lineage Property: InStyleOf

Compositions written by an active apprentice carry an additional InStyleOf({master_name}) property -- displayed as Style: {master_name}. Like seasonal and Stormborn, it is cap-exempt: it is appended after the 2-property truncation, so it never displaces a behavioral property.

The marker is informational only -- it does not affect quality scores, audience reactions, or revel resonance. It exists to record cultural lineage: which master shaped which works. The property is attached only while the apprenticeship bond is active. Compositions written after graduation do not carry it; the lineage instead lives in the student's permanent TrainedBy component.

Source: crates/er-sim/src/sim/systems/compose.rs, lines 189-192; crates/er-sim/src/sim/components.rs, CompositionProperty::InStyleOf.

Creative Block

Three or more consecutive compositions with average quality below 50 give a 30% chance of triggering a creative block. Duration is 100 to 200 ticks (random). During a block, the elf refuses to compose and seeks a Garden instead.

Source: crates/er-sim/src/sim/systems/compose.rs, ConsecutiveMediocre, creative block trigger logic

Name Generation

Composition names follow the structure "{Prefix} {Base Type} {Suffix}".

Prefix is selected from mood tier pools, with two override conditions checked first:

Suffix comes from the dominant inspiration source:

Title Generation

In addition to the composition name, each work gets a short and long title pair. The short title is drawn from a pool matching the dominant inspiration source (e.g., "Still Water", "The Argument"). The long title appends a mood modifier (e.g., "Still Water, in the Rain").

Source: src/sim/art.rs, generate_name, generate_title

Interactions

• Inspiration -- Originality score and compound properties depend on inspiration channels
• Aesthetic Position -- Determines genre family selection and composition aesthetic snapshot
• Revels -- Compositions are performed at revels where audience reactions are computed
• Needs & Mood -- Mood drives the emotional score and name prefix selection
• Skills -- Music skill determines mastery score, base type tier, and compose duration
• Artistic Direction -- Patron direction influences which elves the curator assigns as Composers
• Seasons & Weather -- Season at completion determines the seasonal property; Storm weather during premiere can trigger Stormborn
• Apprenticeship -- An apprentice's compositions carry the cap-exempt InStyleOf({master}) lineage marker

Tips

• A skill-10 elf with high inspiration and good mood can produce a Magnum Opus -- the rarest property in the game. Protect your best musicians from mood crashes.
• Creative blocks are not purely bad: composing during a block earns the Cathartic property, which is otherwise unobtainable.
• Seasonal genre bias means Winter is the best time for Pastoral works and Summer for Radical. Plan revel timing accordingly.
• The 8% cross-genre surprise means even a deeply traditional elf occasionally writes something radical. This is intentional and can spark interesting audience reactions.
• Compositions with the Elegy property are only possible when an elf is mourning -- these tend to have very high emotional scores due to the +15 bonus.

Inspiration

Overview

Inspiration is the creative fuel that drives composition quality. Every elf has five independent inspiration channels that accumulate from different experiences. These channels feed into the originality score of Compositions, determine which composition properties are earned, and influence genre selection.

Inspiration is not a single number -- it is a 5-dimensional creative profile that reflects how an elf has been inspired, not just how much.

How It Works

The Five Channels

Each channel is a u8 value (0-255 per channel, but the total is capped):

Total Inspiration

The total is the sum of all five channels, capped at 100 for threshold checks:

Total = min(nature + social + rivalry + beauty + solitude, 100)

This cap means that a broadly inspired elf (moderate across all channels) reaches the ceiling just as easily as a deeply specialized one.

Source: src/sim/components.rs, Inspiration::total

Dominant Source

The channel with the highest value is the "dominant source." This determines:

• The suffix of composition names (e.g., "of the Silver Wood" for Nature)
• The title pool for short/long titles
• Which channel receives a +5 boost from Love reactions at revels
• Genre selection bias (Nature dominance with value > 40 favors Pastoral)

Ties are broken by priority order: Nature > Social > Rivalry > Beauty > Solitude.

Source: src/sim/components.rs, Inspiration::dominant_source

Values & Formulas

Inspiration Equilibrium

Each elf has a natural equilibrium for their inspiration channels, derived from their Aesthetic Position. The equilibrium represents where the elf's inspiration naturally gravitates:

Example: An elf with aesthetic position (structure=0.3, tradition=0.2, emotion=0.7, social=0.8) would have equilibrium:

• Nature: (1.0 - 0.3) x 20 = 14
• Social: 0.8 x 25 = 20
• Rivalry: (1.0 - 0.2) x 15 = 12
• Beauty: (0.3 + 0.2) x 10 = 5
• Solitude: (1.0 - 0.8) x 25 = 5

Source: src/sim/components.rs, InspirationEquilibrium::from_aesthetic

Seeding from Equilibrium

When an elf's inspiration is initialized from equilibrium, the system guarantees a minimum total of 25 by boosting the highest-equilibrium channel in increments of 5 until the floor is reached.

Source: src/sim/components.rs, Inspiration::from_equilibrium

Impact on Composition Quality

Inspiration total feeds directly into the Originality score:

Originality = inspiration_total x 0.6 + random(0..20), clamped 0-100

An elf with 0 total inspiration will produce originality scores of 0-20 (random noise only). An elf with 100 total inspiration will score 60-80 on average.

Revel Inspiration Boost

When an elf has a Love reaction to a composition at a revel, their dominant inspiration channel receives +5 (capped at 100 per channel).

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system Love reaction handler

Composition Property Thresholds

Inspiration channels interact to create special composition properties when two channels both exceed 30:

See Compositions for the full property system.

Creative Block

Trigger Mechanism

When an elf produces three or more consecutive compositions with average quality below 50, each subsequent composition has a 30% chance of triggering a creative block.

A composition with quality >= 50 resets the consecutive mediocre counter to zero.

Block Duration

Creative block lasts 100 to 200 ticks (randomly determined).

Block Effects

• The elf refuses to compose and instead seeks a Garden
• The elf is excluded from revel attendance
• If the elf manages to compose during a block (e.g., forced by circumstances), the composition earns the Cathartic property
• Critical needs (rest, sustenance below 20) override block behavior -- the elf will seek a Dwelling to rest even during a block

Source: crates/er-sim/src/sim/components.rs, CreativeBlock, ConsecutiveMediocre; crates/er-sim/src/sim/systems/compose.rs and crates/er-sim/src/sim/systems/behavior.rs, creative block trigger and behavior tree

Interactions

• Compositions -- Inspiration drives originality score and enables compound properties
• Aesthetic Position -- Determines inspiration equilibrium values
• Revels -- Love reactions boost dominant inspiration channel by +5
• Needs & Mood -- Mood and inspiration together determine emotional and originality scores
• Terrain -- Forest and garden proximity builds Nature and Beauty inspiration

Tips

• An elf's equilibrium is fixed by their aesthetic position. To shift where inspiration naturally gravitates, you need to shift the elf's aesthetics (via friend drift, school drift, or revel audience drift).
• The Solitude and Social channels are in natural tension: an elf with high social axis will have high Social equilibrium but low Solitude equilibrium, and vice versa. This makes the Bittersweet property (Social > 30 AND Solitude > 30) one of the harder compound properties to earn.
• Keep an eye on Nature inspiration for potential Pastoral genre selection. An elf needs Nature as their dominant source AND nature > 40 for the 60% Pastoral bias to kick in.
• The total cap of 100 means you do not need all channels maxed out. A specialist with 80 in one channel and 20 spread across others already hits the cap.
• Creative blocks are recoverable. Place a Garden nearby and the elf will seek it out. The block self-resolves after 100-200 ticks.

Aesthetic Position

Overview

Every elf has a 4-axis aesthetic position that defines their artistic taste and creative identity. This is the most influential hidden stat in the game: it determines which genre an elf composes in, how they react to others' art at Revels, their natural Inspiration equilibrium, and whether they feel alienated from the settlement's cultural center.

Aesthetic positions drift over time through four independent mechanisms -- friendship proximity, revel audience exposure, school influence, and apprenticeship bonds -- creating emergent cultural movements without any scripting. See Drift Mechanics below for how they combine.

How It Works

The Four Axes

Each axis is a continuous float from 0.0 to 1.0. The "opposite" of any value is simply 1.0 - value -- there are no separate fields for opposing poles.

New elves are assigned a uniformly random position on all four axes.

Source: src/sim/components.rs, AestheticPosition

Distance Metric

Aesthetic distance between two elves (or between an elf and a composition) uses Euclidean distance in 4D space:

distance = sqrt((s1-s2)^2 + (t1-t2)^2 + (e1-e2)^2 + (sc1-sc2)^2)

Since each axis ranges 0.0-1.0, the maximum possible distance is:

max distance = sqrt(1^2 + 1^2 + 1^2 + 1^2) = 2.0

Two elves at diametrically opposite corners of the aesthetic space are exactly 2.0 apart. Elves within about 0.5 distance are aesthetically compatible; beyond 1.0 they are quite different.

Source: src/sim/components.rs, AestheticPosition::distance_to

Values & Formulas

Audience Evaluation Weights

When an elf evaluates a composition at a revel, their aesthetic position determines how much they weight each quality dimension. The raw weights before normalization:

These three weights are then normalized to sum to 1.0. The raw sum ranges from about 1.15 to 1.85 depending on position.

The final audience score is:

score = mastery x w_mastery + originality x w_originality + emotional x w_emotional

A social modifier then adjusts the score:

• Social axis > 0.7: +5 points (crowd energy)
• Social axis < 0.3: -3 points (crowd discomfort for introverts)

Source: src/sim/art.rs, evaluate_audience

Genre Affinity

The tradition axis is the primary driver of genre selection:

The exact formula:

p_radical = max((1.0 - tradition - 0.5) x 1.5, 0.0)

At tradition=1.0, p_radical=0. At tradition=0.0, p_radical=0.75.

Source: src/sim/art.rs, select_genre

Inspiration Equilibrium

Aesthetic position determines the natural resting state of each inspiration channel:

See Inspiration for full details.

Source: src/sim/components.rs, InspirationEquilibrium::from_aesthetic

Drift Mechanics

Aesthetic positions are not static. Four independent drift mechanisms slowly reshape the cultural landscape of the settlement: friend proximity, revel audience exposure, school influence from successful composers, and apprenticeship. Together they are the engine of emergent cultural movements -- no scripting, no designer-placed factions, just small daily nudges that accumulate into settlement-wide artistic identity.

How Drift Direction Works

All four drift systems use signum-based drift: the direction is determined by the sign of the difference, but the magnitude is a fixed step. This means a friend whose tradition is 0.51 (when yours is 0.49) pulls you the same 0.01 as a friend whose tradition is 0.99.

This is a ratchet, not a spring. Distance doesn't amplify drift -- only existence of a difference does. Two consequences players should note:

• Alignment converges slowly, then stops. Once your axis matches a friend's sign-side of theirs, drift continues but by only one step; when you cross to the same side, oscillation can happen at the boundary.
• Extreme taste doesn't pull harder. A radical elf with tradition=0.0 does not exert more force on their friends than a moderately-innovative elf with tradition=0.3 -- the pull is identical, just slower to saturate.

Audience drift (per performance) and apprenticeship drift (toward master) follow the same rule. School drift is the one exception: it pulls toward the sign of the school composer's deviation from 0.5, not toward the composer's exact position.

Friend Drift

When two friends (relationship strength >= 50) are within 3 Manhattan tiles of each other, their aesthetics converge. This runs once per game day.

Rate: 0.01 per axis per day

The drift direction is the sign of the difference: if a friend's structure is higher, the elf's structure increases by 0.01 (and vice versa). All four axes drift independently.

Only friends within 3 tiles are affected. Distant friends do not drift.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, FRIEND_DRIFT_RATE = 0.01, aesthetic_friend_drift_system

Audience Drift (Revel)

When an elf hears a composition performed at a Revel, their aesthetic position drifts toward the composition's aesthetic snapshot (captured at creation time, see Composition Aesthetic Shift below).

Rate: 0.005 per axis per composition heard

This is applied once per composition performed, for every audience member. A revel with 5 performances means up to 5 drift applications per attendee. Because audience drift fires per performance (not per day), a single well-attended revel can out-weigh a full day of friend drift: 5 performances × 0.005 = 0.025, versus the daily friend cap of 0.01.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, AUDIENCE_DRIFT_RATE = 0.005, apply_audience_aesthetic_drift

School Drift

Composers who have received 3 or more Love reactions at revels become aesthetic "schools" -- cultural attractors. Non-friend elves within 5 Manhattan tiles of a school composer drift toward that school's aesthetic.

Rate: 0.008 per axis per day

Unlike friend drift which pulls toward the friend's exact position, school drift pulls toward the direction of the school's aesthetic relative to the center (0.5). If a school composer has structure=0.9, nearby non-friends drift in the positive structure direction by 0.008 per day. If the composer has structure=0.2, nearby non-friends drift in the negative structure direction.

Friends are excluded from school drift because friend drift already handles them.

⚠ Terminology note: The code refers to these composers as "legendary" composers, and SchoolFormed events use that language. This is not the same as the Legendary prestige tier (score 81+). A "school composer" needs only 3 Love reactions ever -- a very low bar that most active composers cross in their first few revels. The Legendary prestige tier is a far higher achievement. Both systems exist; they are not linked.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, SCHOOL_DRIFT_RATE = 0.008, SCHOOL_THRESHOLD = 3, aesthetic_school_drift_system

Apprenticeship Drift

When an elf is in an active apprenticeship bond, they drift toward their master's aesthetic position daily -- provided they remain within 5 Manhattan tiles of the master.

Rate: 0.02 per axis per day (2x the friend rate)

This is the strongest drift in the system. A full season of apprenticeship can shift a student's aesthetic by up to 0.02 × days, enough to move a radical apprentice meaningfully toward their traditional master's values or vice versa. The drift persists after the bond resolves -- imprint, not transient influence.

Apprenticeship drift stacks with friend drift: if the apprentice is also a friend of their master (strength >= 50) and within 3 tiles, both systems apply, producing daily drift of up to 0.03 per axis.

See Apprenticeship for the full apprenticeship system. The drift logic lives alongside other drift systems for co-location.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, APPRENTICE_DRIFT_RATE = 0.02, apprenticeship_aesthetic_drift_system.

Drift Rate Summary

Drift Interactions

Multiple drifts can apply to the same elf on the same day. The rules:

• Friend and school drift are mutually exclusive toward a given composer. School drift only affects non-friends; friends of a school composer get friend drift toward that composer's exact position, not school drift toward their axis direction.
• Apprenticeship and friend drift stack if the apprentice is both a friend and within range of their master.
• Audience drift always stacks with any daily drift -- it runs during revels regardless of what else the elf has going on.
• Multiple friends or schools stack. An elf with three nearby friends gets three friend-drift applications per axis per day (one per friend, using each friend's direction). An elf within range of two schools gets two school-drift applications.

This means a well-integrated elf -- friends nearby, revels frequent, perhaps an apprentice -- can accumulate substantially more drift per day than a reclusive one. Social integration literally shapes taste faster.

Worked Example

Consider Tamsin, an apprentice with two close friends, near one school composer (but not a friend of that composer), who attends a revel with 4 performances one evening. Her daily drift budget for the tradition axis, if every system moves her the same direction:

Tamsin's tradition axis can shift by nearly 7% in one busy day. Over a 20-day season without contradiction, that's a full point on the [0.0, 1.0] scale -- from fully innovative to fully traditional.

A reclusive elf with no friends, no master, not near a school, who doesn't attend the revel: zero drift that day. Aesthetic identity is a social phenomenon in this system; hermits keep whatever aesthetic they started with.

Composition Aesthetic Shift

When a composition is created, its aesthetic snapshot is not identical to the composer's position. Small shifts are applied based on inspiration balance:

This means highly original works drift the composition's tradition axis downward, and highly emotional works drift the emotion axis upward. These shifted values are what audiences drift toward during revels.

Source: crates/er-sim/src/sim/systems/compose.rs, composition aesthetic drift logic in compose_system

Interactions

• Compositions -- Genre family, quality weights, and composition aesthetic all derive from position
• Inspiration -- Equilibrium values are computed from aesthetic position
• Revels -- Audience reactions depend on aesthetic distance; attendance causes drift
• Relationships -- Friends within 3 tiles cause mutual aesthetic convergence
• Apprenticeship -- Apprentices drift toward their master at 2x friend rate
• Prestige -- The "Legendary" prestige tier is distinct from the "school composer" threshold of 3 Love reactions
• Satisfaction & Departure -- Elves far from the settlement's aesthetic center feel alienated

Tips

• Apprenticeship drift is the strongest single source at 0.02/axis/day -- if you want to shift a specific elf's aesthetic deliberately, pair them with a master whose taste you want them to inherit.
• Friend drift (0.01/day) only activates at close range. Housing friends near each other accelerates cultural convergence. Distant friendships have zero aesthetic pull.
• School drift creates emergent "movements." A composer with 3+ Love reactions (the school threshold -- note this is much lower than the Legendary prestige tier) surrounded by non-friend neighbours will gradually pull those neighbours toward their taste direction, creating a coherent artistic identity in that area.
• Audience drift at revels is the main mechanism for settlement-wide cultural coherence. Regular revels with compositions from varied composers spread aesthetic influence broadly. A single 5-performance revel can move an attendee more than a full day of friend drift.
• Drift is a ratchet, not a spring. Taste difference magnitude doesn't amplify the pull -- only presence of difference does. Cultivating radical elves requires many exposures, not fewer-but-more-extreme ones.
• An elf's genre tendency is almost entirely determined by their tradition axis. If you want more Radical compositions, cultivate low-tradition elves by exposing them to innovative works at revels.
• The composition aesthetic shift means that a purely traditional elf who writes a highly original piece will produce a composition that actually nudges audiences away from tradition. Art has a life of its own.
• Hermits keep their starting aesthetic. An elf with no nearby friends, no master, not near a school, who avoids revels, will never drift. Most settlements don't produce hermits accidentally -- isolation has to be engineered or suffered through lifecycle events.
• The maximum aesthetic distance of 2.0 is useful context: two elves at 1.5+ distance are aesthetically alien to each other and will react very differently to the same composition.

Revels

Overview

Revels are the cultural heartbeat of an elven settlement -- communal gatherings where compositions are performed, audience reactions are evaluated, relationships form, and the settlement's aesthetic identity evolves. They are the primary way that art connects to the social fabric: a single revel can boost morale, trigger creative blocks, form new fandoms, and shift the aesthetic landscape of the entire community.

Revels are scheduled by the Curator (or the Dummy Curator's rule-based logic) and require a Feast Hall, food, compositions, and enough available elves.

How It Works

Scheduling Requirements

The Dummy Curator schedules a revel when all of the following are true:

The LLM Curator uses the same information but makes its own judgment call. The player can also influence revel timing through messages to the curator.

Source: src/sim/curator/dummy.rs, revel scheduling logic

Lifecycle Phases

A revel progresses through three phases, each with a fixed tick duration:

None --> Gathering (5 ticks) --> Performing (5 ticks per piece) --> Aftermath (5 ticks) --> None

Phase 1: Gathering (5 ticks)

During gathering, elves walk toward the Feast Hall. Elves are directed to the hall each tick until they arrive or the phase ends:

• Elves with a creative block are excluded from attendance
• Attendance is capped at the settlement's capacity
• Elves who arrive at the hall receive the RevelAttending marker
• Attending elves skip the normal behavior tree for the revel's duration

At the end of the gathering phase, food is consumed:

Food consumed = min(attendee_count, available_food)

If there is not enough food for everyone, all attendees receive a "Sparse feast" mood modifier: -3 for 100 ticks.

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system, Gathering phase

Phase 2: Performing (5 ticks per composition)

Compositions are performed one at a time, newest first. Each performance takes 5 ticks to complete. At the end of each 5-tick window, audience evaluation runs.

For each audience member and each composition:

1. The audience member's aesthetic position determines evaluation weights
2. A weighted score is computed from the composition's mastery, originality, and emotional dimensions
3. A social modifier is applied (+5 for social axis > 0.7, -3 for social axis < 0.3)
4. Discontented elves receive a -5 penalty to their score
5. The score maps to a reaction tier

See Aesthetic Position for the full weight formulas.

Source: src/sim/art.rs, evaluate_audience

Phase 3: Aftermath (5 ticks)

The aftermath phase is a brief wind-down:

• RevelAttending markers are removed from all elves
• The revel zone is detected from attendee positions
• Average audience score is computed across all performances and reactions
• Great/boring revel satisfaction spikes are applied (see below)
• The revel is archived to history with full reaction data
• last_revel_tick is recorded (starts the cooldown timer)

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system, Aftermath phase

Values & Formulas

Mood Effects

Audience reactions produce mood modifiers:

Satisfaction Spikes

Revels directly affect elf satisfaction, which drives the departure system:

These are buffered as "spikes" consumed by the satisfaction system on its next tick, so they integrate properly with the satisfaction recomputation.

Source: crates/er-sim/src/sim/systems/revel.rs, revel satisfaction spike logic in revel_tick_system

Inspiration Boost

A Love reaction boosts the audience member's dominant inspiration channel by +5 (capped at 100 per channel).

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system Love reaction handler

Aesthetic Drift

Every composition heard at a revel nudges all audience members' aesthetic positions toward the composition's aesthetic snapshot:

Drift rate: 0.005 per axis per composition heard

A revel with 4 performances applies up to 4 drift increments per attendee. See Aesthetic Position for details.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, AUDIENCE_DRIFT_RATE = 0.005

Fandom Formation

When an elf has a Love reaction to a composition (and is not the composer), the reaction is recorded in their Fandom memory. Each elf tracks up to 5 fan relationships, pruning the weakest if capacity is exceeded.

When a new fandom forms (first Love reaction for that composer), a FandomFormed event is emitted and archived as a revel incident.

See Fandom for how fan proximity then boosts composer inspiration, strengthens relationships, and emits FanRequest events over time.

Source: crates/er-sim/src/sim/components.rs, Fandom; crates/er-sim/src/sim/systems/fandom.rs, fandom_system; crates/er-sim/src/sim/systems/revel.rs, fandom emission in revel_tick_system

Prestige Update

When a composer's work receives a Love reaction at a revel, their last_love_tick is set to the current tick. This is the heartbeat of the prestige system -- it resets the decay clock.

The prestige score itself is computed every 50 ticks by the prestige_system from three inputs:

Prestige = (recent_loves x 5.0) + (fans x 10.0) + (compositions x 2.0) - decay

The score is clamped to 0--100 and mapped to a tier:

Prestige feeds into satisfaction at a weight of x 0.15 (max +15 at score 100). High-prestige elves also shape the settlement's aesthetic center with up to 3x weight (at prestige 100), making them cultural anchors whose taste disproportionately defines the community norm.

Tier changes emit PrestigeChanged events and are visible in the revel recap.

Source: crates/er-sim/src/sim/systems/prestige.rs, prestige_system; crates/er-sim/src/sim/components.rs, PrestigeTier::from_score

Performance Incidents

Two types of incidents can occur during a revel performance and are archived with the revel record:

PublicCritique

A PublicCritique fires when a rival of the composer gives a Dislike reaction to the performance, stacking an additional -4 mood on the composer (80 ticks) and granting +2 rivalry inspiration to the critic. The total mood hit on the composer is -7 (-3 Dislike + -4 PublicCritique). The incident is also recorded in the revel archive as PerformanceIncident::PublicCritique.

For the full mechanic — when rivalries form, how the conflict system runs, escalation/reconciliation, and how PublicCritique interacts with ego crises — see Rivalries → Public Critique.

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system -- PublicCritique logic.

FandomFormed

When a Love reaction creates a new fan relationship (first Love for that composer), a FandomFormed incident is recorded. See Fandom Formation above for details.

Ego Crisis

When a composer's own work receives a majority negative reception (more than half of audience reactions are Dislike or Indifferent), the composer suffers an ego crisis:

This is separate from (and stacks with) individual Dislike mood penalties and PublicCritique penalties. A composer who is publicly criticized by a rival and gets majority negative reception takes:

• -3 mood (Dislike reaction)
• -4 mood (PublicCritique)
• -30 satisfaction spike (ego crisis)

Ego crises are a significant blow. Combined with the -10 "boring revel" spike (if avg score < 30), a disastrous revel can push a composer toward departure.

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system -- ego crisis at majority negative check.

Dislike Accumulation

When an audience member Dislikes 2 or more performances in a single revel, they receive an additional satisfaction spike:

-20 satisfaction (on top of the per-performance Dislike mood penalties)

This punishes consistently bad revels more than a single weak performance.

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system -- dislike_counts tracking.

School Formation

When a composer accumulates 3 or more Love reactions across revels (tracked in their Aspirations), a SchoolFormed event fires. This marks the composer as a cultural attractor -- their aesthetic position becomes a gravitational center that pulls nearby non-friend elves toward it.

The school drift system runs once per day (every DAY_LENGTH ticks). For each elf who is not a friend of the school composer and has fewer than 3 Love reactions themselves (i.e., is not a school-founder), their aesthetic position is nudged toward the school composer's aesthetic at a rate of 0.008 per axis per day.

Schools are how legendary composers reshape a settlement's entire aesthetic landscape. A composer with 5+ Love reactions acts as a constant aesthetic pull on every non-friend elf, slowly aligning the community toward their taste.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, aesthetic_school_drift_system, SCHOOL_THRESHOLD = 3, SCHOOL_DRIFT_RATE = 0.008

Revel Absence

During the gathering phase, elves with extreme personality values may choose not to attend:

These absences are logged as RevelAbsence events. Absent elves miss all performance effects (mood, satisfaction spikes, aesthetic drift, fandom formation) but also avoid negative outcomes from bad revels.

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system -- personality-driven absence events in Gathering phase.

Cooldown

After a revel ends, 400 ticks must pass before the next one can be scheduled. The first revel after settlement creation has its cooldown waived.

Source: src/sim/curator/dummy.rs, cooldown check; src/sim/world.rs, last_revel_tick initialization

Revel Archive

Every completed revel is archived with:

• Day number
• Zone name (detected from attendee positions)
• Attendee names
• Full performance records with per-elf reactions and scores
• Incidents (public critiques, fandom formations)

The archive computes an average score across all reactions and identifies the highlight (best-received performance by total reaction score sum).

Source: src/sim/components.rs, RevelArchive

Revel Types

Each revel has a type that determines its seasonal character. The type affects audience scoring through a seasonal appropriateness modifier -- holding the right revel in the right season boosts quality, while mismatched revels are penalized.

The curator selects from each season's natural options when scheduling. The seasonal appropriateness modifier is added to each audience member's score during the evaluation phase.

Source: crates/er-sim/src/sim/components.rs, RevelType::seasonal_options, RevelType::seasonal_appropriateness.

Seasonal Resonance

When a composition is performed, its seasonal property is checked against the current season. If they match, the audience responds more warmly. If they clash, the audience is slightly cooler.

These modifiers stack with the revel type's seasonal appropriateness. A Vernal composition performed at a Garden Walk in Spring receives both the +5 resonance bonus and the +5 GardenWalk-in-Spring appropriateness, for a total of +10 to every audience member's score. This is the core feedback loop that makes seasonal timing matter.

Conversely, a Hibernal composition at a summer Grand Performance gets -1 (mismatch) but the Grand Performance still provides +5 (it's in-season for its type). The combination is +4 -- not bad, just not as strong as a season-aligned performance.

Source: crates/er-sim/src/sim/art.rs, evaluate_audience -- seasonal resonance section.

Interactions

• Compositions -- Performed newest-first; quality dimensions drive audience scores
• Aesthetic Position -- Evaluation weights and audience drift
• Inspiration -- Love reactions boost dominant channel; high inspiration prevents creative block
• Satisfaction & Departure -- Great revels boost satisfaction, boring revels damage it
• Needs & Mood -- Reactions generate mood modifiers; sparse feasts cause mood penalties
• Relationships -- Fandom formation creates persistent social bonds
• Buildings -- Feast Hall required; compositions require Workshop
• Artistic Direction -- Direction influences which compositions are created before the revel
• Romance -- Shared transcendence (both Loved the same piece) is the strongest romance catalyst (+8 warmth)
• Arrivals -- Great revels (avg score >= 75) trigger the cultural event arrival channel (1-2 new elves)
• Personality -- Extreme personality values can cause revel absences
• Seasons & Weather -- Seasonal anchor events create revel windows; missing them applies mood penalties

Tips

• Schedule revels when your best composers have recently finished new works. Compositions are performed newest-first, so recent high-quality pieces get heard.
• Ensure adequate food before a revel. A "Sparse feast" mood penalty hits every attendee and can tank audience scores for the whole event.
• Revels are the primary mechanism for settlement-wide aesthetic convergence. Without regular revels, elves drift apart culturally and satisfaction drops.
• A revel with low average scores (< 30) actively harms the settlement through the -10 satisfaction spike. It is better to skip a revel than to hold one with only crude compositions.
• Watch for discontented elves at revels -- they evaluate with a -5 penalty, making bad reactions even more likely. Addressing satisfaction before a revel improves outcomes.
• The 400-tick cooldown means roughly one revel every 4 game days (with DAY_LENGTH=100). Winter's higher food requirement (15 vs 5) means you need well-stocked granaries to keep the revel cadence up.
• Fandom is a powerful social mechanic. An elf who Loves a composer's work becomes a fan, which affects future proximity-seeking and inspiration. Legendary composers can reshape the settlement's culture through school drift.

Cultural Movements

When a settlement's artistic life crosses certain thresholds, the simulation emits cultural milestone events: visible signals in the event feed that something larger than any single composition or elf has happened. These events mark when a composer's audience grows large enough to constitute a "school," when a genre is invented for the first time, or when a movement of like-minded elves crystallizes around shared loves.

This page covers three colony-level events:

• SchoolFormed — a composer crosses 3 cumulative Love reactions. Implemented.
• GenreInvented — a settlement's first anachronistic composition. Defined but not yet emitted.
• MovementCrystallized — coalescence of co-loving elves into a named movement. Defined but not yet emitted.

All three are EventPriority::Notable -- they appear in the event feed and revel recap but do not pause the game. Their reach extends well beyond individual elves: each marks a moment where the colony's culture has, in some small or large way, taken on a new shape.

Source: crates/er-sim/src/sim/events.rs, variants SchoolFormed, GenreInvented, MovementCrystallized; priority classification in CulturalEvent::priority.

SchoolFormed

A composer becomes a "school" the moment their cumulative count of Love reactions received as a composer crosses 3. From that moment forward, they are an aesthetic attractor: nearby non-friend elves slowly drift toward their taste direction (see School Drift).

Formation Conditions

The check is "was below threshold and is now at-or-above" -- so if a composer gets two Love reactions in one performance and they were already at 1, the event fires once for the threshold crossing, not twice.

Event Payload

Display

"{composer} has become a legendary school ({love_count} loves)"

⚠ Terminology warning: The display string says "legendary school," but the threshold is just 3 Love reactions -- a very low bar. This is not related to the Legendary prestige tier (which requires score 81+). A school composer can be a brand-new arrival with an Unknown prestige tier and a single hit performance. See the aesthetic position page for further discussion of this naming collision.

Player Significance

A SchoolFormed event tells the player: this composer's work is now influencing other elves' aesthetic positions. Concretely:

• Non-friend elves within 5 Manhattan tiles of the school composer drift toward the direction of the composer's aesthetic (relative to 0.5) by 0.008 per axis per day.
• The composer's prestige score gets the same fan and Love-reaction inputs it always did -- SchoolFormed is a separate, parallel signal, not a prestige driver.
• Schools tend to cluster: a school composer who keeps performing accumulates fans, the fans drift toward them aesthetically, and over time a coherent "movement" emerges around the school's chosen axis directions.

The event is the cue to start watching that part of the settlement for cultural identity formation.

Source: crates/er-sim/src/sim/systems/revel.rs -- emission at the was_below && asp.love_reactions_received >= SCHOOL_THRESHOLD branch around line 371; crates/er-sim/src/sim/systems/aesthetics.rs -- school drift behavior keyed to the same SCHOOL_THRESHOLD = 3 constant.

GenreInvented

A GenreInvented event would mark the moment a settlement composes its first anachronistic piece in a given genre family -- a cultural shock event celebrating that someone broke from the traditional and natural genres into something new (Jazz, Rock, Blues, Free Verse, and similar genre families described in the compositions reference).

⚠ Status: defined but not currently emitted. The event variant exists in CulturalEvent and would render in the event feed if produced, but no system in the codebase constructs it today. The 2026-03-16 art-data-files PRD explicitly defers it ("GenreInvented event deferred (noted as TODO)").

Intended Formation Conditions

Per the original game-mechanics specification:

"When an anachronistic piece is the settlement's first, emit GenreInvented."

The intended trigger is a per-settlement "first anachronistic genre" recognition: the system would need to track which genre families have been performed at least once in the settlement's history and fire the event the first time a composition lands in a previously-unseen anachronistic family.

Event Payload

Display (when implemented)

"{inventor} invented a new genre: {genre}!"

Why It's Worth Implementing

Anachronistic genres carry strong aesthetic signal -- they are the colony's break from tradition, the moment innovation overtakes inheritance. A first emission would be a real cultural milestone worth marking in feeds, and could plausibly factor into:

• Arrival mechanics (new wanderers attracted by cultural novelty -- see the reputation-based arrival design noted in earlier handoffs).
• Aspiration progress for innovation-leaning elves.
• A potential Founder tag for the inventing composer (analogous to colony founders).

See the follow-up beads for the open implementation issue.

Source: crates/er-sim/src/sim/events.rs -- variant declaration only. Original design: docs/plans/2026-03-14-game-mechanics-spec.md line ~540 and docs/brainstorms/2026-03-16-art-data-files.md line ~63.

MovementCrystallized

A MovementCrystallized event would mark the formation of a named cultural movement: a coherent group of elves bound together by shared aesthetic loves strong enough to constitute a recognizable artistic faction within the colony.

⚠ Status: defined but not currently emitted. The event variant exists in CulturalEvent and would render in the event feed if produced, but no system in the codebase constructs it today. The full crystallization logic (co-love subset detection, movement naming, member tracking, mood bonuses, revel score modifiers) is unimplemented.

Intended Formation Conditions

Per the original game-mechanics specification:

"After 3+ revels, scan for co-loving subsets: ≥3 elves who LOVED ≥3 same compositions. Named from founding compositions: 'The Defiant Shadow School.'"

The intended pipeline:

1. After every revel (once the colony has hosted at least 3 revels), scan the audience reaction history for co-loving subsets: groups of 3 or more elves who all gave Love reactions to the same 3 or more compositions.
2. When such a subset is detected and not already constituting an existing movement, name the movement after one or more of its founding compositions (e.g., "The Defiant Shadow School" from compositions like "Defiant Nocturne" and "Shadow Aubade").
3. Tag aligned elves with movement membership.
4. Emit MovementCrystallized { name, member_count }.

Event Payload

Display (when implemented)

"A cultural movement has formed: {name} ({member_count} members)"

Intended Downstream Effects

The same specification documents the gameplay effects movements would have if implemented:

• Mood bonus: aligned elves get "Part of a movement" +2 morale per 200 ticks.
• Revel scoring modifier: at revels, movement-aligned compositions get +3 from aligned elves and -2 from opposed elves.
• Patron interaction: the human director would be able to favorite or disfavor movements, shaping the colony's cultural arc.
• Curator awareness: the AI advisor would surface movement formation as a notable event for player attention.

None of the above is wired today. A MovementCrystallized payload appears in test fixtures ("The Defiant School", 3 members) but only to exercise the display formatter -- no production code path produces one.

See the follow-up beads for the open implementation issue.

Source: crates/er-sim/src/sim/events.rs -- variant declaration only. Original design: docs/plans/2026-03-14-game-mechanics-spec.md lines ~600-606 and docs/prd/elf-revel-prd.md lines ~118-122.

How These Events Interact

Even though only SchoolFormed fires today, all three events were designed as stages of cultural emergence at increasing scale:

A fully populated cultural-emergence pipeline would let a player watch their colony progress through these stages: a single compelling composer becomes a school, an experimental composition opens a genre, and eventually like-minded audience members coalesce into a recognizable movement around the new aesthetic. Today only the first step is operative.

Related Systems

• Revels -- where Love reactions are tallied and where SchoolFormed is emitted. The intended trigger sites for GenreInvented and MovementCrystallized would also live here or in adjacent revel-processing logic.
• Aesthetic Position — School Drift -- the simulation effect of becoming a school: nearby non-friends drift toward the school's aesthetic direction.
• Compositions -- genre families, including the anachronistic family relevant to GenreInvented.
• Prestige -- a parallel reputation system for composers; the Legendary prestige tier is unrelated to the "school" threshold despite the shared word in the SchoolFormed display string.
• Fandom -- per-elf fan tracking; fandom contributes to prestige independently of school formation.

Follow-up Work

Two of the three events on this page are unimplemented design intent. Open beads track the gap so future cultural depth work can pick them up:

• Revel-ris — implement GenreInvented emission: track first-seen genre families per settlement, fire on first anachronistic composition.
• Revel-awc — implement MovementCrystallized detection and effects (epic): co-love subset scanning, movement naming, membership tracking, mood bonuses, revel-scoring modifiers, patron/curator hooks.

These are noted as TODO in the original PRD and game-mechanics spec but were never scheduled. If you're considering implementing either, see docs/plans/2026-03-14-game-mechanics-spec.md (~lines 540-606) for the original spec.

Artistic Direction

Overview

Artistic Direction is the patron's primary tool for shaping the settlement's creative culture. It is a single setting with four modes that influences how the Curator makes decisions about role assignment, composition encouragement, and settlement priorities. The direction does not force any specific outcome -- it nudges the curator's judgment toward a particular aesthetic value.

You cycle through directions by pressing 'd' during normal gameplay (not in Look mode, where 'd' controls the camera).

How It Works

The Four Directions

The default starting direction is Balanced.

Pressing 'd' cycles through them in order:

Balanced --> Favor Mastery --> Favor Originality --> Favor Emotion --> Balanced

Source: src/sim/components.rs, ArtisticDirection; src/model.rs, cycle_artistic_direction

How the Curator Interprets Direction

The direction is communicated to the curator in two ways:

1. System prompt context: The LLM Curator receives the direction as part of its system prompt under "Patron's Direction," with explicit guidance:

   • Favor Mastery: "nurture your most skilled composers"
   • Favor Originality: "encourage avant-garde elves"
   • Favor Emotion: "protect your deeply-feeling artists from creative block"
   • Balanced: no specific instruction

2. Dummy Curator rule: When the direction is non-Balanced, the Dummy Curator ensures the best musician (highest music skill) is assigned the Composer role if no Composer has been assigned yet. This applies equally to all three non-Balanced directions.

Source: src/sim/curator/prompt.rs, build_system_prompt; src/sim/curator/dummy.rs, artistic direction handling

State Snapshot

The current direction is included in the settlement state snapshot sent to the curator each consultation cycle:

patron_direction: "FavorMastery" (or Balanced, FavorOriginality, FavorEmotion)

This means the LLM Curator sees the direction every time it evaluates the settlement and can adjust its strategy accordingly.

Source: src/sim/curator/state.rs, patron_direction field

Values & Formulas

Direction Does Not Affect Composition Scores Directly

Artistic direction does not modify the quality formulas. Mastery is always driven by music skill, originality by inspiration total, and emotional by mood. The direction works indirectly:

Interaction with Audience Evaluation

While direction does not change evaluation weights (those come from individual elf aesthetic positions), the compositions produced under each direction tend to score differently:

Patron Taste System

Artistic direction is one part of the broader Patron Taste system, which also includes:

The curator sees all of these when making decisions. Favorite compositions that are performed at revels trigger a special patron notification event.

Source: src/sim/components.rs, PatronTaste

TUI Display

The current direction is shown in the status bar with a short label:

Source: src/render_terminal.rs, direction label rendering

Interactions

• Compositions -- Direction biases which compositions get created through role assignment
• Revels -- Composition quality affects revel outcomes; direction shapes what is composed
• Roles -- Non-Balanced directions influence the curator to assign Composer roles
• The Curator -- Primary consumer of direction; both Dummy and LLM curators respond to it
• Aesthetic Position -- Audience evaluation weights are per-elf, not direction-dependent

Tips

• Balanced is the safe default. The curator already optimizes for settlement health. Only switch to a specific direction when you have a deliberate artistic vision.
• Favor Mastery is strongest in established settlements with high-skill composers. In a young settlement where everyone is skill 1-3, the mastery ceiling is too low for direction to matter much.
• Favor Originality works best when you can supply high inspiration. Build gardens, encourage wandering, and ensure varied experiences. Without inspiration sources, the direction is aspirational but ineffective.
• Favor Emotion is the defensive choice for settlements under stress. Emotional compositions with high mood tend to get broad audience approval, which boosts satisfaction and prevents departures.
• Direction changes take effect on the next curator consultation cycle. There is no delay or transition cost -- switch freely as conditions change.
• The LLM Curator interprets direction more creatively than the Dummy Curator. Where the Dummy Curator simply assigns the best musician as Composer, the LLM Curator might rearrange multiple roles, suggest garden placement, or write messages explaining its artistic reasoning.
• Watch the composition quality breakdowns to verify your direction is working. If you favor Mastery but compositions still have low mastery scores, the problem is likely insufficient music skill, not the direction setting.

Relationships

Elves form bonds with each other through proximity, shared activities, and aesthetic affinity. These relationships shape mood, satisfaction, and the social fabric of your settlement.

Overview

Every elf maintains a list of up to 20 relationships, each with a numeric strength value ranging from -100 to +100. As strength changes, relationships cross thresholds that reclassify them into one of three types: Acquaintance, Friend, or Rival.

Relationships form gradually. Two elves standing near each other and working gain small increments of strength. Over time, those small gains accumulate until a bond crystallizes. The social system runs every 50 ticks, evaluating proximity and adjusting strength for every pair of elves.

How It Works

Bond Types

Relationships are classified by their strength value:

New relationships always start as Acquaintance with strength 0.

Source: src/sim/components.rs, Relationships::adjust -- strength clamped to -100..100, Friend at 50+, Rival at -30 or below.

Formation Triggers

Relationships shift through proximity-based delta calculations that fire every 50 ticks in the social system:

Base delta (requires Manhattan distance <= 3 between the two elves):

Aesthetic affinity modifier (applied on top of base delta):

Aesthetic distance is computed as Euclidean distance in 4D aesthetic space (structure, tradition, emotion, social axes, each 0.0--1.0). The maximum possible distance is 2.0.

Source: crates/er-sim/src/sim/systems/social.rs, social_system -- proximity check at Manhattan <= 3, aesthetic distance thresholds at 0.3/0.7/0.9.

Social Axis Scaling

After computing the combined delta, it is scaled by each elf's Social axis (from their Aesthetic Position):

This means a Social elf gains +2 per working-proximity tick instead of +1, while a Personal elf only gains +0 (rounded down from 0.5). The scaling applies to both positive and negative deltas.

Source: crates/er-sim/src/sim/systems/social.rs, apply_social_axis_scale -- threshold checks at 0.7 and 0.3.

Bond Origins

Partner relationships remember how they formed. Three origins are currently tracked — Apprenticeship, SharedCrisis, and RivalryToLove — and they shift the partnership dissolution threshold up or down by bounded amounts. Four additional variants (Workshop, Revel, Critique, Rescue) are reserved for future triggers and carry no effect yet.

Origin history is a per-partnership property: only Partner relationships carry entries, and the history is cleared when a partnership dissolves. Acquaintances, Friends, and Rivals do not carry origin markers.

See Partnership Origins for the full system — triggers, the strength_min invariant that enables RivalryToLove detection, dissolution-threshold math, and the OriginSavedPartnership event that surfaces the mechanic in the feed.

Source: src/sim/components.rs, BondOrigin enum and Relationship::origin_history.

Relationship Affixes

Each relationship carries two boolean flags:

• Tested: Set to true when a friendship (strength >= 50) dips below 50 and then recovers back above 50. Also set during departure recovery -- if an elf nearly leaves but stays, friends who helped keep them get the Tested flag. A "Tested" bond is one that survived adversity.

• Fragile: Starts as true for all new relationships. Indicates the bond has not yet been reinforced. Set to true on relationships where an elf recovered from near-departure without any friend support.

Source: src/sim/components.rs, Relationship struct -- tested and fragile fields.

Values & Formulas

Strength Progression Example

Starting from 0, with both elves actively working within 3 tiles and having similar aesthetics (distance < 0.3):

• Base delta: +1 (both active)
• Aesthetic bonus: +1 (affinity)
• Total per 50-tick cycle: +2 per elf (before social scaling)
• Social elf (> 0.7): +4 per cycle
• Balanced elf: +2 per cycle
• Personal elf (< 0.3): +1 per cycle

At +2/cycle, a balanced elf pair reaches Friend status (+50) in approximately 25 cycles = 1,250 ticks (~12.5 days).

Decay

Every 500 ticks, any relationship where the two elves are not within Manhattan distance 3 of each other decays by -1 strength. This means neglected friendships slowly fade, though it takes 500+ ticks of separation for a friend (50+) to drop back to acquaintance.

Source: crates/er-sim/src/sim/systems/social.rs, social_system -- decay branch at tick.is_multiple_of(500).

Capacity and Pruning

Each elf can hold at most 20 relationships. When the list exceeds 20, it is sorted by absolute strength (strongest bonds first) and truncated. This means the weakest acquaintanceships are pruned to make room for stronger bonds.

Source: src/sim/components.rs, Relationships::prune -- MAX_RELATIONSHIPS = 20.

Rivalries

When a relationship's strength falls to -30 or below, it reclassifies to Rival, and a separate set of mechanics activates: arguments at close range, public critiques during revels, escalation past -60, and reconciliation back above -30. Those mechanics — including the RivalryArgument, PublicCritique, CompetitionEscalated, and RivalryReconciled events — live on the dedicated Rivalries page.

This page covers the underlying strength model that creates the Rival classification in the first place; Rivalries covers what happens once an elf is in one.

Interactions

Mood Effects

The social mood system runs every 10 ticks and applies mood modifiers based on nearby relationships:

Source: crates/er-sim/src/sim/systems/social.rs, social_mood_system -- distance checks at 3 (friends/rivals) and 5 (general nearby).

Company Need

The company need (0--100 scale) is influenced by the Social axis and proximity, running every 2 ticks:

For Personal elves, "company" is inverted -- low values are good (solitude achieved).

Source: crates/er-sim/src/sim/systems/needs.rs, company_system.

Satisfaction

Friend count feeds directly into the satisfaction formula:

Satisfaction = inspiration x 0.3 + morale x 0.2 + friends x 5.0 + aesthetic_fit x 20.0 + revel_score x 0.1 + prestige x 0.15 + spike

Each friend contributes +5.0 to satisfaction. An elf with 4 friends gets +20 satisfaction from relationships alone, which can be the difference between staying and departing.

Mentor Bonds

Apprenticeship is a separate component, not a normal relationship. While the bond is active it does not appear in the relationship list. At graduation, the master and student exchange a permanent +15 to +25 strength delta (scaled by bond strength), almost always pushing the pair into Friend territory.

The graduation also writes a permanent TrainedBy lineage marker on the student, visible in their detail panel.

If the master's tradition axis is > 0.6 and the student's final skill exceeds the master's, the master takes a -10 relationship penalty to the student instead of the +10 a more open master would receive -- a traditional master who feels surpassed registers it as a slight rather than a triumph.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_graduation_system -- bonus tiers at lines 322-324, surpass branch at line 348.

Departure Cascade

When an elf departs, remaining elves receive mood effects based on their relationship:

Close friends (strength >= 60) also enter a Mourning state for 200 ticks, gaining an additional -5 "Grieving" mood modifier. Mourning elves are drawn toward composing tributes.

Source: crates/er-sim/src/sim/systems/satisfaction.rs, satisfaction_system -- departure cascade section.

Tips

• Cluster housing near workshops to maximize proximity time. Elves who rest and work near each other accumulate relationship strength fastest (+2 base for co-resting).

• Watch the aesthetic positions of your elves. Pairs with similar aesthetics (distance < 0.3) gain bonds 50% faster. The Aesthetic Position panel shows each elf's 4D position.

• Social elves are relationship engines -- their x2 multiplier means they bond (and feud) at double speed. Assign them roles that keep them near others.

• Personal elves need space. They bond slowly (x0.5) and get stressed near crowds. Give them solitary tasks like distant gathering.

• Friendships prevent departure. Each friend adds +5 satisfaction. An elf with 0 friends and low inspiration is at serious risk. Check the Satisfaction page for threshold details.

• Don't ignore rival buildup. Two aesthetically opposed elves working together can drift to rivalry (-30) in about 15 cycles (750 ticks). Separate them before the -2 mood penalty kicks in.

• Pruning is automatic at 20 relationships. If an elf has many weak acquaintances, stronger bonds are preserved. You don't need to manage this.

• Friendships can become romance. Two friends who share emotional experiences accumulate romantic warmth. Friendship is a prerequisite for the SlowBurn and AestheticResonance warmth sources. Strong friends are more likely to fall in love -- and more likely to be devastated if it ends.

• Partnerships are protected. The adjust() method guards Partner relationships from being reclassified by the normal social system. Only romance progression creates Partners; only romance dissolution removes them.

• Master-student bonds compound friendships. A successful apprenticeship ends with both elves taking +15..+25 relationship -- often the largest single relationship event in the game. Pair masters and students whose aesthetic distance is small to also benefit from the post-graduation drift toward each other.

Rivalries

Not every bond is a friendship. Two elves who keep getting in each other's way — clashing aesthetics, repeated negative encounters, a public slight at the wrong revel — can drift into rivalry, and rivalry has its own social weather: arguments at close range, hostile critiques during performances, escalation into entrenched feud, and (sometimes) reconciliation back to acquaintance.

This page is the canonical home for the rivalry mechanic and the four cultural events it generates: RivalryArgument, PublicCritique, CompetitionEscalated, and RivalryReconciled. For the underlying relationship strength model — how any bond, including rivalry, is created and adjusted — see Relationships.

Overview

A relationship becomes a rivalry when its strength falls to -30 or below. Below that threshold, the bond is classified as RelationType::Rival, which unlocks four related behaviors:

1. Mood penalties when the rivals are within 3 tiles of each other (handled by the social mood system — see Relationships → Mood Effects).
2. Arguments triggered by the conflict system on rival proximity.
3. Public critiques triggered when a rival in a revel audience Dislikes the composer's work.
4. Escalation past -60 and reconciliation back above -30, each surfacing its own event.

Rivalries are not just costs — they fuel the rivalry inspiration channel, which can push elves toward composition properties like Manifesto, Obsessive, and Virtuosic. A well-tuned rivalry produces art the elves wouldn't otherwise make.

Source: crates/er-sim/src/sim/components.rs, Relationships::adjust — Rival classification at strength -128..=-30.

How Rivalries Form

Rivalries form through the same proximity-and-aesthetic-affinity machinery as friendships, just running in the negative direction. Two elves with strongly opposed aesthetics (4D distance > 0.9) working near each other receive a -2 per cycle penalty to their bond instead of a positive delta. After enough cycles of negative drift, the strength crosses -30 and the relationship reclassifies to Rival.

Other paths into rivalry:

• Argument deltas: each rivalry argument applies an additional -2 to both sides of the bond, deepening it.
• Composition disliked by an enemy: if a relationship was already negative, a Dislike reaction at a revel doesn't change the strength directly, but the social cost of the public critique makes future positive drift harder (the composer's mood drop reduces their willingness to be near the critic).

See Relationships → Formation Triggers for the full delta tables. The same machinery, just with negative aesthetic affinity producing rivalry instead of friendship.

Rival threshold: relationship strength <= -30 (and not a Partner — partnerships are protected from reclassification).

Source: crates/er-sim/src/sim/components.rs, Relationships::adjust — strength clamped to -100..100, kind reclassified unless Partner.

The Conflict System

Once a relationship is classified as Rival, it becomes visible to the conflict system, which runs every 10 ticks and scans all elf pairs for:

1. Manhattan distance <= 3 (rivals must be near each other for anything to happen).
2. Both sides classified as Rival (the rivalry must be mutual — strength check on at least one side).
3. Per-pair cooldown elapsed (no two arguments between the same pair within DAY_LENGTH × 3 ticks — three game days).

When all three conditions are met, the system rolls a personality-modulated argument chance:

Argument chance = 10% + 15% × max(impulsivity_a, impulsivity_b)

Impulsivity is a personality axis on each elf, mapped through a sigmoid into a 0–1 multiplier. Two patient elves argue at base ~10% per check; a pair where one elf is highly impulsive argues at ~25% per check. Since the system runs every 10 ticks, effective per-tick rates are ~1–2.5%.

Source: crates/er-sim/src/sim/systems/social.rs, conflict_system — proximity at Manhattan <= 3, cooldown at day_length * 3, chance formula at 0.10 + 0.15 * impulsivity.max().

Argument Events (RivalryArgument)

When a check succeeds, the system emits a RivalryArgument event with both elf names and a topic derived from the pair's greatest aesthetic-axis disagreement:

If aesthetic data is missing for either elf, the topic falls back to "artistic direction".

Argument Effects

Both elves take immediate consequences:

Pride modulation matters. A high-pride elf takes a deeper mood hit (down to -5) for a longer duration (up to 100 ticks). A humble elf brushes off the same insult with -2 mood for 50 ticks. The formula is mood = -2 - (pride × 3) and duration = 50 + (pride × 50).

Personality Crisis Triggers

Arguments can also kick a fragile elf into a personality crisis, surfaced by the PersonalityCrisis event:

• EgoWound: pride > 0.85 AND morale < 40 AND no existing wound → +150 ticks of "Wounded pride" (-8 mood) and an EgoWound component.
• LongPatienceBroken: patience > 0.85, 10% chance per qualifying argument → +50 ticks of "Patience shattered" (-5 mood) and a LongPatienceBroken component.

Argument priority in the event feed: Notable (worth reading, not pause-worthy).

Source: crates/er-sim/src/sim/systems/social.rs, conflict_system and argument_topic — mood/inspiration/strength deltas; pride scaling at lines 525–540; crisis triggers at lines 596–620.

Source: crates/er-sim/src/sim/events.rs, EventPriority — RivalryArgument is Notable.

Public Critique (PublicCritique)

Rivalry follows elves into the revel hall. When a composer performs at a revel, every audience member rolls an aesthetic reaction (Love / Enjoy / Indifferent / Dislike). If a rival of the composer rolls Dislike, the system emits a PublicCritique event:

This stacks on the base Dislike penalty (-3 mood for 50 ticks). A composer publicly critiqued by a rival receives a total of -7 mood from one event.

PublicCritiques are also recorded as PerformanceIncident::PublicCritique in the revel archive, preserving the critic and target names for later inspection.

If the critique pushes the revel into majority-negative reception, the composer additionally takes the -30 satisfaction "ego crisis" spike. See Revels → Ego Crisis for that interaction.

Priority: Notable.

Source: crates/er-sim/src/sim/systems/revel.rs, revel_tick_system lines 294–334 — rival check on Dislike reactions, mood and inspiration deltas.

Escalation (CompetitionEscalated)

When an argument's -2 strength delta pushes the bond past -60, the system emits a CompetitionEscalated event. This marks a deeply entrenched rivalry — the pair has argued (or drifted) enough times that hostility is now a defining social feature of their relationship.

Escalation threshold: relationship strength crosses from above -60 to <= -60.

The event itself fires only on the crossing — re-escalating after recovery requires the bond to first recover above -60 and then fall again. There is no separate "deeply escalated" state machine; the threshold is purely an event-emission gate. Escalated rivals continue to use the same conflict-system mechanics, just from a deeper hole that takes longer to climb out of.

Priority: Notable.

Source: crates/er-sim/src/sim/systems/social.rs, conflict_system lines 646–652 — escalation check on strength crossing from > -60 to <= -60.

Reconciliation (RivalryReconciled)

A rivalry can heal. When a Rival relationship's strength rises back above -30, the bond reclassifies to Acquaintance and the system emits RivalryReconciled.

Reconciliation threshold: relationship strength crosses from <= -30 to > -30.

How does a rivalry recover? Through the normal social system's positive proximity deltas: two former rivals working closely together with aligned aesthetics slowly heal the rift. Each cycle they get along can restore +1 to +2 strength; each argument re-applies -2.

This is why the 3-day per-pair argument cooldown matters for reconciliation: it gives the social system time to apply enough positive deltas between arguments. A pair that argues every 3 days but gets along between sessions can still trend toward reconciliation if the positive deltas outweigh the -2 per argument.

Reconciliation does not restore lost mood, lost inspiration, or the strength_min watermark on the relationship — that watermark is permanent (a relationship can be marked "once a rivalry" forever, which feeds the RivalryToLove partnership origin if the bond eventually flips all the way to Partner).

Priority: Notable.

Source: crates/er-sim/src/sim/systems/social.rs, conflict_system lines 654–660 — reconciliation check; crates/er-sim/src/sim/components.rs Relationships::adjust for strength_min semantics.

When Rivals Depart

When a rival departs, remaining elves who had a Rival bond with them receive a +3 mood "Rival departed" modifier for 100 ticks. See Satisfaction → Departure Cascade for the full mood effect table including friend and acquaintance reactions.

Tips

• Don't ignore rival buildup. Two aesthetically opposed elves working together can drift to rivalry (-30) in roughly 15 social cycles (~750 ticks). Once they cross -30, the conflict system starts firing arguments, and each argument deepens the rivalry by another -2 while costing both elves mood. Separate them early if you don't want a feud, or commit to it if you do.

• Pride is a multiplier on every argument. A high-pride elf takes -5 mood for 100 ticks per argument; a humble elf takes -2 for 50. If two proud elves become rivals, each argument is genuinely destabilizing. Watch for the EgoWound event — it means a pride > 0.85 elf has been pushed past their morale threshold.

• Rivalry is a creative engine. Each argument grants both elves +3 rivalry inspiration, and public critiques add +2 for the critic. The Manifesto, Obsessive, and Virtuosic composition properties all require rivalry > 30. A composer with one well-tuned rival often produces more (and more pointed) art than one with none.

• Public critiques compound disastrously. Composer mood, fan loss, ego crisis, and a permanent record in the revel archive all stack. A composer who is publicly criticized at a revel that also tilts majority-negative takes -7 mood plus -30 satisfaction in one tick. Schedule revels with the audience composition in mind — a rival in the audience is a coin flip, not a guarantee.

• Reconciliation is slow but real. Two rivals working together with aligned aesthetics can heal back to Acquaintance over time. The 3-day per-pair argument cooldown is the window where reconciliation is possible. If you want to repair a rivalry, give the pair shared work in close proximity and avoid revel co-attendance until the bond crosses -30.

• The strength_min watermark is permanent. A reconciled rivalry leaves a trace: the relationship remembers it was once at -30 or worse. This enables the RivalryToLove partnership origin — a former rival who became a partner has a more resilient bond than one who was always a friend. Reconciled rivals are not "back to neutral"; they have history.

• Personality crises are rare but durable. EgoWound (150 ticks) and LongPatienceBroken (50 ticks) both apply mood pushes that last long enough to risk a cascade into the satisfaction departure window. If you see PersonalityCrisis in the feed, the affected elf is briefly fragile.

Related Pages

• Relationships — the underlying strength model, formation triggers, and bond classifications.
• Revels — performance reactions, including how a rival in the audience produces a PublicCritique.
• Inspiration — the rivalry channel and which composition properties it unlocks.
• Compositions — Manifesto / Obsessive / Virtuosic properties and their rivalry inspiration requirements.
• Partnership Origins — how a reconciled rivalry that becomes a partnership unlocks the RivalryToLove origin.
• Satisfaction & Departure — rivalry's contribution to the mood/satisfaction loop and the departure cascade.

Apprenticeship

A skilled elf and a novice working side by side at the same craft can form a master-student bond. Over time the apprentice's hands grow surer, their aesthetic drifts toward the master's, and their compositions carry the master's name as a stylistic signature. When the apprentice reaches mastery, the bond resolves -- sometimes in pride, sometimes in resentment.

Overview

Apprenticeship is a one-to-one bond between two elves working the same skill. There is no manual assignment: the simulation matches eligible pairs every 50 ticks based on skill, proximity, and current task. Bonds form silently, deliver their effects continuously while the pair stays close, and resolve at graduation when the student reaches skill 10.

A master can hold at most one active apprentice. A student can have at most one master. Bonds dissolve cleanly if either elf departs the colony, and lapse if 500 ticks pass without proximity.

Three tick systems run the lifecycle, all every 50 ticks:

• Formation -- match eligible pairs, dissolve stale and dead-master bonds
• Effects -- award proximity XP, refresh master mood, count bond strength
• Graduation -- detect skill-10 students, sever the bond, apply social effects

A separate aesthetic drift system runs once per day to slowly pull the apprentice's aesthetic position toward the master's.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs; crates/er-sim/src/sim/systems/aesthetics.rs, apprenticeship_aesthetic_drift_system.

How It Works

Formation Eligibility

Every 50 ticks the formation system snapshots all elves and looks for unbonded pairs that match all of:

Only Compose, Build, and Gather tasks count as skill exercises. A master idling does not exercise their skill, and so cannot form a bond that tick. A pair must be actively working the same craft, near each other for the match to fire.

The matcher takes the first eligible student per master (sequential pass; no scoring). One student per master per pass.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_formation_system -- task_to_skill, eligibility filters at lines 137-148.

Bond Strength

bond_strength (0--255) increments by +1 every 50 ticks the pair stays within 5 tiles. It is the count of proximity ticks the bond has accumulated. It never decreases except by dissolution. Three thresholds matter at graduation:

Reaching 200 takes 200 proximity ticks = 10,000 ticks of continuous near-master work. A bond can persist longer than that without graduating if the student's skill is still climbing.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_effects_system; graduation tiers at lines 322-324.

Effects (Per 50-tick Tick)

While the pair is within 5 tiles:

The XP bonus is small but constant. Over a full apprenticeship a student typically gains hundreds of bonus XP from proximity alone, accelerating their climb to skill 10.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_effects_system -- proximity check at line 217, mutations at lines 224-243.

Aesthetic Drift

Once per day, every apprentice within 5 tiles of their master drifts 0.02 along each aesthetic axis (structure, tradition, emotion, social) toward the master's value. This is 2x the friend drift rate. The pull is signed -- it always moves toward the master, clamped to [0.0, 1.0].

Apprentices learn what their master values, not just what their master does. An apprentice studying under a deeply traditional master will gradually become more traditional themselves, even if they entered the bond as a radical.

This drift persists in the student's aesthetic position after graduation -- the bond ends, but the imprint remains.

Source: crates/er-sim/src/sim/systems/aesthetics.rs, apprenticeship_aesthetic_drift_system -- APPRENTICE_DRIFT_RATE = 0.02, proximity check at 5 tiles.

Graduation

When a student's skill in the bonded craft reaches 10, the next graduation pass resolves the bond:

1. Remove Apprenticeship from student and HasApprentice from master.
2. Attach a permanent TrainedBy { master_name, skill } component to the student.
3. Apply mutual relationship bonus (+15, +20, or +25 depending on bond strength).
4. Push "Graduated" mood +8 on the student for 300 ticks.
5. Emit a Graduation event (notable priority -- shows in event feed).

The TrainedBy component is permanent and visible in the elf detail panel as Trained by {master} ({skill}). It marks lineage even after the master has departed.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_graduation_system -- skill 10 gate at line 279, bonus tiers at lines 322-324.

The Surpass Branch

If the graduating student's skill is strictly greater than the master's at graduation time, a StudentSurpassedMaster event fires. The master's reaction depends on their tradition axis:

A traditional master expects deference and grades the apprentice's success as a slight against the lineage. An open master treats it as the system working as intended -- the student became greater than the teacher, which is the point.

This branch fires once per (student, master) pair for the lifetime of the colony, tracked by the surpass_acknowledged set. A student who surpasses a master, leaves the colony, and returns will not re-trigger the event.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_graduation_system -- surpass check at line 348, tradition threshold 0.6 at line 352.

Maintenance and Dissolution

The formation system also handles cleanup every 50 ticks:

Stale bonds dissolve quietly (no event). A master and student who drift apart -- because tasks reassign or one moves to a distant zone -- will lose the bond after about 10 game days of separation.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_formation_system -- staleness at line 104; cleanup_apprenticeship_on_departure.

Interactions

Composition Style

Every composition by an active apprentice gets the InStyleOf({master_name}) composition property. It is cap-exempt (does not count toward the 2-property limit), inserted alongside the seasonal property.

A composition titled Wistful Sonata of Fellowship written by an apprentice of a master named Calenor will display the property as Style: Calenor. It marks the work as belonging to a lineage. The property is attached only while the bond is active -- post-graduation compositions do not carry it (the lineage lives in the TrainedBy component instead).

Source: crates/er-sim/src/sim/systems/compose.rs, lines 189-192; crates/er-sim/src/sim/components.rs, CompositionProperty::InStyleOf.

Mentor Relationships

The master-student bond does not show up in the relationship list while the apprenticeship is active -- it is a separate component. Only at graduation do the two elves exchange a permanent +15..+25 relationship strength bonus, which generally pushes them firmly into Friend territory and often beyond.

The surpass branch can flip this: a traditional master who feels surpassed loses 10 relationship to the student (net result: typically still positive, but smaller). An open master gains an extra +10 (deep, lasting friendship).

Lifecycle and Departure

When a master departs, their student loses the bond and takes a -8 mood penalty. The aesthetic drift the student has accumulated remains. The TrainedBy component, if already set by an earlier graduation under a different master, is preserved -- a student can only have one TrainedBy at a time, but lineage records are not retroactively erased.

Elder masters who depart through fulfilled departure leave behind students who must finish learning on their own. The master's name lives on as master_name in the (now-orphaned) lineage record.

Aesthetic Position Convergence

Pairs that maintain the bond for a full season can drift up to 0.02 x days in each axis -- enough to noticeably shift an apprentice's aesthetic identity. Two elves who started 0.4 apart in tradition can converge to within 0.2 over a long apprenticeship.

This is one of the few systems in the game that changes an elf's aesthetic position after personality maturation. Most aesthetic shifts come from environmental drift; apprenticeship is targeted, directional drift.

Tips

• Pair masters and apprentices in the same workshop. The matching system requires both elves to be actively performing the same task within 5 tiles. Co-locating composer huts, builder yards, and gathering paths gives the matcher more candidate pairs to work with.

• Aesthetic alignment is not required for formation -- only skill and proximity. A radical apprentice can bond with a traditional master, and the drift system will pull them toward the master's aesthetic over time. This can be used deliberately to shift a colony's aesthetic balance: appoint elders with the values you want to preserve, and apprentices will inherit them.

• Watch for the surpass event. If your master's tradition is high (> 0.6), a strong apprentice will eventually surpass them and trigger resentment. The master's +5 Rivalry inspiration can fuel new compositions (Manifesto, Obsessive, Virtuosic require Rivalry > 30) -- but the -10 relationship hit can also push them toward departure if they were already strained.

• Long apprenticeships are not punished. A bond at strength 200+ gives a +25 relationship bonus at graduation, vs +15 for a quick match. There is no maximum duration; bonds can run thousands of ticks. The only cost is opportunity -- a low-skill student locked into one master cannot learn from anyone else.

• InStyleOf is a lineage marker, not a quality bonus. The property does not affect mastery, originality, or emotional scores -- it is purely informational. A composition's quality still depends on the composer's own skill, inspiration, and mood. The marker matters for cultural history (which master shaped which compositions), not for revel performance.

• Don't over-cluster apprenticeships in one craft. A master can only hold one apprentice. If you have three skill-9 builders and only one skill-2 builder, two of your masters will sit unbonded. Spread skill levels across crafts to maximize the number of active mentorships.

• Bonds dissolve quietly. If a master is reassigned to a task that doesn't exercise the bonded skill, the pair will stop accumulating proximity ticks and the bond will lapse after 500 ticks of inactivity. There is no warning -- the apprentice simply loses the bond and will be re-matched (potentially to a different master) on the next formation pass.

Romance

Elves don't choose who to love. Attraction emerges from shared emotional experiences -- grief, transcendence, comfort in dark moments. Romance in your settlement is asymmetric, gradual, and deeply shaped by personality.

Overview

Each elf can hold up to 3 simultaneous attractions. Attractions accumulate warmth over time through shared experiences. When warmth crosses key thresholds, the relationship progresses through stages: attraction, courtship, and partnership. Partnerships can dissolve under aesthetic drift or status asymmetry, leaving permanent personality scars.

Romance runs on three tick systems:

• Warmth accumulation (every 50 ticks)
• Progression (every 50 ticks)
• Dissolution (every 100 ticks)

Source: crates/er-sim/src/sim/systems/romance.rs -- romance_warmth_system, romance_progression_system, romance_dissolution_system.

How It Works

Warmth Sources

Warmth grows through shared emotional moments, not compatibility scores. Two elves must experience something together for attraction to build.

Catalyst events are special -- they don't just add warmth, they unlock the courtship transition. A spark without a catalyst stays as unacted attraction.

Source: crates/er-sim/src/sim/systems/romance.rs, romance_warmth_system -- catalyst flag set on SharedTranscendence, SharedGrief, ComfortInDarkness.

Personality Multipliers

All warmth gains are scaled by the attracted elf's personality:

A cautious, proud elf accumulates warmth at 0.6 x 0.8 = 48% of the base rate. A bold elf with low pride accumulates at 130%. Love is not equally distributed.

Source: crates/er-sim/src/sim/systems/romance.rs, romance_warmth_system -- Personality::sigmoid_effect applied to boldness/pride thresholds.

Progression Stages

Courtship requires both elves to have warmth >= 60 for each other (mutual) and a recent catalyst event (within 100 ticks of the spark). One-sided warmth above 60 doesn't trigger courtship -- it starts the unrequited clock.

Partnership is the final stage. Only romance_progression_system creates partnerships; only romance_dissolution_system removes them. The Relationships::adjust method guards Partners from being reclassified by the normal social system.

Source: crates/er-sim/src/sim/systems/romance.rs, romance_progression_system -- COURTSHIP_THRESHOLD = 60.0, PARTNERSHIP_THRESHOLD = 85.0.

Unrequited Love

When one elf's warmth crosses 60 (spark) but the target's warmth stays below 30 for 200 ticks, the attraction resolves as unrequited:

• An Unrequited personality scar is applied
• Mood penalty: -5 for 150 ticks
• The attraction is removed

This is one of the few ways scars form outside of partnership dissolution. A cautious elf who builds warmth slowly may carry unrequited scars from multiple failed attractions over a long game.

Source: crates/er-sim/src/sim/systems/romance.rs, romance_progression_system -- unrequited branch at 200 ticks after spark_tick.

Dissolution

Partnerships accumulate dissolution pressure over time. When pressure reaches 100.0, the partnership ends.

Pressure sources (per 100-tick cycle):

Patience modifier: all pressure is scaled by (1.5 - patience). A patient elf (patience = 1.0) scales pressure by 0.5x. An impulsive elf (patience = 0.0) scales by 1.5x.

Proximity repair: when partners are within 3 tiles, pressure decreases by up to -2.0 per cycle (minimum delta: -5.0). Keeping partners near each other physically slows dissolution.

Dissolution events:

Betrayal is instant -- it doesn't wait for pressure to reach 100. If one partner begins courting a third elf, the partnership dissolves immediately.

Source: crates/er-sim/src/sim/systems/romance.rs, romance_dissolution_system -- pressure cap at 100.0, patience modifier at 1.5 - patience.

Partnerships carry origin markers — records of how the bond grew (apprenticeship, shared grief, rivalry-turned-love) that shift the dissolution threshold above or below baseline 100. A partnership with Apprenticeship and SharedCrisis origins dissolves at pressure 135, not 100; a RivalryToLove partnership dissolves at 90. When origin history saves a partnership from a pressure cycle that would have ended it at baseline, an OriginSavedPartnership event fires in the feed.

Values & Formulas

Warmth Timeline Example

Two bold friends (boldness > 0.7) who share a revel transcendence moment:

1. SharedTranscendence: +8.0 x 1.3 = +10.4 (catalyst set)
2. SlowBurn each 50-tick cycle: +1.0 x 1.3 = +1.3
3. At cycle 39 (~1,950 ticks): warmth crosses 60.0 -- spark
4. If mutual and catalyst within 100 ticks: courtship begins
5. Continued SlowBurn + AestheticResonance: ~2.0-3.3 per cycle
6. At ~cycle 58 (~2,900 ticks): warmth crosses 85.0 -- partnership

A cautious pair (x0.6) would take roughly twice as long to reach the same thresholds.

Dissolution Timeline Example

Partners with aesthetics drifting apart (distance = 0.9):

• Pressure per cycle: (0.9 - 0.8) x 5.0 = 0.5
• Patient elf (patience = 0.8): 0.5 x 0.7 = 0.35 per 100 ticks
• Impulsive elf (patience = 0.2): 0.5 x 1.3 = 0.65 per 100 ticks
• If not near each other: ~150-290 cycles (15,000-29,000 ticks) to dissolve
• If near each other: repair of -2.0 per cycle far exceeds pressure -- stable

Aesthetic drift alone dissolves partnerships slowly. Add a prestige gap and the pressure compounds rapidly.

Interactions

Mood Effects

Source: crates/er-sim/src/sim/systems/social.rs, social_mood_system -- "Near beloved" modifier.

Satisfaction

Romance contributes directly to satisfaction:

Source: crates/er-sim/src/sim/systems/satisfaction.rs, satisfaction_system -- romance_bonus section.

Composition Properties

Romance states unlock composition properties when an elf composes:

See Scars — Composition Properties for the full picture.

Source: crates/er-sim/src/sim/systems/compose.rs, compose_system -- partner contentment and scar-driven properties.

Tips

• Shared transcendence is the strongest catalyst. Schedule revels with compositions that polarize the audience -- elves who both Love the same piece get +8 warmth and a catalyst flag. This is the fastest path to courtship.

• Grief bonds are powerful. When an elf departs, watch who mourns together. Shared grief (+6, catalyst) can spark romances between elves who barely knew each other before the loss.

• Keep partners near each other. Proximity repair (-2.0/cycle) counteracts mild aesthetic drift. Partners who work in the same zone are more stable than those assigned to opposite ends of the settlement.

• Watch for unrequited spirals. A cautious elf (x0.6 warmth) paired with a bold elf (x1.3 warmth) can create asymmetric attraction -- the bold elf's warmth climbs past 60 while the cautious elf's is still at 35. The 200-tick unrequited clock starts for the bold elf.

• Betrayal is instant and one-sided. If a partnered elf begins courting someone new, the existing partnership dissolves immediately. Only the betrayed elf gets the Betrayal scar. The betrayer walks away clean.

• Scars accumulate. An elf who has been through two heartbreaks carries -3.0 satisfaction permanently. Three unrequited loves add another -4.5. Multiple scars can push an elf toward departure even if everything else is going well.

Partnership Origins

Partnerships remember how they began. When two elves become Partners, the stages they passed through on the way — a teaching bond, a shared grief, a rivalry that softened — are stamped onto the partnership as origin markers. Markers are identity, not numerical bonuses. They don't inflate strength. They make partnerships that grew through specific hardships harder to break, and they tell a visible story about what the bond is made of.

Overview

Every Partner relationship carries an origin_history: an append-only list of (origin, day) entries recorded in the order they happened. Three triggers currently write origins:

• Apprenticeship — the pair graduated a master-student bond before becoming Partners
• SharedCrisis — the pair comforted each other through grief or darkness
• RivalryToLove — the pair were once rivals (strength reached -30 or below) before becoming Partners

Non-Partner relationships do not carry origin history. When a partnership dissolves, origin_history is cleared — if the elves later re-partner, their history starts fresh.

Origins have one gameplay effect: they shift the dissolution pressure threshold. Baseline partnerships dissolve at pressure 100; partnerships with origins dissolve at 100 + delta, where the delta is computed from history with per-variant caps. When an origin-strengthened partnership survives a pressure cycle it would have dissolved under at baseline, a CulturalEvent::OriginSavedPartnership fires — the moment the mechanic becomes visible to you.

Source: crates/er-sim/src/sim/components.rs, Relationship::origin_history; crates/er-sim/src/sim/systems/origin_balance.rs.

How It Works

Origin Triggers

Each origin is written at the moment of a specific semantic event. The write is deduplicated per event, not per system firing — a single underlying event produces at most one entry even if the tick system it rides on runs many times.

Source: crates/er-sim/src/sim/systems/apprenticeship.rs, apprenticeship_graduation_system; crates/er-sim/src/sim/systems/romance.rs, SharedCrisis write in romance_warmth_system and RivalryToLove detector in romance_progression_system.

The strength_min Invariant

To detect RivalryToLove after the fact, every relationship tracks strength_min — the lowest strength it has ever held. Every strength change updates it via strength_min = strength_min.min(new_strength). The field is monotonic (only decreases) until dissolution, when it resets to the current strength.

Rivalry sits at strength -30 or below. If a pair's strength_min ever dipped to -30 or lower, then later climbed back up through reconciliation and courtship into partnership, the evidence of the old rivalry is still there when the partnership forms. Without strength_min there would be no way to know — the current strength at formation time is always positive.

Hard-set strength assignments (partnership formation at +80, betrayal at -50) also update strength_min inline, so dramatic swings are not missed.

Source: crates/er-sim/src/sim/components.rs, Relationship::strength_min and Relationship::adjust_strength.

SharedCrisis Deduplication

A bereaved elf enters a Mourning state for 150--300 ticks. During that time, romance_warmth_system runs every 50 ticks and may fire a ComfortInDarkness or SharedGrief catalyst between the mourner and a nearby friend — potentially 3--6 times over one bereavement.

Without deduplication, a single shared death would stamp 3--6 SharedCrisis entries onto the partnership's history, undermining the per-variant cap that prevents runaway resilience. Instead, the trigger keys on the (pair, departed_friend) tuple during the active Mourning episode: exactly one entry is written per mourning episode, regardless of how many catalyst firings occur within it. A second, later bereavement — a different departed friend — produces a second entry; repeated firings during the same bereavement do not.

This keeps the origin_history count of SharedCrisis entries equal to the number of distinct grief events the pair lived through together, not the number of times the sim ticked over during them.

Source: crates/er-sim/src/sim/systems/romance.rs, SharedCrisis dedup table keyed by mourning-instance ID.

Pending Origins

Some origins are determined before a partnership exists. When a strong apprenticeship (bond_strength >= 60) graduates without the pair being Partners yet, the trigger stores a pending entry in a resource-side table keyed by the pair's stable ID hash. If the pair later becomes Partners within 30 in-game days, the pending entry drains into the new partnership's origin_history with the formation tick. If either elf departs or dies before then, the pending entry is cleared.

Pending entries are not saved — they represent in-flight causal state, not persistent history. A save/load during the 30-day window will lose the pending entry. This is accepted: the window is short, and the mechanic does not rely on save durability.

Source: crates/er-sim/src/sim/pending_origins.rs, PendingOriginWrites resource.

Dissolution Resistance

Partnership dissolution pressure accumulates per the rules in Romance. The dissolution threshold is 100 + origin_threshold_delta, computed from origin_history:

Stacking: Positive deltas sum, then clamp to a total of +50. Negative deltas (RivalryToLove) are added after the positive cap — so a rivalry bond always registers as fragility, even in a partnership stacked with Apprenticeship and SharedCrisis. Empty history gives delta 0 and the baseline threshold 100.

Worked examples:

• [Apprenticeship] → +20 → threshold 120
• [Apprenticeship, SharedCrisis] → +35 → threshold 135
• [SharedCrisis × 5] → +45 (cap of 3 holds) → threshold 145
• [Apprenticeship, SharedCrisis × 3] → +65 → cap at +50 → threshold 150
• [Apprenticeship, SharedCrisis × 3, RivalryToLove] → +50 capped, then -10 → threshold 140
• [RivalryToLove] alone → -10 → threshold 90 (dissolves easier than baseline)

Source: crates/er-sim/src/sim/systems/origin_balance.rs, origin_threshold_delta.

The Save Event

CulturalEvent::OriginSavedPartnership fires when romance_dissolution_system finds a partnership where:

1. Accumulated pressure would cross baseline 100 (dissolution would have fired without origins), AND
2. Pressure is still below the origin-adjusted threshold (dissolution does not fire with origins), AND
3. The prior pressure was under 100 (this is the transition tick, not every tick afterward)

It fires once per such crossing and reads in the event feed as a brief line naming both elves and the origins that saved them: "<A> and <B>'s partnership endured — an apprenticeship once shared, a crisis weathered together". The phrasing varies per origin: SharedCrisis reads as "a crisis weathered together", RivalryToLove as "a rivalry turned to love", Apprenticeship as "an apprenticeship once shared".

This is the mechanic made visible. A silent dissolution-resistance modifier would be invisible to the player; the event surfaces the moment the bond's history actually kept it alive.

Source: crates/er-sim/src/sim/systems/romance.rs, romance_dissolution_system save-detection logic; crates/er-sim/src/sim/events.rs, CulturalEvent::OriginSavedPartnership::description.

Reading Origin History on an Elf

The Relationships screen renders each Partner's origin history as a single extra line below the partner row:

Partner Kellen                                [#####.....] 80
    grew from apprenticeship (day 14), then shared crisis (day 47)

Format rules:

• The first entry uses grew from; subsequent entries use then, comma-separated
• Variants render as lowercase words: Apprenticeship → "apprenticeship", SharedCrisis → "shared crisis", RivalryToLove → "rivalry to love"
• Day number = tick / 100 using the canonical DAY_LENGTH constant
• Empty history → no line rendered at all (no placeholder text)
• Non-Partner relationships → no line

There is no truncation: a partnership with a dense history renders as one long line that may extend beyond the panel width. Dense histories are rare in practice; this is accepted until data shows otherwise.

Source: crates/er-sim/src/render_terminal.rs, format_origin_history_line.

Values & Formulas

Threshold Timeline Example

Two elves who graduated a strong apprenticeship together (Apprenticeship origin written at graduation, +20) and later lost a close friend together during a Mourning episode (one SharedCrisis entry written at the first catalyst firing, +15):

• Empty partnership threshold: 100
• After graduation (Apprenticeship origin): 120
• After shared bereavement (+ SharedCrisis origin): 135

If aesthetic drift later pushes dissolution pressure to 115, a baseline partnership dissolves. This one survives — pressure < 135 — and a CulturalEvent::OriginSavedPartnership fires on the tick pressure crosses 100. If pressure continues climbing to 140, the partnership eventually dissolves anyway, but it lasted meaningfully longer than an origin-less partnership under identical conditions.

Dissolution Clearing

All three partnership exit paths clear origin_history and reset strength_min on the surviving-side relationship record:

1. Graceful dissolution from accumulated pressure (romance_dissolution_system)
2. Satisfaction departure — partner leaves the settlement due to low satisfaction
3. Farewell departure — partner dies of old age

After clearing, a surviving elf who later re-partners starts with empty history and a fresh strength_min. The new partnership's resilience is shaped only by the bond that forms next.

Tick Ordering

Same-tick writes are ordered by the tick pipeline: romance_progression_system at slot 9.6, apprenticeship_graduation_system at slot 23d. A graduation and a partnership-formation that land on the same tick write in a consistent order; tests assume this ordering. Future system reorderings must re-confirm the invariant.

Source: crates/er-sim/src/sim/world.rs, tick pipeline; slot documentation in system files.

Interactions

With Romance Dissolution

Origin history is currently the sole lever on the dissolution threshold. The tested and fragile flags on Relationship are computed but not yet read by romance_dissolution_system. If a future system wires those flags into threshold math, the interaction with origin history will need documentation.

With Apprenticeship

A graduation with bond_strength >= 60 records a pending-origin entry even if the pair is not yet Partners. If they become Partners within 30 in-game days, the entry drains. If not, it expires silently. A graduation with bond_strength < 60 does not qualify — the teaching did not sustain long enough for the bond to count as causal. See Apprenticeship for how bond_strength accumulates.

With Mourning

SharedCrisis writes are keyed to Mourning episodes. Two distinct bereavements produce two entries; repeated catalyst firings during one bereavement produce one. See Relationships § Departure Cascade for how Mourning is triggered.

With Save Files

origin_history and strength_min both persist across saves. Partnerships formed before this system existed load with empty history and strength_min equal to current strength (no lost-history assumption — the pre-feature data simply cannot be inferred).

PendingOriginWrites is a runtime-only resource and is not saved. An apprenticeship that graduates shortly before a save, followed by a partnership formation shortly after a load, will not record the Apprenticeship origin — the pending entry was lost. This window is narrow (graduation → partnership within 30 days, across exactly the save boundary) and accepted as a known limitation.

Tips

• Watch for the endurance event. ... 's partnership endured in the event feed means dissolution pressure crossed 100 but the partnership survived on origin resistance. It is the most reliable signal that origin markers are doing work in your settlement. These events first appear roughly day 30--80 in a typical playthrough — the earlier ones are memorable precisely because they're the first time the mechanic manifests.

• Apprenticeship + partnership is the strongest pairing. A master-student pair who reach bond_strength 60+ and later fall in love enter partnership with +20 resilience already banked. Pair elves with similar aesthetics during apprenticeship formation (smaller aesthetic distance means faster post-graduation friendship drift, which is a prerequisite for the romance warmth sources). See Apprenticeship.

• Grief forges durable bonds. A pair who comfort each other through the departure of a mutual friend earn a SharedCrisis origin — and the +6 warmth catalyst from SharedGrief often sparks the romance itself. Bereavement is generative, not purely corrosive. See Romance § Warmth Sources.

• Rivalries that turn to love are fragile. RivalryToLove carries a -10 dissolution delta — partnerships that rose out of hostility dissolve easier than baseline, not harder. The identity is preserved as cost, not as protection. Expect these to break more readily under aesthetic drift; pair them with proximity (partners within 3 tiles get -2 pressure per cycle) if you want them to last.

• Caps prevent runaway resilience. SharedCrisis stops contributing after 3 occurrences (+45 max) and the total positive delta clamps at +50 (threshold 150). A partnership that weathered five bereavements is not five-bereavements strong — it is three-bereavements strong in game terms, though the full count still renders in the UI. This is deliberate: long-running dynasties cannot accumulate infinite resistance and lock into un-dissolvable pairs.

• Re-partnering is a clean slate. When a partnership dissolves, origin_history and strength_min reset on the surviving partner. A widow who loses a 20-year-strong mentor-partnership and later pairs with someone new starts that new bond with the baseline threshold of 100. Grief carries forward as personality scars, not as partnership resilience.

• Dense histories are legible but long. The Relationships screen shows full origin history on one line. A partnership with five entries will produce a wide line. No truncation is applied; overflow is accepted until the shape of real-game data shows it matters.

Personality

Every elf has a personality defined by three axes -- boldness, patience, and pride. These aren't static labels. Root values shift permanently through scars, while expressed behavior drifts gradually toward the new root through maturation. An elf who suffers heartbreak doesn't change overnight; they change over hundreds of ticks, slowly becoming more cautious.

Overview

Personality has two layers:

• Root values (boldness, patience, pride): the elf's deep self. Only modified by scars. Set at birth/arrival and rarely change.
• Expressed values: what the elf actually acts on. Nudged toward root values by maturation every 50 ticks. These are what other systems read.

Each axis ranges from 0.0 to 1.0, with 0.5 as neutral:

The combination of all three axes defines an elf's gestalt -- a named archetype based on which octant of personality space they occupy.

Source: src/sim/components.rs, Personality struct -- root and expressed fields, PersonalityAxis enum.

How It Works

Gestalts

Every elf is assigned a gestalt based on whether each root axis is above or below 0.5. There are 8 gestalts, one for each corner of the personality cube:

Gestalt names appear in the elf detail view. They don't directly affect mechanics -- the three axis values do -- but they give a quick read on an elf's temperament.

Source: src/sim/components.rs, PersonalityGestalt enum and Personality::gestalt() method.

Generation

Founders (the starting elves) get personality values generated near the 8 corners:

• Base: 0.85 (high) or 0.15 (low) per axis
• Jitter: +/-0.1
• This creates distinct personality clusters in your starting population

Arrivals use bimodal generation:

• Each axis: 0.2 or 0.8 base (50% coin flip) + +/-0.1 jitter
• This produces elves with strong personality leanings, not wishy-washy midpoints

Expressed values start equal to root values. Divergence only happens after scars shift the root.

Source: src/sim/components.rs, Personality::random_founder and arrival generation in src/sim/arrival.rs.

Maturation

Every 50 ticks, expressed values drift toward root values:

expressed += (root - expressed) x rate

The rate is age-dependent -- young elves reshape quickly, elders resist change. See Lifecycle & Aging for the full stage-by-stage breakdown:

At the Prime rate of 2% per cycle, after a scar shifts a root value:

• 500 ticks (~5 days): 82% of the way to the new root
• 1,000 ticks (~10 days): 96% converged
• 1,500 ticks (~15 days): effectively identical to root

Young elves reach the same convergence roughly twice as fast; Elder elves take roughly four times as long. Identity calcifies with age.

Source: crates/er-sim/src/sim/systems/mood.rs, personality_maturation_system; crates/er-sim/src/sim/components.rs, Stage::maturation_rate.

Sigmoid Effect

When personality values are read by other systems (romance warmth, social bonding, crisis triggers), they pass through a sigmoid function that compresses the middle and stretches the extremes:

if raw < 0.5:  2.0 x raw x raw
if raw >= 0.5: 1.0 - 2.0 x (1.0 - raw) x (1.0 - raw)

This means personality only has strong mechanical effects at the extremes. An elf with boldness 0.4 vs 0.6 behaves almost identically. An elf with boldness 0.1 vs 0.9 behaves very differently.

Source: src/sim/components.rs, Personality::sigmoid_effect.

Personality Crises

Extreme personality values can trigger transient crisis states under certain conditions. The crisis system runs every 10 ticks. See Scars — Transient Crisis Markers for the full table and mechanics.

Only EgoWound leaves a permanent scar when it expires. The others resolve without lasting personality change — the elf rode out the weather.

Source: crates/er-sim/src/sim/systems/social.rs, conflict_system (EgoWound / LongPatienceBroken triggers) and personality_crisis_system (Withdrawal / RecklessAbandon triggers, all four expiries).

Scars

Scars are permanent modifications to root personality values — the one mechanism that actually moves root axes after character generation. Each scar applies a small axis shift (clamped to 0.05-0.95), carries a narrative label, and costs -1.5 satisfaction forever.

Five scar kinds exist: Heartbreak, EgoWound, Betrayal, Unrequited, PartnerLoss. Four of five shift boldness downward — emotional loss makes elves cautious.

For full details — formation conditions, root-shift values per scar, events, composition interactions, and the boldness-erosion spiral that pushes elves toward departure — see the dedicated Scars page.

Source: src/sim/components.rs, PersonalityScar struct, ScarKind enum, Personality::apply_scar.

Values & Formulas

Satisfaction Bonuses by Personality

The satisfaction system applies personality-specific bonuses every 10 ticks:

Source: crates/er-sim/src/sim/systems/satisfaction.rs, satisfaction_system -- personality bonus section.

Personality Effects Across Systems

Interactions

Departure Risk

Scars push elves toward departure through two channels:

1. Direct satisfaction penalty: -1.5 per scar
2. Boldness erosion: Heartbreak, Betrayal, and PartnerLoss all reduce boldness. Lower boldness means slower romance warmth accumulation (x0.6), making it harder to form new partnerships -- which would provide +10 satisfaction.

An elf who suffers multiple romantic losses enters a downward spiral: scars reduce satisfaction, boldness erosion makes recovery harder, and departure becomes increasingly likely.

Composition Properties

Personality influences composition through crisis states and scars:

• Heartbreak scar + currently unpartnered: unlocks the Heartbreak property (raw emotional art, +15 emotional)
• PartnerLoss scar + actively mourning same person: +10 emotional boost (no property slot — it's a resonance)
• Currently courting (not a scar): unlocks the LoveSong property

Revel Behavior

Personality drives revel attendance decisions. During the gathering phase, elves with extreme personality values may choose not to attend:

• Cautious (boldness < 0.3): "chose the forest over the fire"
• Proud (pride > 0.8): "refused to attend -- if they don't want their art, they don't want their festival"

These absences generate RevelAbsence events in the log.

Tips

• Read the gestalt, but watch the axes. IronCrowned tells you an elf is bold+patient+proud, but the specific values matter. An IronCrowned at (0.55, 0.55, 0.55) behaves very differently from one at (0.95, 0.95, 0.95) due to the sigmoid effect.

• Scars are permanent but slow-acting. After a heartbreak, the elf's expressed boldness doesn't drop for days. Use the maturation window to stabilize them -- place them near friends, give them meaningful work.

• Cautious elves are fragile. They accumulate romance warmth at 60% rate, making courtship slower. If their partner leaves, the PartnerLoss scar pushes boldness even lower. A formerly cautious elf with two PartnerLoss scars may never form another partnership.

• Proud elves resist romance. The x0.8 warmth multiplier for pride > 0.7 means proud elves take longer to fall in love, but their partnerships are no more stable than anyone else's. A proud elf who does partner up is just as vulnerable to dissolution from aesthetic drift.

• EgoWound is the only scarring crisis. A proud elf (pride > 0.85) whose morale drops below 40 after an argument enters an EgoWound crisis — 150 ticks. If it expires, they gain a permanent EgoWound scar (pride +0.03, patience -0.05). Withdrawal, RecklessAbandon, and LongPatienceBroken all expire silently. See Scars — Transient Crisis Markers.

Scars

Elves remember. When something significant happens to them — a partnership ends, a love goes unreturned, a pride is wounded past bearing — the event leaves a permanent mark called a scar. Scars shift root personality values by small amounts, and those shifts are forever. They accumulate. A long-lived elf who has weathered two heartbreaks and a betrayal is, mechanically, a different person than the one who arrived — slightly more cautious, slightly more bitter, slower to warm, quicker to leave.

This is the deep-time social layer of the sim. Most mood shifts decay. Scars don't.

Overview

A scar has two effects:

1. A permanent shift to root personality values. Root values feed expressed values through slow maturation (see personality), so the change is visible but gradual.
2. A narrative label — a human-readable string attached to the elf, visible in the detail view, naming what happened and who caused it.

Scars are additive. The same elf can accumulate multiple heartbreaks, a betrayal, and a partner loss, and every one of them contributes to the final root values. Root values are clamped to the range 0.05 -- 0.95 after each scar applies, so an elf can approach but never reach absolute extremes.

Each scar also costs -1.5 satisfaction forever, via the satisfaction system's scar_penalty term. Four scars is -6.0 permanent satisfaction — a background gravity pulling the elf toward departure.

Source: crates/er-sim/src/sim/components.rs, Scars, PersonalityScar, ScarKind, Personality::apply_scar. crates/er-sim/src/sim/systems/satisfaction.rs, scar_penalty term.

Scar Types

Five scar kinds exist today. Each has its own trigger, axis shift, and narrative template.

Note the pattern: four of five scars shift boldness down. Emotional loss makes elves cautious. The sim systematically erodes boldness across an elf's romantic life, and only deliberate intervention — giving them friends, meaningful work, aesthetic alignment — keeps them bold enough to form the next partnership.

Source: crates/er-sim/src/sim/components.rs, ScarKind enum and Personality::apply_scar match.

Formation Conditions

Each scar has precise trigger conditions in code. Knowing them helps you predict where scars will appear and intervene before they do.

Heartbreak — both partners

Fires in the romance dissolution system (every 100 ticks) when a partnership dissolves via the normal-drift path (aesthetic distance, prestige asymmetry, accumulated pressure ≥ 100.0). Both ex-partners receive the scar and a "Partnership ended" -8 mood for 300 ticks.

• Condition: dissolution_pressure >= 100.0 AND origin history does not save the partnership.
• Applied to: both elves.
• Label: each sees "Scarred by the silence of [the other]".

Betrayal — the betrayed only

Fires in the same dissolution system, but through a different branch. If an elf's partner is currently courting someone else, the partnership dissolves instantly (pressure snaps to 100.0, reason = "betrayal").

• Condition: partner has RomanticState.courting = Some(third_name) where third_name != self.
• Applied to: only the betrayed elf — the cheater walks away with no permanent mark.
• Label: "Trust broken by [ex-partner]".
• Mood: -10 "Betrayed" for 300 ticks.
• Origin history does not protect against betrayal. By design: a chosen act is categorically different from gradual drift.

Unrequited — the pining elf

Fires in the romance courtship system (every 50 ticks) when an attraction has been one-sided for too long.

• Condition: tick - spark_tick >= 200 AND the target's warmth toward this elf is < 30.0.
• Applied to: the elf who pined.
• Label: "Love unmet by [target]".
• Side effects: their own warmth toward the target is set to 20.0 (bittersweet memory, not erased); -5 "Unrequited feelings" mood for 150 ticks.

PartnerLoss — the one left behind

Fires in the satisfaction system (every 10 ticks, departure phase) when a partner elf departs the settlement (satisfaction-driven departure, legacy, or otherwise).

• Condition: the departing elf has an active partnership; their partner remains.
• Applied to: the remaining partner only.
• Label: "Lost [departed] to the road".
• Side effects: partnership is cleared (partner = None, courting = None, dissolution_pressure = 0); Mourning attached for 300 ticks (longer than friend mourning's 200); grief stacks with any existing mourning.

EgoWound — from the crisis, not the argument

Unlike the others, EgoWound does not fire directly from an event. It is the expiry payload of the EgoWound crisis marker (see Transient Crisis Markers below). The chain:

1. Conflict system (every 10 ticks): when two elves argue, if one has pride > 0.85 AND morale < 40 AND no existing EgoWound, they gain an EgoWound crisis marker with 150 ticks remaining and a -8 "Wounded pride" mood.
2. Personality crisis system (every 10 ticks): decrements the marker each tick-batch. When it hits 0, the marker is removed — and the elf receives a permanent EgoWound scar.

So EgoWound scars are a delayed consequence of unresolved wounded pride. A proud elf whose morale recovers fast enough might weather the crisis without lasting mark — if the crisis expired would still leave the scar, but the timeline gives you ~15 in-game days to fix what hurt them.

Source: crates/er-sim/src/sim/systems/social.rs, conflict_system (crisis trigger at line ~598), personality_crisis_system (scar on EgoWound expiry at line ~702).

Transient Crisis Markers

Four non-scar marker components exist as short-lived ECS attachments. They modulate behavior temporarily and sometimes leave a permanent scar when they expire. They are not scars — they are crisis states the elf is currently in.

EgoWound is the only crisis that always leaves a permanent scar. The others are temporary — a lesson the elf learned, or a weather pattern they rode out. They fire PersonalityCrisis cultural events when they begin, but no ScarFormed event when they expire (except EgoWound).

Why the asymmetry? Bold elves overwhelmed by crowding (Withdrawal) can recover when the crowd thins; impulsive elves giving up on stuck goals (RecklessAbandon) feel relief, not damage; patient elves who finally snap (LongPatienceBroken) reset. But pride, once wounded below morale-40, calcifies — the memory persists as a personality shift.

Source: crates/er-sim/src/sim/components.rs, EgoWound/Withdrawal/RecklessAbandon/LongPatienceBroken structs. crates/er-sim/src/sim/systems/social.rs, personality_crisis_system — all four markers decay, only EgoWound writes a scar.

Events

Two CulturalEvent variants surface scars and crises to the player log.

ScarFormed

Fires every time a scar is applied. Payload:

#![allow(unused)]
fn main() {
ScarFormed {
    elf: String,        // the scarred elf's display name
    scar_label: String, // e.g. "Scarred by the silence of Thalindra"
}
}

• Priority: Notable (shows in standard log, not just detailed view).
• Display string: the scar_label verbatim. The scar speaks for itself — no templating wraps it.
• Fires from: romance_courtship_system (Unrequited), romance_dissolution_system (Heartbreak, Betrayal), satisfaction_system (PartnerLoss), personality_crisis_system (EgoWound scar on crisis expiry).

PersonalityCrisis

Fires when a transient crisis marker is attached — not when it expires.

#![allow(unused)]
fn main() {
PersonalityCrisis {
    elf: String,
    crisis: String, // "ego wound" | "patience shattered" | "withdrawal" | "reckless abandon"
}
}

• Priority: Notable.
• Display string (evocative per crisis):
  • "ego wound" → "[elf] retreats, pride wounded beyond bearing"
  • "patience shattered" → "[elf]'s legendary patience finally snapped"
  • "withdrawal" → "[elf] withdraws from the settlement, overwhelmed"
  • "reckless abandon" → "[elf] throws caution aside in a manic burst"

Source: crates/er-sim/src/sim/events.rs, ScarFormed and PersonalityCrisis variants; EventPriority match; display_string implementation.

Interactions

The Boldness Spiral

Scars push elves toward departure through two reinforcing channels:

1. Direct satisfaction penalty. Each scar is a permanent -1.5 on the daily satisfaction calculation. Four scars is -6.0 — approaching the threshold where an elf starts strongly considering departure.
2. Boldness erosion. Heartbreak, Betrayal, PartnerLoss, and Unrequited all push boldness down. Lower boldness slows romance warmth accumulation (x0.6 for boldness < 0.3 vs x1.3 for > 0.7), making recovery through new partnership harder. It also raises the chance of a revel absence — "chose the forest over the fire" — compounding isolation.

An elf who loses one partner to departure and then goes unrequited when reaching out to someone new has two scars costing -3.0 satisfaction, boldness reduced by -0.08, and is now measurably worse at starting the next partnership. Without intervention, the spiral is how elves leave.

Composition Properties

Scars shape the art elves make.

• Heartbreak scar + currently unpartnered: unlocks the Heartbreak composition property. Emotional score +15, property slot filled.
• PartnerLoss scar for a currently-mourned elf: +10 emotional boost (stacked if the mourning is for the same name as the scar). No property slot consumed — it's a compound resonance, grief made legible through art.

Note: the LoveSong composition property is driven by currently courting, not by scars. Wiki entries elsewhere that attribute LoveSong to Heartbreak/PartnerLoss are stale — see crates/er-sim/src/sim/systems/compose.rs for the current rules.

Source: crates/er-sim/src/sim/systems/compose.rs, Romance composition properties section.

Rebuilding After Scars

Scars cannot be removed, but their effect on an elf's life depends on what comes next.

• Maturation moves expressed values toward root, and root values are what scars shift. So the personality change is slow — see lifecycle. A heartbroken young elf shifts within a week of in-game time; an elder barely moves.
• New partnerships provide +10 satisfaction, enough to offset several scars' direct penalty.
• Friends, meaningful work, and aesthetic alignment keep satisfaction above departure threshold even as scars accumulate.

The sim models a specific emotional truth: damage is real and permanent, but it's not deterministic. An elf with five scars can still have a long, satisfying life — they'll just be different than the elf who arrived.

Tips

• Watch for proud-and-miserable elves. Pride > 0.85 and morale < 40 after any argument is the EgoWound crisis window. 150 ticks to recover their mood before the scar locks in. A single kept friendship or a satisfying composition can save them.

• Protect couples during prestige gaps. Prestige asymmetry feeds dissolution pressure; pressure ≥ 100 fires Heartbreak on both sides. If one partner is breaking out as Renowned and the other stays Emerging, consider leveling the trailing partner's revel exposure before the gap becomes decisive.

• Betrayal is one-sided by design. When a partner starts courting someone else, the betrayed elf takes the full hit and the cheater walks. This is intentional — players should read infidelity as a moral event, not a symmetric breakup. But mechanically: the cheater is the one who survives unscarred, and the betrayed may never form another stable partnership.

• Unrequited has a 200-tick deadline. A one-sided attraction that hasn't reached mutual warmth (≥30) within 200 ticks resolves as Unrequited. If you see a potential pairing that's stalled, the window to shift aesthetic alignment or geography is finite.

• PartnerLoss compounds with Mourning. The -5 "Grieving" mood stacks with the -8 "Partnership ended" style grief; the scar is permanent and the boldness drop slows future recovery. Losing a partner to departure is the single hardest scar to recover from — a partner, a mood penalty, a boldness drop, and 300 ticks of active mourning, all at once.

• Scars tell stories. Read the labels. An elf carrying "Scarred by the silence of Thalindra", "Love unmet by Celebwen", and "Lost Aerendir to the road" isn't just a set of lowered stats — they are a person with a specific emotional history. The sim remembers for you; let it show up in how you play them.

Grief & Tribute

When an elf loses someone they were close to — a friend, a partner, a bonded tree — they don't simply log a mood penalty and move on. They enter mourning: a multi-tick state that pulls them toward the workshop, marks any composition they create as an elegy, and weaves the lost name into the colony's emotional memory.

Grief is one of the few states that overrides an elf's normal task priorities. A mourning elf will leave food gathering, building, and aspiration work to compose. What they make while grieving carries unusual emotional weight — and what they refuse to make can fracture friendships across the settlement.

Overview

The grief arc has four stages:

1. Loss — a close friend departs, a partner leaves, or a bonded tree dies.
2. Mourning — the bereaved elf gains a Mourning component with a ticks_remaining countdown and a "Grieving" mood modifier. They prefer composing over other tasks.
3. Tribute — if a workshop is available, the mourner composes. Any composition created while Mourning is present gains the Elegy property (+15 emotional). A TributeComposed event fires.
4. Resolution — when ticks_remaining hits zero, grief_system removes the Mourning component and clears per-episode dedup keys in PendingOriginWrites. The grief is over; the elegy remains.

The arc is gated by emotional closeness. Acquaintances and rivals don't trigger mourning. Friends below strength 60 don't trigger mourning. Only close friends (strength ≥ 60), partners, and bonded trees do.

Source: crates/er-sim/src/sim/components.rs, Mourning; crates/er-sim/src/sim/systems/mood.rs, grief_system; crates/er-sim/src/sim/systems/satisfaction.rs and lifecycle.rs for the spawn sites.

How It Works

What Triggers Mourning

Three pathways apply a Mourning component. Each sets a different duration based on the depth of the loss:

A MourningBegan event fires for elf-on-elf mourning. Tree mourning fires BondedTreeDied instead (and ElegyRefused for the refusal branch). Both are emitted at EventPriority::Notable.

Source: crates/er-sim/src/sim/systems/satisfaction.rs:518-532 (friend), :535-575 (partner); lifecycle.rs:158-167 (fulfilled departure); flora_systems.rs:585-680 (tree death).

Effects on the Mourner

While Mourning is present, the elf is changed in three player-visible ways:

Mood. A "Grieving" modifier of -5 is pushed for 200 ticks. This stacks with the "Friend departed" or "Partner departed in fulfillment" mood modifier that fires alongside the death — a partnered elf losing their bonded mate carries both penalties simultaneously.

Behavior. task_decision_system checks is_mourning before checking creative block, aspirations, and idle decisions. A mourning elf is pulled toward TaskKind::Compose if a Workshop building exists. If no workshop is available, they default to TaskKind::Wander — wandering in grief is preferred over gathering or building. Critical needs (sustenance < 20, rest < 20) still take priority over mourning.

Composition. Any composition completed while Mourning is present automatically gains the CompositionProperty::Elegy property, which adds +15 to the emotional score. The Elegy property occupies a property slot (max 2), so it competes with seasonal properties, Heartbreak, LoveSong, Debut, Stormborn, etc.

Source: crates/er-sim/src/sim/systems/behavior.rs:181-191 (task decision); crates/er-sim/src/sim/systems/compose.rs (Elegy property assignment, TributeComposed emission).

The Tribute

When a mourning elf finishes a composition, two events fire:

• ArtCompleted — the normal completion event listing the piece's tier and properties (including Elegy).
• TributeComposed { composer, departed, composition_name } — the elegy-specific event naming the departed friend. Notable priority.

There's no quality threshold for a tribute. Any composition a mourning elf finishes is a tribute, regardless of mastery, originality, or audience reception. The dedication is what matters — the mourner pointed their grief at a workshop and made something.

A single mourning episode can produce multiple tributes if the mourner composes more than once before ticks_remaining expires. Each fires its own TributeComposed event.

Source: crates/er-sim/src/sim/systems/compose.rs:305-312, Elegy property assignment.

Refusing the Elegy

The tree-death branch of grief has a hard fork that elf-on-elf mourning does not. When a Notable tree dies and its bonded elves are about to enter mourning, each bonded elf is checked against their AestheticPosition.tradition value:

A refuser doesn't grieve the bonded-tree-style elegy, but they still take the full mood penalty. They reject the ritual, not the feeling.

Refusal has a social cost. Any elf with high tradition (aesthetic.tradition > 0.7) and low tolerance (aesthetic.social × personality.patience < 0.2) is offended. Each traditionalist:

• Gains a -3 "Ancient rites disrespected" mood modifier for 100 ticks
• Has their Relationships toward each refuser adjusted by -10
• Emits a RitesDisrespected { offended_elf, refuser } event per refusal

This is the only place in the sim where a refusal to grieve in the traditional way generates measurable interpersonal damage. A colony with many low-tradition elves and many high-tradition traditionalists can fracture along ritual lines after a single notable tree dies.

Source: crates/er-sim/src/sim/flora_systems.rs:619-677, tradition gate and traditionalist reaction.

Resolution

grief_system runs every tick at pipeline slot 6.5 (after mood_system). Each tick it does two passes:

1. Expire: collect Mournings where ticks_remaining == 0, capture (entity, elf_name, departed_friend), then remove the component and clear matching SharedCrisis dedup entries in PendingOriginWrites so the partnership-origin bookkeeping doesn't grow unbounded.
2. Decay: for every remaining Mourning, decrement ticks_remaining.

Order matters: capture-before-remove ensures the departed name is preserved for pending_origins.clear_crisis_keys_by_departed(...). The clear is scoped per (elf_name, departed_friend) pair — unrelated SharedCrisis entries for the same elf pair (a different departed) are preserved.

There is no event for mourning ending. The Mourning component simply disappears. Player-facing closure comes from the tribute (TributeComposed) or the silence of having composed nothing.

Source: crates/er-sim/src/sim/systems/mood.rs:57-96, grief_system; crates/er-sim/src/sim/pending_origins.rs:80-90, dedup-clear contract.

Cultural Events

The grief arc fires four cultural events, all at EventPriority::Notable:

MourningBegan is not emitted by the fulfilled-departure path or the tree-death path — only by dissatisfied departures. A fulfilled elder's friends enter mourning silently (no event), and tree mourners fire BondedTreeDied instead.

Source: crates/er-sim/src/sim/events.rs:229-256, 339-353, 741-771 (priority tags); events.rs:579-668 (display strings).

Interactions

With Partnerships

A Partner relationship triggers the partner-loss branch on departure, distinct from the friend branch:

• Partnership state cleared (partner = None, courting = None, dissolution_pressure = 0.0)
• PersonalityScar { kind: ScarKind::PartnerLoss } added to Scars
• Personality::apply_scar(PartnerLoss) permanently shifts root personality (see Scars)
• Mourning duration: 300 ticks (vs. 200 for a close friend) — or current ticks_remaining + 100 if already mourning
• ScarFormed event fires alongside any MourningBegan

A partner death is one of the few events that can stack mourning on top of mourning. An elf already grieving a friend whose partner then departs sees their mourning extended by 100 ticks rather than reset.

Source: crates/er-sim/src/sim/systems/satisfaction.rs:535-575, partner-loss branch.

With Romance

Mourning is one of the strongest catalysts for new attractions. Per romance:

• Shared grief (both elves mourning the same departed friend): +6.0 warmth per cycle, catalyst flag set — unlocks the courtship transition.

Two elves who lose the same close friend can spark a courtship from comfort alone, even if they barely knew each other before the loss. This is the "grief bond" — emergent, asymmetric, and unscripted.

The PendingOriginWrites system tracks this with per-episode dedup so that a single 200-300 tick mourning episode doesn't multiply SharedCrisis partnership-origin entries across the 50-tick warmth cadence (romance_warmth_system runs every 50 ticks; mourning lasts 150-300 ticks, so naive accumulation would produce 3-6 entries per pair per death).

Source: crates/er-sim/src/sim/pending_origins.rs, dedup contract; crates/er-sim/src/sim/systems/romance.rs, SharedGrief warmth source.

With Composition

The Elegy property is one of five "named-circumstance" composition properties (alongside Heartbreak, LoveSong, Stormborn, Debut). It is automatic — no aspiration, skill check, or audience condition gates it. If Mourning is present at the moment of composition completion, the property is added (provided fewer than 2 properties are already attached).

Elegy properties stack with seasonal properties (Vernal/Solstitial/Autumnal/Hibernal) — a winter elegy can carry both Hibernal and Elegy. They do not stack with Heartbreak and LoveSong if the slot budget is full; the property-pushing order in compose_system determines which wins. Elegy is pushed before Heartbreak and LoveSong, so an elf mourning a friend while also unpartnered+heartbreak-scarred ends up with Elegy (not Heartbreak).

A separate composition path triggers on PartnerLoss scar specifically: when an elf with an unresolved PartnerLoss scar composes about the mourned partner, an extra +10 emotional bonus is added without occupying a property slot. See Scars — Composition Properties.

Source: crates/er-sim/src/sim/systems/compose.rs, property-assignment order.

With Behavior Priority

The task-decision priority cascade in task_decision_system places mourning between Discontented (refuses ambitious work) and the normal block/aspiration check:

1. Critical needs (sustenance < 20, rest < 20)
2. Discontented elves — only basic survival
3. Mourning elves — compose if workshop exists, else wander
4. Creative block — skip composing
5. Aspiration goals
6. Normal idle decisions

A mourning and discontented elf falls into the discontented branch and never composes — discontent overrides grief. This is the one case where grief is silenced rather than expressed.

Source: crates/er-sim/src/sim/systems/behavior.rs:142-191, priority cascade.

Tips

• Tributes are quiet revolutions. A mourning elf doesn't need high music skill to produce a tribute. Even a tier-1 Mediocre composition with the Elegy property carries +15 emotional — enough to shift a revel's audience reactions toward Love. If you have a low-skill elf and an unexpected friend-departure, let them compose; the tribute may outperform their normal work.

• Workshops save grief. A mourning elf with no workshop available will wander instead of compose. That means no tribute, no TributeComposed event, no Elegy property — just 200-300 ticks of -5 mood with nothing produced. Build workshops near where your tightest friendships cluster.

• Notable trees are emotional time bombs. Once a tree becomes Notable, every elf with a TreeBond to it is on a fuse. Tree death is not always avoidable (seasonal die-off, age), and a single notable death can mourn 3-5 elves simultaneously. Watch which elves bond to which trees and consider whether the tree is in a stable spot.

• Tradition fault lines. A colony with a wide spread of tradition values (some elves below 0.3, some above 0.7) is one notable-tree death away from a RitesDisrespected cascade — each refuser triggers a -10 relationship hit from every offended traditionalist, and -10 per refusal compounds quickly. Track aesthetic distance, not just population count, when picking arrivals.

• Don't fear the grief bond. When a beloved elf departs, the friends they leave behind often form unexpected partnerships through SharedGrief. Two elves who mourned the same person can become each other's partners. The loss isn't replaced — it's woven into the next bond's origin.

• Partner-loss is permanent in a way friend-loss isn't. The PartnerLoss scar shifts root personality (Personality::apply_scar) and persists for the rest of the elf's life unless resolved. A widowed elf grieves harder (300 ticks vs 200), carries the scar forever, and unlocks the +10 emotional bonus composition path when they compose about the partner. Friend-grief is a wave; partner-grief is a tide.

Lifecycle & Aging

Elves age. Skill comes easier when they are young; compositions reach their peak in their prime; their voice carries further once they are elders. When an elder has lived a satisfied life long enough, they do not depart in bitterness -- they attend one last revel, say goodbye, and leave a legacy behind that the colony remembers.

Overview

Every elf carries an Age component set at spawn. Age measures ticks lived since birth. Four stages bracket that lifespan, each shifting how the elf interacts with nearly every downstream system:

(DAY_LENGTH = 100 ticks.)

Stage is derived from tick - birth_tick on demand -- it is not stored. A cached last_known_stage field lets transition detection fire exactly once per boundary crossing.

Three systems drive the lifecycle:

• age_stage_system (once per day) -- emits StageTransition events when the cached stage differs from the current one.
• elder_fulfillment_system (every 50 ticks) -- tracks how long each elder has been satisfied; marks them Fulfilled after 500 ticks above satisfaction 70.
• farewell_departure_system (every tick) -- processes elders marked AwaitingFarewell, spawning a LegacyFigure record and despawning the elder.

Source: crates/er-sim/src/sim/systems/lifecycle.rs; crates/er-sim/src/sim/components.rs, Stage, Age, Fulfilled, FulfillmentProgress, AwaitingFarewell, LegacyFigure.

How It Works

Stage Multipliers

Each stage scales four numeric bands of the elf's behavior. The multipliers are read at call-sites throughout the sim; no single system applies them all.

The shape is deliberate:

• Young elves learn fast (1.3x XP) but make lower-quality work (0.8x quality).
• Prime elves produce their best compositions (1.2x quality) with normal XP and physical ability.
• Mature elves lose some XP gain (0.7x) and physical rate (0.8x) but their prestige weighs more heavily in satisfaction (1.3x).
• Elder elves move slowly (0.5x physical, 0.5x XP) but their work carries unusual emotional weight (+10 to the emotional score on every composition, on top of 1.1x base quality). Their prestige also weighs more in satisfaction than any other stage (1.5x).

Elders are slower hands, but deeper voices.

Source: crates/er-sim/src/sim/components.rs, Stage::skill_xp_multiplier, comp_quality_multiplier, physical_multiplier, influence_multiplier, elder_emotional_bonus.

Personality Maturation Rate

The personality maturation system -- which nudges expressed personality values toward their roots -- also scales by age stage. Young elves change most quickly; elders are almost immovable:

This means a scar applied in youth reshapes the elf fast; a scar applied to an elder barely shifts their behavior before they depart. Identity calcifies with age.

Source: crates/er-sim/src/sim/components.rs, Stage::maturation_rate; applied in crates/er-sim/src/sim/systems/mood.rs, personality_maturation_system.

Stage Transitions

Once per day (tick multiple of DAY_LENGTH = 100, skipping tick 0), every elf's current stage is compared to their cached last_known_stage. If the stage advanced, the cache updates and a StageTransition { elf, from, to } cultural event fires.

There is no hard cap at Elder -- once an elf reaches stage Elder at tick 4,000, they remain Elder for the rest of their life. Departure happens through satisfaction mechanics, not a hard age limit.

Source: crates/er-sim/src/sim/systems/lifecycle.rs, age_stage_system.

Elder Fulfillment

When an elf reaches Elder stage and has satisfaction > 70, an invisible counter starts. Every 50 ticks:

• If their satisfaction is still above 70, add +50 to FulfillmentProgress.ticks_above.
• If their satisfaction drops to 70 or below, reset FulfillmentProgress to zero. Partial progress does not persist.

When the counter reaches 500 ticks (10 game days of continuous happiness as an elder), the elf is marked Fulfilled. The FulfillmentProgress component is removed and an ElderFulfilled event fires.

An elf who spends their elder years bouncing between content and discontent never completes the fulfillment path. The fulfillment counter is strict -- sustained contentment, not average contentment, is what marks an elder for an honored departure.

Source: crates/er-sim/src/sim/systems/lifecycle.rs, elder_fulfillment_system -- threshold 70.0, accumulator step 50, completion at 500.

The Farewell Revel

Being marked Fulfilled does not trigger an immediate departure. Instead, the elf waits for the next revel they attend. When that revel concludes, the finalization pass scans attendees for the Fulfilled marker and tags each one with AwaitingFarewell.

This is deliberate: the revel is the farewell. The community gathers, the fulfilled elder performs or witnesses one last performance, and only then do they leave. There is no silent fulfilled departure.

On the next tick after being tagged, farewell_departure_system runs the full departure sequence:

1. Build a LegacyFigure record from the elder's portfolio, prestige, love reactions, and revels performed.
2. Emit a FulfilledDeparture { elf, legacy_score } event (notable priority).
3. Apply the fulfilled-departure mood cascade to every elf in the elder's relationship list.
4. Apply any apprenticeship cleanup (see apprenticeship).
5. Despawn the elder.

Source: crates/er-sim/src/sim/systems/revel.rs (Fulfilled detection + AwaitingFarewell tag at line 523); crates/er-sim/src/sim/systems/lifecycle.rs, farewell_departure_system.

Fulfilled Departure Mood Cascade

A fulfilled departure is bittersweet, not devastating. Mood effects on surviving elves are softer than for a dissatisfied departure, and the mourning period is shorter:

Friends with strength >= 60 and all Partners also enter a Mourning state -- but the Mourning component is created with ticks_remaining: 150, shorter than the 200-tick mourning that follows dissatisfied departures. The shortening reflects the different emotional shape: the community mourns, but the mourning is wrapped in pride.

Source: crates/er-sim/src/sim/systems/lifecycle.rs, farewell_departure_system -- mood matches at lines 137-141, mourning at line 159.

Legacy Figures

When a fulfilled elder departs, a LegacyFigure record is pushed onto the colony's permanent legacy list. Legacy figures outlive the elves themselves -- they are cultural memory the simulation never forgets.

A LegacyFigure captures:

The legacy_score is a rough numeric summary of cultural impact. A prolific Legendary-tier composer who performed at many revels will leave a higher-scored legacy than a quiet Mature-stage soloist. The score is also announced in the FulfilledDeparture event.

Legacy figures persist in the colony state; they are the kind of historical record a future UI panel could render as a "Hall of Elders." Dissatisfied departures do not currently push LegacyFigure records -- only fulfilled ones earn the remembrance.

Source: crates/er-sim/src/sim/components.rs, LegacyFigure; crates/er-sim/src/sim/systems/lifecycle.rs, score at line 106.

Interactions

Satisfaction & Departure

Fulfilled departure is a separate departure path from the satisfaction-triggered one. The discontented timeline (300 ticks warning, 500 more ticks to depart) does not apply to elders who are flourishing -- they leave through a different gate, at a different cadence, with a different mood footprint on those they leave behind.

The satisfaction formula itself also weights elder elves differently: the prestige bonus term is scaled by the elder's 1.5x influence multiplier. A renowned elder's prestige contributes more heavily to their own satisfaction than a young elf's would, which makes it easier for them to accumulate the 500 ticks of sustained happiness that fulfillment requires.

Personality

The personality maturation system reads the elf's age stage to set the convergence rate. Elves in crisis (scarred) heal quickly when young and slowly when old. An Elder who loses a partner carries that scar for the remainder of their life with very little behavioral adjustment.

Compositions & Revels

Every composition reads the composer's stage through Age to scale mastery and originality by comp_quality_multiplier. Elder compositions receive a flat +10 to their emotional score on top of that multiplier, making late-career works often the most emotionally resonant pieces in a colony's portfolio.

At revel time, the finalization pass checks for attending elders marked Fulfilled. An elder who is fulfilled and attends any revel will depart after that revel -- your scheduling of revels implicitly schedules their goodbyes.

Apprenticeship

When an elder with AwaitingFarewell departs, the farewell system calls cleanup_apprenticeship_on_departure. If the elder was mentoring an apprentice, the student loses their Apprenticeship component and receives a -8 "Mentor departed" mood modifier for 200 ticks.

Students graduated under the elder retain their permanent TrainedBy lineage marker -- the master's name lives on in the student's detail panel even though the elder is gone.

Skills & Work

Build and gather task progress is scaled by physical_multiplier -- Mature elves work at 80% speed and Elder elves at 50%. Skill XP gains are scaled by skill_xp_multiplier, so aging elves climb skill levels slowly even when they work often. A Young elf learning their craft gains XP 2.6x faster than an Elder performing the same task (1.3 / 0.5).

Tips

• Schedule revels for your elders. An elder who reaches Fulfilled status is waiting for the next revel to say goodbye. If you want to delay a beloved elder's departure, holding off on revels buys time -- but keeping them in an environment that produces sustained satisfaction is already in tension with extending their life indefinitely. The simulation is designed for graceful exits.

• Prime is the composition sweet spot. Stage Prime gives 1.2x quality with full physical and XP multipliers, and no elder emotional bonus -- pure technical peak. If you are trying to push a specific elf toward a Magnum Opus (skill 10, inspiration > 90, mood > 50), their Prime window (ticks 500--1,999, days 5--19) is when the composition quality math is most forgiving.

• Elder prestige compounds. The 1.5x influence multiplier on prestige means an elder with a high prestige tier gets more satisfaction from their reputation than any other stage. Keeping a prestige-Renowned elder's satisfaction above 70 long enough to trigger Fulfilled is easier than it looks; the system rewards long-lived success.

• Young elves are emotionally volatile. 4% maturation rate means a scar applied in youth shifts their behavior visibly within a few days. Young elves who suffer heartbreak or unrequited love can change noticeably before you have time to stabilize them. Pair them with friends early.

• Mourning for a fulfilled elder is shorter. 150 ticks vs 200 for dissatisfied departures. Your surviving elves will compose fewer Elegies after a fulfilled departure than they will after a bitter one. If you're chasing Elegy-tagged compositions, dissatisfaction cascades produce them more reliably -- though at the cost of a colony that feels worse.

• LegacyFigures are cumulative, not displayed (yet). The simulation records them permanently, but there is no in-game panel that lists them. This is future UI territory -- a Hall of Elders that shows every fulfilled departure's name, gestalt, compositions, and score. The data is already being collected for that day.

• Cascade softness matters for colony resilience. A dissatisfied departure gives friends -10 mood for 300 ticks; a fulfilled departure gives -5 for 200. Across a long-running colony, a string of fulfilled departures leaves the survivors in noticeably better emotional shape than a string of dissatisfied ones. The lifecycle system is balanced so that peaceful exits preserve the colony's capacity for the next generation.

Satisfaction & Departure

Satisfaction measures how content each elf is with life in the settlement. When satisfaction stays too low for too long, the elf will warn you, then leave permanently. Departures are the primary population-loss mechanic, balanced against the arrival system which brings new elves as colony reputation grows.

Overview

Every elf has a satisfaction value (0--100) that is recomputed every 10 ticks from a weighted formula combining inspiration, mood, friendships, aesthetic alignment, revel quality, and prestige. When satisfaction drops below an elf's personal departure threshold, a countdown begins. If the elf stays below threshold for 300 ticks, they become Discontented (visible warning). If they remain below threshold for 500 more ticks (800 total), they depart -- permanently removed from the settlement.

How It Works

The Satisfaction Formula

Satisfaction is recomputed from scratch every 10 ticks (not accumulated):

Satisfaction = (inspiration x 0.3) + (morale x 0.2) + (friends x 5.0) + (aesthetic_fit x 20.0) + (revel_score x 0.1) + prestige_bonus + personality_bonus + romance_bonus - scar_penalty - overcrowding_penalty + spike

The result is clamped to 0--100.