Workers, Residences & Factory Automation

1. Summary

Players can build automated production lines in the world using:

Workers loop while active: travel, work, travel, rest when exhausted. They are not free — wages per tick, training fees, food, beds, and tools.

Currency for wages and sales: copper → silver → gold → platinum (08 §8.5).

2. Design principles

3. Craft residence

A craft residence is a BuildingInstance (20) — kind: residence | workshop — with linked sub-entities:

craft_residence:
  id: residence_b
  owner_character_id: ...
  region_id: ...
  position: { x, y, z }
  links:
    lodging: lodging_b           # beds, pantry
    devices: [wood_mill_1, kitchen_1]
    storage: [storage_house_a, storage_house_b]
    worker_spawn: worker_quarters
  permissions: [owner, guild_crafters]

Residences are region-local — all linked storage/devices should be reachable by pathfinding in the same region (cross-region supply chains = later phase).

4. Craft devices

Devices are world-placed items (crafted or installed) that act as stations (09 §7).

craft_device:
  id: wood_mill_1
  template: wood_processing_mill
  residence_id: residence_b
  allowed_recipes: [lumber_to_plank, hardwood_to_plank]
  fuel: optional              # coal, power crystal — per recipe
  durability: ...
  queue: []                   # optional player queue; workers append

Examples: wood mill, forge, cooking hearth, loom, alchemy bench, inscription table.

Worker + device: worker must be adjacent/in range, have inputs in inventory or pull from linked input storage (config), run CraftExecute for craft_time_ticks modified by worker skill.

5. Workers

5.1 Worker entity

Workers are npc_instances (19) with employer_id — same stats, inventory, and death rules as other NPCs; plus job state (13).

worker:
  id: worker_ana
  name: Ana
  employer_character_id: ...
  residence_id: residence_b
  lodging_bed_id: bed_2
  wage_account: employer_bank   # deducted per tick
  state: working | traveling | resting | idle | dismissed
  attributes:                   # same families as players (`11`)
    STR, DEX, STA, VIT, ...
  skills:
    logging: 12
    hauling: 8
    carpentry: 5
    trading: 3
  pools:
    stamina: { current, max }
    hunger: { current, max }
  inventory: WorkerCarrier       # limited slots — mass/volume (`08`)
  equipment:                     # job outfit
    hands: iron_axe
    body: work_tunic
    pack: small_backpack
  active_job_id: job_lumber_loop

5.2 Hire & dismiss

Hire from labor broker NPCs in towns or recruit after quests. Worker cap per residence from building tier + CHA (optional).

5.3 Training

Employer pays training fee (coins from bank or residence treasury):

training_session(worker, skill, fee) → skill_xp += f(fee, worker.VIT, teacher_quality)

Training can be passive on-job (slow XP while doing related tasks) or active (paid courses at guild hall — faster). Skilled workers: faster harvest, shorter craft ticks, better yields, fewer failures.

5.4 Wages, effort & silver sink (implemented)

Workers are a deliberate coin sink: harder routes cost more payroll, burn food/water faster, and skilled workers charge more while working faster.

Payroll formula (each wage_interval_ticks)

due_cp = round(
  (base_cp + loop_step_cp + travel_cp) * level_wage_mult
).max(1)

Step costing rules (assets/config/server-settings.yaml → workers.step_costs):

Empty companion jobs use idle only.

Pay sources (treasury order)

1. Employer bank ledger (automatic paycheck withdraw; works while offline while the region still tracks the character)
2. Assigned lodging container contents
3. Other employer-owned placed chests within 12 m of lodging (or employer if no lodging)
4. Employer carried coins (root + worn bags)

Other player expenses (taxes, shipping fees, shop buys, hire/train fees, property upkeep) use the same bank-then-purse rule via try_spend_copper.

If unpaid → Strike (job loop halted). While striking, pay retries about every 5 s so restocking lodging/chests (or depositing to bank) resumes work without waiting a full interval.

