Mining → trading → construction → modules — design capture

Captured 2026-07-10. The economy spine; precedes the fleet design (docs/design-fleet.md) which consumes it. Not yet scheduled.

System spine: hulls carry faction identity, neutral hardpoints receive modular weapons, and default loadouts are content choices rather than inseparable guns. Read the visual combat system spine first. This document owns acquisition, fabrication, and shop distribution; modular weapons owns hardpoint/art mapping, while munitions owns ammunition and rearm rules.

Minerals (tiered ladder)

Tier	Mineral	Source	Used for
T1	Ferrite	everywhere	hulls, structure, bulk
T2	Silica	common, belt-specific	electronics
T2	Ice	cold outer belts only	volatiles/fuel
T3	Titanium	frontier systems	engines, armor
T4	Iridium	rare belts	weapons, high-tech
T5	Voidite	ONLY near black holes (Veil)	fold tech, exotics

Distribution

Each belt: one dominant mineral (~80%) + optional trace (~20%), declared in the belt’s JSON (extends OrbitDef).
Single-type belts keep routing legible (“the titanium belt in Karda”); the trace keeps every belt worth prospecting.
No literal inter-system belts (systems are separate scenes); the same flavor comes from paired belts on both sides of a starlane carrying each other’s trace mineral.

Danger = richness

Systems get a danger tier scaling pirate spawn pressure AND mineral richness/variety. Existing systems already ladder:

Eos — safe: Ferrite/Silica
Karda — frontier: Titanium (pirates already lurk in that belt)
Veil — deadly: Voidite at the black hole; the endgame mine

Chain

mine ore → sell raw at stations (trading gives ore worth) → refine at stations (refinery) → components → construct modules. Hauling (fleet design) moves every link. MVP order: mineable asteroids + ore cargo + raw selling first; refine/construct after.

Contested supply chains (owner spec, 2026-07-11)

Danger=richness is not just spawn pressure — it is GEOGRAPHY that forces hauling. The high-tier minerals can ONLY be mined where it is dangerous, and the refinery that turns them into anything can ONLY sit somewhere else. Raw ore has to survive the trip between them.

Mine and refinery are deliberately separated. A tier’s ore is mineable only in its hostile belt; no refinery exists in that system (or the local one only takes lower tiers). The refined-goods value lives one or more danger-crossings away — a starlane run through pirate space with a hold full of unrefined, unsellable-at-full-value ore.
Raw ore is the vulnerable form. Unrefined ore is bulky, low-value if dumped locally, and lost with the hull — so the risk rides on the hauler, not on a wallet. Refining “banks” the value; until then it is cargo a pirate can take.
This is the core risk loop, not a side quest: Voidite (Veil, at the black hole) already is the extreme case — mine in the deadliest system, haul it out to refine. Generalize it down the ladder so Titanium (Karda frontier) wants a run back to Eos, etc. Belt richness, refinery placement, and pirate pressure are the three knobs, set per system in content, not hardcoded.
Escort/haul fleet roles exist because of this (docs/design-fleet.md): the answer to a dangerous haul is a hauler + fighter escort, or a fast solo run — a real loadout choice, not a formality.

Already in-engine (2026-07-11 audit)

Combat and the mining/salvage TOOLS are built; the economy they feed is not. Beam/cannon/missile weapon templates ship; nairan_mining_beam and nautolan_salvage_array exist as utility “weapons” with nothing to point at yet. Belts render in every system but carry NO mineral data. The dock screen has a stubbed “OUTFITTING” shop slot. So the foundation slice is data + loop (mineral defs, cargo hold, mineable rocks, ore items, station prices), not new combat.

Ship modules

Categories: Weapons, Engines, Ship tweaks (shields, cargo expanders, capacitors, …). Modules are constructed from minerals, found as loot/wreck salvage, or bought.

Constructed modules explicitly include weapons. Fabrication outputs reusable modular items, never guns unique to one hull: the same WeaponTemplate may arrive built into a ship or through a ModuleCategory.Weapon wrapper. The Arena is the current retrofit/loadout laboratory before the outfitting shop opens; it exercises the same module items the economy will later fabricate, salvage, and sell.

