Add newer CoalGov update

coalgov-wiki-pages/npcs.txt

@@ -1,4 +1,4 @@
-====== NPC Supply Chains ======
+====== NPC Workers, Traders, and Households ======
 
 CoalGov NPCs use Citizens. They are server-side entities, so players do not need client mods.
 
@@ -8,11 +8,13 @@ NPCs are managed with:
 
 ===== NPC Types =====
 
-  * Trader - stores goods, has a coal account, and can haggle with players.
-  * Worker - patrols an assigned NPC zone and performs configured labor.
+  * 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:
@@ -25,6 +27,15 @@ 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:
@@ -37,12 +48,23 @@ Create workers and a trader in that zone:
   /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.
 
@@ -66,6 +88,32 @@ 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.
@@ -81,10 +129,26 @@ Admins can add starting goods or coal:
 
 ===== Configuration =====
 
-Worker roles are matched by NPC name under ''npc.worker.roles''. For example, an NPC named ''Farmer Joe'' uses the ''farmer'' role.
-Workers whose names do not match a configured role do nothing by default.
+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