Coalgov/coalgov-wiki-pages/npcs.txt

====== NPC Workers, Traders, and Households ======

CoalGov NPCs use Citizens. They are server-side entities, so players do not need client mods.

NPCs are managed with:

  /cgnpc

===== NPC Types =====

  * Trader - stores goods, has a coal account, haggles with players, and can receive worker output.
  * Worker - has a role, home, work location, hunger, inventory, coal account, and configured labor.

Workers and traders have their own persisted CoalGov inventories. Supply chains move items between those inventories before goods reach players.

NPCs are meant to behave like small economic agents. A worker travels between home and work, eats food, buys food if funded, requests supplies from same-zone NPCs, and stops working if hunger gets too low.

===== Zones =====

NPCs work inside polygon zones. Use the claim wand to mark points around the work area:

  /claim wand
  /cgnpc zone create <name>

Create NPCs while standing where they should spawn:

  /cgnpc create worker <name> <zone>
  /cgnpc create trader <name> <zone>

After creating an NPC, set its household and job details:

  /cgnpc home <id>
  /cgnpc work <id>
  /cgnpc role <id> <role>
  /cgnpc needs <id>

''/cgnpc home'' and ''/cgnpc work'' use the admin's current location. Home is where an NPC returns during rest hours or when needs are too low. Work is the point the NPC prefers during working hours.

===== Farm-To-Market Example =====

Select a polygon around the farm with ''/claim wand'', then create an NPC zone:

  /cgnpc zone create farm

Create workers and a trader in that zone:

  /cgnpc create worker Farmer farm
  /cgnpc create worker Baker farm
  /cgnpc create trader Marketman farm

Assign homes, work locations, and explicit roles:

  /cgnpc home <farmerId>
  /cgnpc work <farmerId>
  /cgnpc role <farmerId> farmer
  /cgnpc home <bakerId>
  /cgnpc work <bakerId>
  /cgnpc role <bakerId> baker

The default supply chain is:

  * Farmer scans the farm zone for mature WHEAT, CARROTS, POTATOES, and BEETROOTS.
  * Farmer walks to mature crops, harvests drops into NPC inventory, and replants if it has the seed or crop item.
  * Baker pulls WHEAT from same-zone NPC inventories.
  * Baker consumes 3 WHEAT to produce 2 BREAD.
  * Workers eat from their own inventory, then request food from same-zone NPCs, then buy configured food from the market if funded.
  * Workers that are too hungry return home and stop producing until fed.
  * Workers keep a reserve and move surplus output to same-zone traders.
  * Players can haggle with traders for stocked goods.

Example player trade:

  /cgnpc list
  /cgnpc haggle <traderId> buy BREAD 8 8

===== Farm Workers =====

Farm workers use real world blocks. They scan their NPC zone for mature crops, walk to the crop, harvest it, collect the drops into NPC inventory, and replant if they have the correct seed or crop item.

Default supported crops:

  * WHEAT, replanted with WHEAT_SEEDS
  * CARROTS, replanted with CARROT
  * POTATOES, replanted with POTATO
  * BEETROOTS, replanted with BEETROOT_SEEDS

If a worker cannot replant, check its inventory and seed stock:

  /cgnpc stock <id> WHEAT_SEEDS 64

===== Homes, Work, and Needs =====

Each CoalGov NPC stores:

  * Home world and location.
  * Optional work world and location.
  * Explicit role name.
  * Hunger from 0 to 20.
  * Last food time.

Workers rest during configured night hours. During rest they return to home and do not produce goods. During work hours they prefer their work location and wander nearby, while still using their assigned NPC zone for crop scanning and supply-chain transfers.

Needs are configured under ''npc.needs''. Hunger decays on a timer. When hunger is low, the NPC attempts to eat configured foods:

  * First from its own inventory.
  * Then by requesting food from same-zone NPC inventories.
  * Then by buying food from the market with its NPC coal account.

If the NPC cannot feed itself and hunger falls below the work threshold, it returns home and stops working.

Useful admin commands:

  /cgnpc needs <id>
  /cgnpc stock <id> BREAD 16
  /cgnpc funds <id> 25

===== Traders =====

Traders sell from their own inventory. Workers in the same zone can stock traders automatically up to the configured restock target.

Players haggle with:

  /cgnpc haggle <id> buy <material> <amount> <offer>

Admins can add starting goods or coal:

  /cgnpc stock <id> BREAD 64
  /cgnpc funds <id> 100

===== Configuration =====

Worker roles can be explicit or automatic. ''/cgnpc role <id> farmer'' sets a role directly. If no role is set, CoalGov tries to match the NPC name under ''npc.worker.roles''. For example, an NPC named ''Farmer Joe'' uses the ''farmer'' role.
Workers whose role or name does not match a configured role do nothing by default.

  npc:
    schedule:
      enabled: true
      rest_start_tick: 13000
      rest_end_tick: 23000
      work_arrival_distance: 4.0
    needs:
      enabled: true
      hunger_interval_minutes: 20
      eat_below_hunger: 14
      work_min_hunger: 6
      buy_food_from_market: true
      market_food_markup: 1.25
      default_food_preferences:
        - BREAD
        - BAKED_POTATO
        - APPLE
    worker:
      tick_interval_seconds: 20
      allow_default_production: false
      roles:
        farmer:
          behavior: FARM
          output_material: WHEAT
          output_amount: 4
          crops:
            - WHEAT
            - CARROTS
            - POTATOES
            - BEETROOTS
          replant: true
        baker:
          behavior: CRAFT
          output_material: BREAD
          output_amount: 2
          inputs:
            WHEAT: 3
      farm:
        action_distance: 3.0
        max_scan_blocks: 512
    supply_chain:
      max_transfer_per_tick: 64
      source_reserve: 16
      worker_output_reserve: 16
      traders_accept_outputs: true
      trader_restock_target: 256

Admins can seed inventories with:

  /cgnpc stock <id> <material> <amount>

and fund trader purchases with:

  /cgnpc funds <id> <amount>