Tetris inventory (Backpack Battles style)

Every ship has a grid inventory; grid size scales with ShipSize (roughly xs 4x3, s 5x4, m 6x5, l 8x6, xl 10x7 — tune).
Modules occupy shapes (cell lists). Rarity affects stats AND shape/size — the same stats in a friendlier shape is a drop-excitement axis of its own (compact 1x2 rare vs clunky L common).
Later: adjacency synergies (module touching module matters — capacitor beside engine, ammo beside cannon). This is the long-term build-crafting depth.
MVP: every module is 1x1 in a working grid (render, drag-drop, equip effects). The data model stores shape-as-cell-list from day one, so shapes/rarity-shapes/adjacency are content and UI polish, not a refactor.

Trade data access (owner spec, 2026-07-10)

Station stock/prices seed from JSON (each station: mineral -> {stock, price}; prices skew by system danger + local supply). The PLAYER’s view of remote market data is gated by their trade interface:

Lore: one commercial entity owns all trade software; subscription tiers unlock market data from further away — pay more, see further.
Tiers: base = current station only; upgrades extend range (system -> adjacent systems -> galaxy).
Pirated variants: show only certain materials but with looser/no range limits — cheaper/free, incomplete, maybe reputation risk with militia/civilians if detected. A real early-game choice: legal narrow-and-complete vs pirated wide-and-patchy.
Trade UI lives in the dock screen’s stubbed shop slot first; a map overlay (prices on the galaxy chart) once range tiers exist.

One distance model — reuse the autopilot’s, don’t invent a second (2026-07-11)

Interstellar trade (range tiers, price-by-distance, “further = pricier / foggier”) measures distance with the SAME primitives the autopilot and the chart already use — there is no separate trade distance calculator:

Lane hops = range and reachability. features/player/LaneRoute.cs (BFS over the usable-lane graph) already answers “how many jumps to system X, and is it reachable at all”. The subscription range tiers ARE lane-hop counts: base = this station, tier 2 = 1 hop (adjacent systems), tier 3 = N hops / whole reachable graph. A fold-only system (no lane route) is “off the network” for legal trade data — a natural reason its goods are exotic/valuable. Pirated feeds ignore the hop cap.
World distance = price magnitude. Straight-line galaxy distance (GalaxyScale / StarSystemDef.WorldPosition, the same numbers the chart and lane-flight profile use) scales how much a price skews with remoteness, on top of the danger and local-supply skews.
The contested-supply-chain risk rides the SAME route. The lane path the autopilot flies with a hold full of ore is exactly the path a trade tier “sees” prices along and a hauler fleet role plans over — one graph, one set of hops, so mine → haul → refine → sell all speak the same geometry.

Dependency order (merged with fleet doc)

Mineable asteroids (belt JSON: dominant/trace) + ore items + cargo hold
Trading: prices per station, buy/sell UI in the dock screen (shop slot already stubbed), price differentials per system danger
Grid inventory MVP (1x1 modules; weapons/engines/tweaks as equipables)
Refining/construction at stations
Wrecks + salvage (feeds fleet design salvagers + pixel destruction)
Player-owned stations (buildable platforms — docs/design-stations.md): the delivery-hold platform the hauler/trader roles buy and sell against
Then: fleet roles consume all of it (docs/design-fleet.md)

MVP BUILD PLAN — mine/salvage → haul → sell (owner spec, 2026-07-11)

The concrete first economy milestone. Deliberately SHALLOW breadth: two gather verbs, two commodity tiers each, one sell verb. Depth (the T1–T5 ladder, refining, modules, trade tiers above) comes AFTER this loop is fun.

Commodity model — everything sells the same way

