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