Add newer CoalGov update

coalgov-wiki-pages/admin.txt

@@ -76,6 +76,12 @@ Admins can grant a divining rod for testing:
 
   /coalgov admin rod
 
+Admins can grant centralized utility items and synthetic mobs:
+
+  /coalgov admin furnace
+  /coalgov admin mob wandering_trader [count]
+  /coalgov admin mob trader_llama [count]
+
 ===== Admin Bypass Mode =====
 
 Admins normally play under the same build, marker, and mining restrictions as citizens.
@@ -98,6 +104,45 @@ After editing market config, run:
 
 Existing market stock is stored in SQLite and is not reset by reload.
 
+===== NPC Household Setup =====
+
+Create the NPC and then set its home, work site, and role:
+
+  /cgnpc create worker Farmer farm
+  /cgnpc home <id>
+  /cgnpc work <id>
+  /cgnpc role <id> farmer
+  /cgnpc needs <id>
+
+Homes and work sites use the admin's current location. Workers return home at rest time or when hunger is too low. During work hours they move toward the work location and perform the role configured under ''npc.worker.roles''.
+
+NPCs need food if ''npc.needs.enabled'' is true. Seed worker inventories or fund accounts as needed:
+
+  /cgnpc stock <id> BREAD 16
+  /cgnpc funds <id> 25
+
+If an NPC has no food in inventory, it can request food from same-zone NPCs or buy configured food from the market using its own account.
+
+===== Super Furnaces and Synthetic Diamonds =====
+
+On this server the CoalGov Super Furnace recipe is disabled so the Ministry can control synthetic diamond production. Admins grant furnaces with:
+
+  /coalgov admin furnace
+
+When enabled in config, Super Furnaces can convert 40 COAL input into 1 DIAMOND.
+
+===== Lottery =====
+
+Players can buy tickets with:
+
+  /coal lottery buy [tickets]
+
+Admins draw with:
+
+  /coal lottery draw
+
+The house edge is enforced in code. The payout defaults to 90%, is capped at 95%, and always leaves at least 1 Coal Cent for the treasury if tickets were sold.
+
 ===== Reloading Config =====
 
 After editing plugins/CoalGov/config.yml, run:

coalgov-wiki-pages/commands.txt

@@ -6,8 +6,12 @@
   * /coal deposit - deposit all coal items and coal blocks from inventory.
   * /coal withdraw <amount> - withdraw a whole-coal amount into coal items.
   * /coal pay <player> <amount> - pay another online player; accepts decimal coal or cc.
+  * /coal networth - estimate your balance, appraised inventory, and claim purchase value.
   * /coal fines - list unpaid fines.
   * /coal fines pay <id|all> - pay one fine or all unpaid fines.
+  * /coal lottery status - show the current lottery round.
+  * /coal lottery buy [tickets] - buy one or more lottery tickets.
+  * /coal lottery draw - admin-only lottery draw.
 
 ===== Market =====
 
@@ -39,7 +43,13 @@ Right-click the rod to test nearby ground for ore signals below and around you.
 
 ===== Super Furnace =====
 
-Craft a CoalGov Super Furnace with a furnace in the center and stone in the eight surrounding slots. It smelts 5x as fast and burns fuel 4x faster.
+CoalGov Super Furnaces smelt 5x as fast and burn fuel 4x faster. Crafting is disabled on this server so the Ministry can keep synthetic diamonds centralized.
+
+Admins can grant a Super Furnace with:
+
+  * /coalgov admin furnace
+
+When synthetic diamonds are enabled, a Super Furnace can convert 40 COAL input into 1 DIAMOND.
 
 ===== Land =====
 
@@ -56,6 +66,8 @@ Craft a CoalGov Super Furnace with a furnace in the center and stone in the eigh
   * /coalgov admin reload - reload config.yml.
   * /coalgov admin bypass <on|off|status> - toggle admin gameplay bypass for yourself.
   * /coalgov admin rod - grant yourself a divining rod for testing.
+  * /coalgov admin furnace - grant yourself a CoalGov Super Furnace.
+  * /coalgov admin mob <wandering_trader|trader_llama> [count] - spawn controlled synthetic trader mobs.
   * /coalgov admin treasury balance - show treasury balance.
   * /coalgov admin treasury grant <player> <amount> - grant coal from the treasury.
   * /coalgov admin tax exempt <player> <on|off|status> - manage transaction tax exemption.
@@ -70,7 +82,11 @@ Craft a CoalGov Super Furnace with a furnace in the center and stone in the eigh
   * /cgnpc create <trader|worker> <name> <zone> - create a Citizens-backed CoalGov NPC.
   * /cgnpc stock <id> <material> <amount> - add inventory to an NPC.
   * /cgnpc funds <id> <amount> - add coal or Coal Cents to an NPC account.
+  * /cgnpc role <id> <role> - set an explicit configured worker role.
+  * /cgnpc home <id> - set an NPC home to your current location.
+  * /cgnpc work <id> - set an NPC work location to your current location.
+  * /cgnpc needs <id> - inspect NPC hunger, role, home, and work locations.
   * /cgnpc haggle <id> <buy|sell> <material> <amount> <offer> - negotiate with a trader.
   * /cgnpc list - list NPC zones and CoalGov NPCs.
 