Hunger / thirst

Per-tick drain is multiplied by the current step’s effort rate (hunger_effort_scale / thirst_effort_scale). On lodging rest_if_needed, workers eat/drink one pantry consumable from the assigned bed container only when hunger or thirst is below 65% — stock the bed itself with soup/water (nearby chests are not scanned for meals; that path is wages-only).

Level bonuses (skilled workers)

Worker XP pacing

Cumulative XP → level via xp_base × growth^(L−1) ceilings. Defaults: xp_base: 2000, growth: 1.65, awards 0.35 per harvest/craft/sell, 1.0 per route wrap, soft-capped at xp_max_per_route_loop: 8 so craft-until-exhausted cannot dump a level in one loop. Expect ~80+ gatherer loops to L2 and hundreds to mid levels.

Client UI

Workers dock shows wage base→effective cp (effective_wage_copper previews base + loop effort; live travel meters add at debit time).

If employer cannot pay → worker strikes (idle at lodging) until paid or dismissed.

6. Lodging, food & rest

Workers do not run 24/7.

Missing bed → worker cannot be set active. Missing food on rest → slower regen, morale debuff, eventual job halt.

7. Job model — one job per worker

7.1 Job definition

A job is a repeating cycle of steps. One active_job per worker.

job_id: job_chop_to_storage_a
worker_id: worker_ana
enabled: true
checkpoint: true              # resume mid-cycle after rest
steps:
  - step: travel
    target: { poi: forest_patch_7 }      # harvest node / landmark / coords

  - step: harvest
    resource: oak_log
    tool: iron_axe                       # must be equipped
    until: { inventory_full: true } | { qty: 20 }

  - step: travel
    target: { storage: storage_house_a }

  - step: deposit
    storage: storage_house_a
    filter: { items: [oak_log] }
    deposit_all: true

  - step: travel
    target: { lodging: lodging_b }       # optional: only if stamina low (condition)

  - step: rest_if_needed                 # implicit between cycles

job_id: job_mill_planks
worker_id: worker_ben
steps:
  - step: travel
    target: { storage: storage_house_a }

  - step: withdraw
    storage: storage_house_a
    items: [{ template: oak_log, qty: 10 }]

  - step: travel
    target: { device: wood_mill_1 }

  - step: craft
    device: wood_mill_1
    recipe: lumber_to_plank
    qty: 10                              # or until inputs exhausted

  - step: travel
    target: { storage: storage_house_b }

  - step: deposit
    storage: storage_house_b
    filter: { items: [hardwood_plank] }

job_id: job_sell_planks
worker_id: worker_cara
steps:
  - step: travel
    target: { storage: storage_house_b }

  - step: withdraw
    storage: storage_house_b
    items: [{ template: hardwood_plank, qty: 50 }]

  - step: travel
    target: { broker: market_c_broker }

  - step: broker_sell
    broker: market_c_broker
    items: [{ template: hardwood_plank, qty: all }]
    pricing: { mode: market | premium_pct: 5 | fixed_silver: 2 }
    currency: silver                     # proceeds → employer bank (`10`)

7.2 Step types

7.3 Harvest loops — route block (implemented)

A high-level route on the job compiles server-side into the travel/harvest/deposit step cycle — this is what the gfx route editor saves:

job_id: route_oak_loop
mode: job_loop
route:
  kind: harvest_loop
  lodging_container_id: bed-1
  outbound_waypoints: [{ x: 12.0, y: 10.0 }]
  harvest_nodes: [oak-1, oak-2]
  carry_return_ratio: 0.90      # head home when carry ≥ 90%
  loop_wait_ticks: 90           # pause at home between loops
steps: []                       # compiled from route

Compiled cycle: travel waypoints outbound → harvest_route over the listed nodes → travel waypoints reversed → travel to lodging bed → deposit all → rest_if_needed → wait → repeat.

Runtime reliability rules (harvest route):