One Commodity type (id, name, category, baseWorth). Cargo is a hold on the ship (capacity in units; add/remove; lost with the hull — the risk). Selling is sum(baseWorth × qty) × stationPriceSkew. MVP commodities: - Ferrite (mineral, common) — the belt baseline. - Gem (mineral, RARE) — a rarity proc rides ON TOP of a normal mine, it does not replace it: a normal success yields Ferrite; a rare proc yields Ferrite + Gem (owner call — additive, not either/or). - Generic Salvage (salvage, common) — from derelict hulls. - Ancient/Exotic Salvage (salvage, RARE) — the salvage rarity proc. All four just carry a baseWorth and sell like any other — perfecting what each ACTUALLY is (specific alloys, named artifacts) is deferred.

The gather verbs reuse the utility tools that already exist

weapon.nairan_mining_beam and weapon.nautolan_salvage_array are already utility mounts (damage 0, brains never fire them). Give them a real effect: aim at a node, hold the trigger, a progress fills, and cargo gains the node’s commodity — plus a rareChance roll for the bonus rare unit. Nodes deplete.

Content

Belts gain a dominant mineral + rareChance (Ferrite belts everywhere, the Karda/frontier belts richer). Belt rocks OR dedicated ore nodes are the mine targets.
Eos ancient ship graveyard: a field of derelict hulls (a new orbit feature / scatter of wreck nodes) — the common salvage ground, safe and close so salvage is the tutorial gather verb.

Neutral “Independent” economy faction (owner spec)

Add faction.independent — prospectors and salvagers, standings ~0 with EVERYONE (nobody shoots them, they shoot nobody), flying the independent / unarmed utility loadout. It exists so the economy has ambient ACTORS: - A salvage station in Eos by the graveyard (independent faction) that spawns salvage drones / small salvage ships working the wrecks. - A mining outpost by a belt (independent faction) that spawns mining drones working the rocks. These demonstrate the loop before the player does it and give the world texture. They reuse the escort/drone leash (drones on a short leash around their station-carrier — see docs/design-fleet.md escort primitive) plus the gather-verb effect. Selling at their own station closes their loop off-screen.

Phased tasks

E0 Cargo + commodities: Commodity model + JSON, cargo hold on Ship, the four MVP commodities. No gathering yet — just the containers + worth.
E1 Mining: mineable belt/ore nodes (dominant mineral + rareChance), mining beam gather effect (hold-to-fill, deplete, rare proc adds Gem), cargo fills. HUD cargo/progress readout.
E2 Salvage + graveyard: Eos graveyard content (derelict nodes), salvage array gather effect (Generic + rare Exotic proc), nodes deplete.
E3 Sell: station trading — dock → sell cargo for credits (baseWorth × danger/supply skew), dock-screen shop slot UI, wallet gain.
E4 Independent faction + actors: faction.independent (neutral all), salvage station + drones by the graveyard, mining outpost + drones by a belt. (Depends on the escort/drone primitive — build that first or stub the drones as simple gather-loopers.)

MVP done = the player can fly to a belt, mine Ferrite (sometimes a Gem), fly to the Eos graveyard, salvage, haul it to a station, and sell it for credits — through the hostile ground the combat sandbox now provides. Everything past that (rarity ladder, refining, modules, trade tiers, hauler/trader fleet roles) is the existing dependency order above, layered on once this is fun.

Fold Crystal economy (captured 2026-07-12)

Fold Crystals are the fold drive’s fuel (docs/design-bible.md, docs/story-outline.md: one crystal per jump, prime-core only). This is a separate resource lane from the mineral ladder above — deliberately not just “Voidite but rarer” — because no living faction can manufacture them. They are pre-Collapse human artifacts. Humanity is extinct. The supply that exists today is everything that will ever exist until the player invents a way to make more.

Why no market sells them

Every other commodity in this doc has a station that stocks it, because some faction still produces it. Fold Crystals fail that test: the Verid trade in information, not materials (assets/codex/faction-verid.md); no other successor species reverse-engineered fold tech (that’s the whole point of the fold signature being a surprise). So:

