Economy: the colony's trade, land and plunder

Decision #121. This is both the design (what the game is about and why) and the build spec for the first playable version on feat/economy. Numbers marked tuning are starting values, not promises.

1. The game in one paragraph

Felucca is the logistics of power. Ore, stone, timber, grain and hides come from different ends of the map (the atlas makes them scarce by region, #97), but every town needs all of them, because towns are built, repaired and destroyed. There are no portals: goods only move on foot, by cart or by ship, so a price gap between two towns is the cost of moving goods plus the risk of losing them on the road. Towns run their own markets as constant-product pools; the people who fund a town's market are its stakeholders, hold its land and lose with it when it is plundered. Aquais, the free port controlled by the mainland, mints all coin and burns the crown's share of every market fee. Bots are ordinary players (#3): writing a script that works your character while you are at work is a first-class way to play ("smart idle").

Loops:

Minutes: fight, chop, mine, fish, a leg of a road.
A session (1–2 h): a caravan run, a raid on a caravan or a vault, a hunt, a crafting batch.
A season (weeks): land, stakes, town votes, vulnerability windows, sieges (later).

2. Lore frame: a colony

Felucca is the land of the orcs (and older things); humans are colonists. Aquais is the colony's port, held directly by the mainland (the crown): it is the only peaceful place, it mints the colony's coin and it sells mainland goods. The two factions (Karrak Dominion, Aelwyn Concord) are not kingdoms sent from home but colonial blocs that grew out of greed and trade. This explains the cold start: colonists did not arrive empty-handed. The colonial company seeded every town's market with goods and coin (the genesis, §9), and every new colonist lands in Aquais with a purse and a kit.

3. Money: one mint, physical coin

Coin is an item (gold_coin) with weight. The target is that the median capital of an experienced player is about the most a strong character can carry on foot (tuning: 25 coins weigh 0.1 stone, so 100 000 coins ≈ 400 stones ≈ the backpack limit of a Str-100 character). Coin weight is set once before release from playtest data and then frozen. There are no bank cheques yet; city-backed cheques (§13) are a later step.
Only Aquais mints. Gold ore is mined (gold veins: Karrak and the isles), smelted into gold ingots and carried to Aquais, where the mint pays coins per ingot. Mobs never drop coin. This makes the emission of the future token auditable at one point.
Mint rate (tuning): coins_per_ingot = floor(MINT_BASE · MINT_HALF / (MINT_HALF + minted)), MINT_BASE 100, MINT_HALF 100 000 ingots, minted = ingots minted so far. The more has been minted, the less each ingot buys: a smooth halving known in advance.
Sinks: the crown's share of every pool fee, patents, mainland store purchases, corpses that rot with their items, the fence's cut, vault repairs, coins exported to the mainland.
Export: coins handed to the mainland in Aquais leave the world for good (they become the player's on Solana once the bridge exists, #87 keeps the ledger off for now). Hoarding outside the game is fine: that coin no longer works in the world.

4. Character upkeep: a colonist costs money

A character is bought (outside the game) and then has running costs:

Work patents (like a work permit): every gathering and crafting skill needs an active patent to be used (tuning: 200 coins per 30 days per skill, paid to the crown, burned; on sale at every town exchange and in Aquais). New colonists get 7-day patents for Mining, Lumberjacking, Fishing and Cooking.
Food: satiety 0–100 falls by 1 every 90 s online (tuning); eating restores it (bread +25, cooked fish +20, cooked meat +30). At 0 you are too hungry to gather or craft.
Tools wear out (a use costs 1 durability; pickaxe and hatchet 100, fishing pole 50) and break.
Clothes wearing out and shelter are later steps.

5. Gathering and crafting

Only base resources are gathered; everything else is made, in chains that will get deeper (GregTech-like) over time. Skill caps (#52: 700.0 total) force specialisation.

Skill	From	Gives	Tool	Bank / regen (tuning)
Lumberjacking	`tree_*` statics	logs	hatchet	10, +1 per 60 s
Mining	`ore_vein_*`	iron ore (gold ore from `ore_vein_gold`, needs 40.0)	pickaxe	15, +1 per 90 s
Mining	`quarry_*`, big rocks, boulders, outcrops	stone	pickaxe	10, +1 per 90 s
Fishing	water within 4 tiles	raw fish	fishing pole	8 per 8×8 area, +1 per 60 s
(hunting)	animal corpses	raw meat, hides	—	—

An attempt takes 2 s (fishing 3 s) and repeats until the bank is empty, the backpack is full, the player moves or gets another order. Success 0.5 + skill / 2000 (0.5 at 0, 1.0 at 100.0), minus a resource's difficulty; a gain of 0.1 has chance (1000 − skill) / 2000 while the lock is up and the total is under the cap.
Banks deplete: what is near a town is soon worked out, the frontier is richer. Bank state is part of the object's durable state.
Crafting needs a station nearby (forge, anvil, workbench, fire), a patent and sometimes a tool. Processing loses weight (2 ore of 12 stones → 1 ingot of 0.1 stone), so industry settles next to its heavy input: ore is smelted at the mine and ingots travel.

Recipes (append-only ids): boards, iron ingot, gold ingot (Mining 40.0), hatchet, pickaxe, fishing pole, smith's hammer, saw, cooked fish, cooked meat.

6. Towns, guard zones and markets

Every settlement of the baked world is a town with a guard zone (the box around its buildings and plots, grown by a few tiles) and an exchange (its bank's door, else its centre: the strongbox there is the vault). Inside a non-lawless guard zone, attacking an innocent player is refused (the town guard watches); grey players and animals are fair game. Towns of the isles and the wilds are lawless: no protection, and their exchange is a fence (§8).

All trade is done at the exchange (within 6 tiles of the vault), inside the guard zone; trade outside towns is free but there is no market there. (Direct player-to-player trade will be allowed only inside guard zones and taxed at the town's rate; not in the first build.)

Pools

Each town has one constant-product pool (x · y = k, Uniswap v2) per traded good, always against coin:

The fee is charged in coin on both sides (tuning: default 10 %, governance range 0–20 %). It is split: reserves (stays in the pool, which deepens with trade), treasury (the town's purse) and crown (burned in Aquais' name). Default 60 / 30 / 10 %, crown at least 10 %.
Slippage is the design: a caravan of 500 stones lowers the price where it unloads; the first caravan earns most and the next one is better off going elsewhere.
Trades count goods both ways: you buy or sell N units, and the quote says what they cost or bring, fee included (the pool's exact cost of N units, rounded in its favour). Each trade carries a limit — the most coin to pay, the least to receive — and fails rather than fill worse than the player agreed to (the client allows 2 % for prices moving meanwhile).
Liquidity: anyone can add coin and goods in the pool's ratio and receives shares; shares are redeemable for the pool's current reserves. Shares are the stake in the town.

Vault

Everything fungible a town holds — pool reserves, the treasury and players' deposits — is physically in one vault. Players may deposit and withdraw coin and goods (no interest). When the vault is plundered, the loss is spread pro rata over every claim on that item: pool reserves, the treasury, deposits. Taking one side of a pool moves its price; arbitrage then restores it at the stakeholders' expense.

7. Land and stake

A plot (from the town plans, #103/#111) is held by locking LP shares of that town's pools worth at least the town's plot_price in coin at the moment of the claim. While locked, the shares still earn fees and still lose in a plunder. Releasing the plot unlocks them.
The lock is counted in shares, not value, so later deposits never dilute a claim.
A plot gives the right to build and to run a business there. In this build the right is recorded and shown; commissioning a building from uo-buildings on the plot is the next step.

Governance: a small DAO

Stakeholders (weight = coin value of their shares at the proposal's creation, snapshotted) and the lord decide together:

actions: set the fee, set the split, pay coin from the treasury (repairs, building, a reward), elect the lord, set the plot price, set the vulnerability window, set the return reward;
a proposal runs 1 h (tuning), needs a quorum of 20 % of the weight and more yes than no; if the town has a lord, the lord must also vote yes (except on electing a lord);
the lord cannot take the treasury; the treasury is spent only by passed proposals.

Conquest and vassalage (the lord of one town swearing to another, tribute instead of razing, #77) are the next layer; the election is the placeholder.

8. Plunder, notoriety and the fence

The vault can be attacked only during the town's vulnerability window (tuning: 2 h a day, set by governance; server clock in UTC). Attacking it is a criminal act: the attacker is grey for 2 minutes.
A broken vault stays open for 5 minutes: anyone within reach may take goods up to what they can carry. Coin is heavy, so a raid is limited by bodies, pack animals and carts, and the loot must still be carried away by road.
Stolen goods are tainted with their town and a time. Whoever carries tainted goods is grey: anyone may attack them anywhere, even inside guard zones. Pools and vaults refuse tainted goods.
Killing a thief and taking the goods makes you the thief (the taint stays on the goods). Bringing them back to the town's exchange returns them to the vault pro rata, pays the returner the town's return reward (default 10 % of what came back) and marks them a hero for 30 minutes.
The taint wears off after 2 hours — the thief has to guard the loot outside the guard zones until then — or at once at a fence (the exchange of any lawless town), which keeps a quarter of every tainted stack. Simple and visible.
Grey players entering Aquais lose their tainted goods to the mainland's customs.
After the window the vault rebuilds itself, paid from the treasury.
Investigation: every town keeps a public log of what happened at its exchange and vault (who traded, deposited, withdrew, claimed, voted, broke, plundered, returned). A bot can record it; finding out who opened the gate is the players' job.

9. Genesis

At world start the colonial company (the crown) is the liquidity provider of every town pool. Each pool gets GENESIS_GOLD coin by town tier (tuning: village 2 000, fort 3 000, town 5 000, city 10 000, capital 20 000) and goods for a starting price base price × scarcity, where scarcity comes from how many matching resource nodes stand around the town (lots of quarries nearby: stone is cheap; none within the search radius: up to 50× dearer). The crown's shares are ordinary shares; it never trades them, so they are permanent depth (buying the company out is a possible later rule). New colonists start in Aquais with 1 000 coins, a pickaxe, a hatchet, a fishing pole and 5 bread (plus their class's weapon, as before).

10. Death: as in UO, full loot

On death everything the character carries and wears goes into a corpse on the spot; the character becomes a ghost with an empty backpack.
A ghost can walk and talk, nothing else, and cannot be seen fighting or be attacked. It is resurrected by reaching a healer: any town exchange, an ankh shrine, or Aquais.
Anyone may loot a corpse. Looting someone else's corpse is a criminal act (grey 2 min) unless the dead was grey or the corpse lies in a lawless zone. Tainted items stay tainted.
Corpses rot after 20 minutes, animal carcasses after 5, and what is left in them is gone.

11. Animals

Placeholder creatures drawn as capsules: deer (passive, flees; 2 meat, 1 hide), wolf (hostile, in packs; 1 meat, 1 hide), bear (hostile; 4 meat, 2 hides). Herds spawn deterministically per region on grass, forest, jungle and snow, never in a guard zone or the sanctuary, and respawn 2 minutes after dying.

12. Aquais

No land, no vault, no deposits. Aquais trades: it has a pool for every good, but they belong to the mainland alone — the crown puts their liquidity in at genesis (as deep as a capital's) and nobody adds to or withdraws from them, so investing in Aquais is impossible (it would be taking money out of the world). Its fee goes 60 % to the reserves and 40 % to the crown (no town treasury to feed). The exchange also offers: the mint (gold ingots → coins), the mainland store (fixed prices, the coin is burned: bread, pickaxe, hatchet, fishing pole, smith's hammer, saw), patents, and export to the mainland.

13. Later

City-backed cheques: paper money backed by one town's vault, worthless if that vault is emptied (a bank run as gameplay).
Direct trade inside guard zones at the town's fee; outside guard zones, smuggling.
Commissioning buildings on plots (uo-buildings), repair with materials, upkeep.
Conquest, vassalage, tribute; sieges as planned events.
Coloured ores, rare woods, reagents and gems from the atlas deposits (resource-items).
Pack animals and carts (carrying capacity beyond the backpack).
Crown contracts as a second, still-central coin faucet if PvE income proves too thin.
The economic report (money supply, mint, burn, prices per region) published monthly.
Open: how the mint rate behaves when the token's outside price swings (bots flock to gold veins when the token is dear); check in an agent simulation before the token.

14. Precedents and risks

What we borrow and what killed the others:

UO: recall and bank cheques erased geography and coin weight; land ran out (we hold land by stake, and plunder recycles it).
EVE: distance and destruction make a real economy, but everything flows to one hub (Jita) and NPC bounties are the faucet. Aquais is the one hub on purpose, but it has no pools.
Albion: local markets and no teleporting goods work; players crowdsource prices (so does our API: prices are public).
ArcheAge: trade packs with falling prices per delivery are the best caravan game so far; bots and pay-to-win spoiled it.
DeFi Kingdoms, Axie: AMM pools for game resources; they died of token emissions, not of the curve. Our emission is physical and has one source.
Eternum: AMM + physical transport + raids on stores; short seasons, few players, many bots.
Shadowbane, Rust: total loss and offline raids drive players away: windows, pro-rata losses and (later) vassalage instead of deletion.

Main risks: population density versus a 16k map; bots out-trading people (accepted: smart idle); the token's demand from outside; the 10 % fee pushing deep chains into single guilds.

15. Build spec (feat/economy)

Shared code

uo-proto::items: new resources (stone, gold ore, gold ingot, gold coin, raw/cooked fish, raw/cooked meat, hide, bread), tools (fishing pole, smith's hammer, saw), item weights per n units (ItemDef::per), recipes with skill, minimum skill, station, tool and time.
uo-proto::character: ItemProps.stolen (taint).
uo-proto::economy: the pure rules shared by server, client and SDK — pool (constant product, fee in coin, liquidity), market (a town's pools, treasury, deposits, plots, vault, plunder and restore pro rata, log, views), govern (proposals, snapshot weights, tally), citizen (patents, satiety, notoriety timers, ghost), work (resource nodes from sprite names, banks, success and gain, stations), mint (rate, mainland store offers, genesis prices).
uo-world::towns: the town registry from the baked world (or synthetic towns for generated test worlds): id, name, tier, polity, lawless, free port, guard zone, exchange, plots, owning region.
uo-proto::msg: protocol v3 — the economy commands, ReplyData::{Market, Container}, private GameEvent::Sheet, EntityKind::Creature, notoriety and ghost on players.

Server (`uo-server`)

Each town's state is owned by the region of its exchange (the exchange is moved at least 24 tiles inside its region so a trader is always simulated there). New store table towns (fenced last-write-wins like objects); an economy operation saves the town and the player in the same dispatch.
sim/economy.rs: market commands, vault and plunder, taint sweep and confiscation, guard zone rule, governance tick, Aquais services, the Sheet push.
sim/work.rs: harvest and craft tasks, eating, satiety, patents, tool wear, skill gain.
sim/death.rs: corpses, ghosts, resurrection, looting, decay.
Animals: uo-world content (herds), uo-combat archetypes Beast and Prey, loot.

Client (`uo-client`)

ui_kit.rs: one window toolkit (frame with title and close, text, rows, buttons, tables, amount steppers) in the #59 style; the three private copies are folded into it.
Windows: inventory (backpack tree, weight bar, satiety, patents, notoriety), market (pools with price, depth, quotes from the shared pool math; buy/sell; liquidity; vault deposits; plots; proposals and votes; log), crafting (recipes at the station), loot (corpse), Aquais (mint, store, patents, export).
World: clicking a resource node harvests, clicking water fishes, clicking the vault opens the market (Ctrl+click attacks an object); creatures as toon capsules; ghosts translucent; corpses as objects; grey and hero names.

SDK and bots (`uo-sdk`, `uo-loadtest`)

View keeps the sheet, citizen state and market views.
Behaviours: miner, lumberjack, fisher, hunter (gather or hunt, sell at the nearest exchange, eat, renew patents), hauler (buy where cheap, carry, sell where dear), raider (attack a vault in its window, plunder, run to a fence).
uo-server/tests/economy.rs: the whole loop against a cluster in one process.

Assets

corpse (a body lying on the ground, 4 variants) — ordered from the asset pipeline.
Creatures are capsules until creature models exist.

16. Built (first version)

What feat/economy actually does, where it differs from the spec above and what is known to be missing.

Server

Town state lives in a towns store table (memory store and ScyllaDB), one MessagePack blob per town (its Market, and for Aquais the mint's books), last write wins by a fence of the owning region's lease epoch. A region loads its towns on activation (or makes them from towns::genesis), saves changed ones within a second, and saves the town and the trader in the same dispatch after every trade; drain and retire save every town first.
The vault is a runtime obstacle (sprite strongbox, key key(region, SPAWNED_BIT | 1 << 22 | town)) next to each exchange but Aquais'. Outside the window attacks on it are refused with the hours; UO_RAID_WINDOW=always keeps every window open for testing. Broken: an ObjectUpdate with broken: true; rebuilt: the same key comes back whole. A neighbouring region doesn't see a vault in its border margin.
Rules added while building: while a vault stands broken the town's market is shut (no swaps, deposits, withdrawals, liquidity or plot changes); a vault dented but not broken is mended for free when the window closes; the mainland store sells 1–100 at a time; a return reward too heavy to carry waits in the returner's vault deposit; returning loot you plundered yourself earns no reward and no hero's mark (markets remember plunderers while their goods can still be marked), otherwise a raid followed by a return was a sure 10 % profit; raiders can't carry off the last 10 % of each pool's reserves (PLUNDER_FLOOR), so an emptied vault never leaves a pool without coin or goods; a ghost can be raised only 30 s after dying and not at an exchange whose vault stands open (found by the bots: a raider killed at the vault stood up beside it and plundered again).
Colonists land with the starter patents counted from their real landing time, 1 000 coins and the kit; characters from older records get a citizen without the kit; hunger doesn't run while offline.
Work: an attempt sends a private GameEvent::Worked; tool wear is ItemProps.uses; banks live in memory per region (lost on migration or failover, they simply refill). Any move or other order ends a task, including swinging back at an attacker.
Death: everything carried and worn (but the backpack) goes into a corpse object; the player is a ghost (0 hits, not flagged dead, walks and talks only, untargetable, ignored by AI) and stands up with 25 % hits within EXCHANGE_RANGE of any exchange or 2 tiles of an ankh or virtue shrine. Loot range 2 tiles. Corpses live in memory: a migration or failover loses them and their items. A rotting corpse is sent as broken: true (the client makes it vanish).
Animals (per region content, ids above the camp keys, 16+ tiles from camps and 8+ from guard zones, never in the sanctuary):

Species	Hits	Attack	Archetype	Herd	Carcass
Deer	30	—	Prey: grazes within 3 tiles of home, flees enemies within 6	2–4	2 meat, 1 hide
Wolf	45	bite 4–10, 5 AP	Beast: melee, never breaks through	2–4	1 meat, 1 hide
Bear	90	claws 8–20, 8 AP	Beast	1–2	4 meat, 2 hides

Snow: wolves or bears; forest: deer, wolves or bears; jungle: deer, bears or wolves; grass: deer or wolves. A fleeing deer runs as fast as a walking hunter: deer are bow game.

Bots

uo-sdk bots for smart idle (--mix names in uo-loadtest): miner, lumberjack, fisher, hunter (gather or hunt, sell at the nearest exchange, eat, renew patents), hauler (buys where a visited market is cheap, sells where it is dear, minding slippage and its load), raider (breaks a vault in its window, plunders, runs for a fence) and guard (kills grey players, loots them and returns the goods for the reward). crates/uo-server/tests/economy.rs plays the loop end to end (a miner selling, a hauler's arbitrage, a raid and its return); a 50-bot swarm ran for 90 s with no server errors (tick p99 6 ms in a debug build). A full vault takes 200–600 blows: a raid needs a party or kegs.

Known gaps

On generated (test) worlds new characters still spawn by name hash, not in the synthetic free port (the load tests rely on players spreading over the map); on the baked world everyone lands in Aquais.
Corpses and resource banks are not durable (above).
Synthetic towns on generated maps start at nearly the same prices; on the baked world prices differ by the atlas' deposits.