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: src/sim/systems.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: src/sim/systems.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: src/sim/systems.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: src/sim/systems.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: src/sim/systems.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.