No station price. Fold Crystals never appear on a dock shop-slot market screen, at any trade-tier (docs/design-economy.md “Trade data access” above). There is no stationPriceSkew for an item nobody stocks.
Value is expressed narratively, not numerically. A crystal’s “price” is a quest gate, a faction’s asking favor, or the risk of the run to go get one — not a credit figure a wallet can just absorb. Where a hard number is unavoidable (e.g. a black-market vendor barters one for a quest item), price it as an outlier 10-100x the T5 Voidite baseline, and treat that vendor as a one-off, not a template for a shop type.

Rarity: found vs. synthesized

Two tiers, matching the two eras of the story (Act I/II scarcity vs. Act III capability):

Found (default, whole game). Loot-only. Scattered in human ruins — derelict hulls, sealed vaults, black-hole research posts — as a discrete pickup, not a gather-verb yield. Mechanically this rides the Ancient/Exotic Salvage rarity proc already scoped for Econ E2 (docs/design-economy.md “Commodity model” above): an Exotic Salvage node has a small additional chance to drop a Fold Crystal instead of (not in addition to — these are too precious for “sometimes both”) the usual exotic unit. No new gather system needed; this is a table entry on a system that already exists. The Veil vault (docs/story-outline.md) is the seeded, guaranteed cache that starts the run; every crystal after that is this proc, elsewhere in human ruins.
Synthesized (Act III unlock, endgame only). A blueprint/research gate — found late, likely tied to the fold-enabled AI core prototype site or a Verid trade — unlocks a refinery recipe that turns refined Voidite (T5, “fold tech, exotics” — already the ladder’s endpoint) into a crystal at a steep ratio (many Voidite units per crystal) and gated by a scarce catalyst component, not a straight sell-buy loop. This is what makes late-game folding sustainable instead of a hard stop when the found stockpile runs dry, while keeping every crystal spent before the unlock a real, unrecoverable choice.

Locations

Veil — the vault (guaranteed start cache) and the only system with a Voidite belt, so it’s both the origin point and, post-synthesis-unlock, the only place to make more.
Human ruins, galaxy-wide — derelict hulls and sealed sites flagged as Exotic Salvage grounds (Eos graveyard is the first, tutorial-tier instance of this site type; more get scattered as systems are built out) carry the found-crystal proc. Danger-tier of the ruin should track the danger=richness rule above — a crystal find in a safe system undercuts the tension the whole mineral ladder is built on.
Nowhere on a market screen, by design (see above).

Trade value

Not a number in a price table — a design constraint: every crystal spent is a jump the player chose over a jump they didn’t, and every crystal found is a moment worth writing up, not a commodity tick. Keep it that way until the synthesis unlock is live; only then does “cost to make one” become a real, quotable number (Voidite ratio + catalyst rarity), and even

Verid data trade (captured 2026-07-12)

The Verid (assets/codex/faction-verid.md) “trade exclusively in information … and never reveal what they know without extracting something of equal weight.” That’s a barter table, not a shop-slot — it has to stay outside every mechanism the “Trade data access” system above already owns, the same way Fold Crystals stay off the market screen (previous section), or the faction’s whole point collapses into “NPC with a price list.”