-Worker roles are matched from the NPC name. By default, a worker named ''Farmer'' harvests and replants mature crops in its zone, a worker named ''Baker'' consumes wheat to produce bread, and workers move surplus output to traders in the same NPC zone.
+Worker roles can be set with ''/cgnpc role'' or matched from the NPC name. By default, a ''farmer'' harvests and replants mature crops, a ''baker'' consumes wheat to produce bread, and workers move surplus output to traders in the same NPC zone.

coalgov-wiki-pages/economy.txt

@@ -14,6 +14,12 @@ CoalGov uses Coal Cents for sub-coal transactions. Balances are stored as intege
 
 Each player has one balance stored by UUID in SQLite. A player row is created automatically when they join the server.
 
+Players can estimate their CoalGov wealth with:
+
+  /coal networth
+
+The estimate includes current balance, configured market value for appraised inventory items, and claim purchase value. It is an estimate, not a guaranteed sale price.
+
 ===== Deposits =====
 
 Players run:
@@ -58,13 +64,29 @@ The market lets players sell configured resources for coal or Coal Cents and buy
 
 Market purchases and sales can charge a configured government tax. Tax-exempt players do not pay transaction tax.
 
+Same-day buyback protection records recent market purchases. If a player sells the same material back within the configured window, those protected units are paid back at the recorded purchase unit price instead of the current dynamic sell price.
+
+===== Lottery =====
+
+Players can buy lottery tickets with coal:
+
+  /coal lottery status
+  /coal lottery buy
+  /coal lottery buy <tickets>
+
+Admins draw the current round with:
+
+  /coal lottery draw
+
+The lottery has a built-in house edge. The configured payout defaults to 90%, is capped in code at 95%, and always leaves at least 1 Coal Cent for the treasury when tickets were sold.
+
 ===== Treasury =====
 
 The treasury receives market transaction tax and paid fines. Admins can inspect the treasury and issue treasury-funded grants.
 
 ===== NPC Economic Agents =====
 
-CoalGov NPCs have their own coal accounts and inventory. Trader NPCs buy and sell from their own stock and balance. Worker NPCs move inside an assigned polygon zone and periodically produce configured goods into their own inventory.
+CoalGov NPCs have their own coal accounts and inventory. Trader NPCs buy and sell from their own stock and balance. Worker NPCs move between home and work, consume food, buy food if funded, request supplies from same-zone NPCs, and periodically produce configured goods into their own inventory. Hungry workers stop working and return home until fed.
 
 ===== Transactions =====
 

coalgov-wiki-pages/market.txt

@@ -39,6 +39,23 @@ When a player sells a full inventory, the whole batch does not receive the first
 
 Food items start with Ministry stock 0 by default, so players must sell food into the market before anyone can buy it back out.
 
+===== Buyback Protection =====
+
+CoalGov records protected buyback lots when a player buys resources from the Ministry. If that same player sells the same material within the configured protection window, protected units are paid at the recorded buy unit price instead of the current dynamic sell price.
+
+This is meant to reduce accidental buy/sell losses from misclicks or short-term mistake purchases. After the protection window expires, normal dynamic sell pricing applies.
+
+Default config:
+
+  market:
+    buyback_protection:
+      enabled: true
+      duration_hours: 24
+
+===== NPC Food Demand =====
+
+NPC workers can buy configured foods from the market with their own NPC coal account when they cannot feed themselves from NPC inventory or same-zone supply chains. This creates a small simulated food demand for stocked market goods and gives farms/bakers a reason to keep NPC supply chains moving.
+
 ===== Default Dynamic Settings =====
 
   market:

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

coalgov-wiki-pages/testing.txt

@@ -9,9 +9,14 @@ Use this checklist after install or upgrade.
   * /coal deposit removes coal from inventory and increases balance.
   * /coal withdraw decreases balance and gives coal items.
   * /coal pay transfers balance.
+  * /coal networth reports balance, inventory estimate, and claims estimate.
+  * /coal lottery buy 1 charges a ticket.
+  * /coal lottery status shows the active round and pot.
+  * /coal lottery draw pays a winner and leaves a treasury edge.
   * /market opens the Ministry Exchange inventory menu.
   * Selling resources through /market increases balance and market stock.
   * Buying resources through /market decreases balance and market stock.
+  * Selling a recently bought material uses buyback protection during the configured window.
   * Market prices change after stock changes.
   * /land create creates a region.
   * /land info reports current land class.
@@ -35,3 +40,10 @@ Use this checklist after install or upgrade.
   * /coalgov admin bypass on bypasses mining, build, and marker restrictions for that admin.
   * /coalgov admin bypass off restores normal gameplay restrictions for that admin.
   * /coalgov admin spawn setup creates protected spawn guide signs.
+  * /coalgov admin furnace grants a Super Furnace.
+  * Super Furnace synthetic diamond conversion works when enabled.
+  * Named entities drop a recovered name tag on death.
+  * /cgnpc role, /cgnpc home, /cgnpc work, and /cgnpc needs work for an NPC.
+  * Worker NPCs return home during rest hours.
+  * Worker NPCs travel toward work during work hours.
+  * Worker NPCs consume configured food and stop working if hunger is too low.