• Drop-centric collection — after a harvest channel completes, the worker walks to each scattered loot pile itself and picks it up by drop id. Loot scatters up to ~1.2 m past the fixed harvest stand position, so chasing the drop (not the node) is what keeps collection reliable; far-side scatter can never stall the loop.
• Never abandon mid-collect — carry-full is only checked at node arrival and at pickup time (hard carry cap → head home to deposit); a node in progress is always finished and collected first.
• Path-failure skip — a node or waypoint with no viable path for ~3s is skipped with a no path … worker error instead of stalling the route; leftover loot at a depleted node is re-collected on a later loop.
• Rest rules — stamina only regens while idle, so the loop paces itself: a worker too tired to start a harvest channel rests in place and resumes the same node once recovered (never an insufficient stamina retry spin); rest_if_needed at the bed tops stamina up to 90% so every loop starts rested; with no active job workers rest in place like any worker.
• Carry capacity — route carry thresholds and encumbrance use the shared agent carry snapshot (same source as the sim's pickup/encumbrance gates), so heavy loads (e.g. oak logs) never fake a "full" reading after one node.

7.4 Timing

tick_time(step) =
  travel:  path_distance / effective_move_speed(worker)
  harvest: base_harvest_ticks / (1 + logging_skill × coeff) × qty
  craft:   recipe.craft_time_ticks / (1 + relevant_skill × coeff)

Travel time is first-class — distant forest + far mill = hire haulers or build closer storage.

7.5 Conditions & branching (Phase 6b+)

- step: withdraw
  storage: storage_house_a
  items: [{ template: oak_log, qty: 10 }]
  on_fail: { wait_ticks: 60, retry: true }   # mill idle until supply

8. Example factory line

Player owns residence B with lodging (2 beds), wood mill, links to storage A (near forest) and storage B (near residence).

  [Forest] ──Ana──► [Storage A] ──Ben──► [Mill @ Res B] ──► [Storage B] ──Cara──► [Broker @ Market C]
                         ▲                                              │
                         └──────────── rest / food @ lodging B ◄─────────┘

Player stocks lodging pantry, pays wages every N ticks, outfits Ana with axe, maintains mill durability, and monitors profit = broker revenue − wages − training − food − fuel.

9. Outfitting

Missing required tool → step fails / worker idles with error to employer TUI. Tools have durability — employer must repair or replace.

10. Economy integration

Workers do not need player online — sim runs on region worker while chunk is active (see §12).

11. TUI / agent

flatland residence list
flatland residence link storage residence_b storage_house_a
flatland worker hire --residence residence_b --name Ana --wage 5_copper_per_100_ticks
flatland worker assign-bed worker_ana bed_2
flatland worker equip worker_ana --slot hands iron_axe
flatland worker train worker_ana --skill logging --fee 2_silver
flatland worker job set worker_ana --file jobs/ana_chop.yaml
flatland worker job enable worker_ana
flatland worker status worker_ana    # step, stamina, location, errors
flatland factory status residence_b  # all workers, storage levels, device queues

Agent JSON: full job state, storage snapshots, P&L estimate.

12. Simulation & region lifecycle

Anti-exploit: cap workers per account; audit broker_sell for wash trading; residence must be in valid claimed territory.

13. Phasing

14. Open decisions

Resolved (2026-07-06):

Worker motivation (F3)

Optional tip % from broker/stall proceeds into worker pool:

motivation += f(tip_received)
efficiency_multiplier = 1 + motivation_bonus × worker_morale

Higher motivation → faster job steps, fewer idle errors.

15. Settlement workers (NPC towns)

Player-hired workers (§1–§14) and settlement workers share the same job engine (09, 18):

Settlement job cycles run when the region is loaded; ops can seed initial stock at realm launch. Players compete with — and buy from — these shelves while building superior unique items via skill, quality rolls, and enchants.

16. Cross-references

Update 09 for device queue API; 10 for worker broker permissions.