No credit price, at any subscription tier. Verid intel never appears as a line item on the dock shop-slot market, and no trade-tier upgrade (system -> adjacent -> galaxy range, above) ever surfaces it — credits cannot buy it, full stop. This is the load-bearing distinction between the generic market-data system (what’s for sale, how far you can see it) and a Verid encounter (whether they’ll deal with you at all).
Barter, not currency. A trade opens only via player-initiated hail on a present Verid contact (docs/design-universe.md §7). The offer table is keyed to items/flags the player already holds that are provably costly to have gotten — a Fold Crystal, a specific discovered location/ruin flag, a story-critical artifact — never credits, never a generic commodity. Each entry consumes the offered item/flag and unlocks exactly one thing in return: a codex reveal, a story-flag advance, or (rare, one-off, never repeatable) a permanent stat grant — mirroring the Fold Crystal rule that irreplaceable trades don’t get a shop UI, they get a dialogue choice.
CASSIUS’s hail window is the UI, not a new one. Reuse the existing radar-contact -> comms interaction (tutorial-script.md’s HAIL prompt) for the Verid barter dialogue. A Verid offer table is dialogue-tree content, not a new trade screen — the point is the conversation feels like extracting a favour from someone who holds all the leverage, not like browsing a store.
Declining is always safe; low-balling is not guaranteed safe. The Verid disengage without penalty if the player has nothing to offer or walks away. What they do if a player tries to lowball or repeat-farm a one-off trade is intentionally left as a story/DM lever (reputation hit, refusal to ever trade again, or — per docs/design-universe.md §7 — reclassifying the contact as provoked) rather than a fixed rule; the faction’s whole identity is that its terms are opaque. then it belongs in a refinery recipe, not a station’s buy/sell columns.

Economy testbed (accelerated sim, 2026-07-17)

Before hauler/trader roles land, pricing/mining/salvage behavior is easier to tune against a dedicated sandbox than against the shipping universe. The testbed is a separate four-system constellation authored purely for economy observation, loaded only in a debug sim mode — never in a normal launch.

The constellation (features/universe/data/testbed/, ids system.sim_*): a ring of sim_hub (Safe) → sim_reach (Frontier) → sim_deep (Deadly) → sim_edge (Frontier) → back to sim_hub, all lanes reciprocal. Each system carries a belt with a different dominant+trace mineral pair (hub Ferrite/Silica, reach Titanium/Iridium, deep Voidite/Iridium, edge Ice/Titanium); hub and deep also carry a derelict graveyard. Trade + refinery stations, with authored supplySkew per station so price varies both across danger tiers AND within a tier from local supply. Three independent miners per belt plus a salvager on each graveyard generate the flows. No hostiles — the sandbox is about flows, and danger-tier PRICING is a property of the system (dangerTier), not enforced by spawns. The set lives under a data/ SUBFOLDER, which ContentDatabase’s boot scan never recurses into, so it is invisible to a normal launch.
How to run it. scripts/economy-sim.ps1 (optional -TimeScale, default 10x) launches a windowed debug build with --vindicator-economy-sim. That flag makes Debug/EconomySim (an autoload, no-op otherwise) swap the shipped eos/karda/veil/marches set for the testbed via ContentDatabase.SwapToSystemSet — validated the same way boot validates the shipped set (reciprocal lanes, station/spawn refs) — before SystemHost builds the universe. The Main-scene player spawns inside sim_hub (authored at galaxy origin), neutral and idle.
Presence. The presence rule keeps only ONE system live (the piloted ship’s, and systems sit far past two capture radii apart), which would freeze every gather ship outside the hub. The design already supports multi-system presence (a fleet — “a parked miner is also a watchtower”), so the sim raises a ForceAllPresent flag SystemHost unions in, forcing the whole set live so mining/salvage flows run in all danger tiers at once. A normal launch never sets it.
Acceleration. Engine.TimeScale (not physics_ticks_per_second). TimeScale scales the delta handed to every process step uniformly — movement, the gather-beam drain, unload timers, refine — so the run is a faithful fast-forward, not a reweighting; timers stay honest relative to the sim. Ticks-per-second scaling only changes fixed-step DENSITY (more, smaller steps, same simulated time) or would decouple delta timers from the step.
What to look at. Every sim-minute the harness appends one row per station-commodity to user://economy-sim/<timestamp>.csv (sim_seconds,system,station,commodity,price,qty,incoming,outgoing), driven off the same EconomySnapshot the F8 tracker reads, so the log and the live overlay can never disagree. Across a run, watch incoming change as miners fill and dump holds (a full hold in flight shows as inbound to its target station, then clears on unload), and compare price across systems (deep Voidite the richest, hub Ferrite the cheapest) and across stations in one system (supplySkew spread). qty/outgoing stay 0 by design until station stock and the hauler role ship — the CSV field is the wired plug point.