Munitions — ammo & kinetic fabrication (design capture)

Captured 2026-07-19. Design-only pass for the PLAN card “[Economy] Missile ammo + kinetic fabrication”, whose own note says “Needs economy UX/storage/source design first, then combat wiring.” This doc is that economy design; the combat wiring is a separate, later card sequenced at the end here.

Sits downstream of docs/design-economy.md (the mineral ladder, refine chain, cargo hold, dock services it reuses) and alongside docs/design-fleet.md (who carries what). It states what the munition economy IS; the why of the big splits lives in “Alternatives considered” at the bottom.

For cross-system ownership, start at the short visual/combat spine. Weapon item wrappers, hardpoints, and FX families live in design-weapons-modules.md; hull markings and faction presentation live in design-faction-art-language.md.

System spine

Hull = faction body · Hardpoints = neutral sockets · Weapon = modular item (WeaponTemplate ± module wrap) · FX/art = recolorable item family · Default loadout ≠ unique inseparable gun.

This file owns ammunition, capacitor, fabrication, rearm, and heat-order consequences. It does not assign faction paint or duplicate modular weapon implementation.

The problem this solves

Today every weapon that costs anything to fire pays the capacitor (features/combat/Energy.cs): cannons pay energyPerShot, beams drain energyPerSecond (features/weapons/WeaponMount.cs — TryPayShotEnergy, DrainBeamEnergy). That makes energy the only firing throttle, so a kinetic slug-thrower and an energy beam are economically identical — both are “free until the capacitor says no, then free again a second later.” Nothing in the hold is ever spent by shooting. Kinetic weapons have no reason to exist as a distinct choice.

Munitions fix that: some weapons stop drinking (only) from the regenerating capacitor and start eating finite, hauled, fabricated stock out of the cargo hold. A dry gun is dry until you dock, fabricate, or buy more — the capacitor cannot bail you out.

1. Taxonomy — which family consumes what

There are two resource families and two matching visual families. Both use the same weapon/module wrapper; changing the resource gate does not create a second inventory or art pipeline.

Current `WeaponType` / role	Resource gate	Art family	Current example IDs
`Beam`	capacitor only	soft plasma/beam glow	`weapon.energy_beam`, `weapon.heavy_beam_xs`
`Cannon` — energy bolt	capacitor only	soft plasma bolt	`weapon.pulse_cannon_xs`
`Cannon` — kinetic body	planned hold ammo, with optional residual energy	solid body + trail	`weapon.nautolan_bullet_xs`, `weapon.heavy_cannon_xs`
`Cannon` — rail hybrid	capacitor today; ammo only if a `MunitionId` is deliberately authored later	kinetic-looking projectile + trail	`weapon.railgun_xs`, `weapon.heavy_railgun_xs`
`Missile`	planned hold ammo; optional energy is allowed	solid ordnance body + motor trail	`weapon.nairan_missile_s`, `weapon.klaed_torpedo_m`
`Drone`	capacitor/link rules; no ammo in MVP	deployed craft, not a shot sprite	no current `WeaponTemplate` ID; drone modules wrap `weapon.pulse_cannon_xs` or `weapon.energy_beam`

WeaponType therefore selects broad runtime behavior, not resource truth. Energy means capacitor-only and uses the soft energy family. Kinetic means hold ammo (plus optional energy) and uses a solid body/trail. Rail is the intentional hybrid: it reads as accelerated mass without forcing every Cannon to become a metal shell.

The shared high-resolution energy family uses a narrow white-hot core with a controlled soft halo, staged as charge → muzzle → projectile or beam → impact. Kinetic, missile, and rail shots retain a readable solid body or slug plus trail; they are never glow-only. Pink/orange comet treatment is reserved for exotic items, and the large starburst impact is reserved for heavy hits. Faction tint and exact sprite/FX authoring remain in the faction art bible and weapons/modules document.

Mining, salvage, and repair are utility tools, even where their current JSON reuses Beam or Cannon. Their tool faces and work FX do not belong to the combat modular kit and must not borrow the player’s hero-lance glow. See the weapons/modules document for that boundary.

The load-bearing insight: WeaponType is NOT the ammo boundary. WeaponType.Cannon (common/Taxonomy.cs) currently lumps together energy bolts and kinetic guns:

Weapon (shipped JSON)	`type`	Today’s cost	Physically is
Pulse Cannon	cannon	`energyPerShot 2`	energy bolt
Railgun	cannon	`energyPerShot 3`	kinetic slug
Heavy Cannon	cannon	`energyPerShot 2`	kinetic shell
Slug Repeater (Nautolan)	cannon	`energyPerShot 1`	kinetic slug
Energy/Heavy/faction Beams	beam	`energyPerSecond`	energy
Strike / Cruise / Torpedo / Toxic	missile	(free!)	ordnance

So keying ammo off WeaponType would wrongly demand slugs from the Pulse Cannon (an energy bolt) and could not express whether a railgun remains pure energy or opts into ammo. The design adds an explicit munition discriminator on WeaponTemplate, not a WeaponType overload:

// WeaponTemplate additions (JSON-driven, all optional — omit = unchanged)
string MunitionId   { get; init; } = "";   // "" => no munition, energy-only (unchanged)
int    RoundsPerShot { get; init; } = 1;    // discrete draw per trigger pull / volley

The taxonomy table (what ships when this lands)

Family	Munition draw	Capacitor draw	Heat	Notes
Beams (energy/heavy/lasers/picket/lance)	none	`energyPerSecond` (unchanged)	yes	Pure capacitor. The taxonomy anchor: energy weapons never touch cargo.
Energy bolt cannons (Pulse Cannon)	none	`energyPerShot` (unchanged)	yes	Stays energy — it is literally an energy bolt. The player’s default gun costs no ammo, so an empty magazine is never a soft-lock.
Kinetic cannons / autocannon (Slug Repeater, generic cannon)	`munition.slug` ×1	0 (drop `energyPerShot`)	yes	Cheap bulk kinetic. High cadence eats stock fast.
Railgun / mass-driver	none by default; optional `munition.rail_slug` only when deliberately authored later	`energyPerShot`	yes	Hybrid presentation: kinetic-looking projectile, capacitor-driven launch. Do not infer ammo from the art.
Heavy cannon / shell	`munition.shell` ×1	0	yes (high)	Slow, heavy, pricier round.
Flak (family exists in design, not yet in JSON)	`munition.flak` ×1	0	yes	Area burst; round is the point-defense sink.
Missiles (strike/toxic/torpedo/cruise)	discrete `missile.*` ×`RoundsPerShot`	0	low	Discrete ordnance, not “fabricated bulk” — one warhead, one launch. Pooled by weight class: `missile.strike` (light) and `missile.torpedo` (heavy).
Utility (mining/salvage/repair)	none	as today	none	Tools, never ammo.
Drones (`WeaponType.Drone`)	none (MVP)	as today	—	Drone bays are their own later system; not munition-gated in this pass.

Rule of thumb: if it throws mass, it usually eats a munition; if it throws light or plasma, it drinks the capacitor. Rail is the explicit authored exception. Missiles eat a munition and are discrete named ordnance rather than fabricated bulk.

Retrofit consequences

Per-family ammo pooling already suits modular weapons: every equipped item with the same MunitionId draws from the same cargo stack.
Equipping an ammo-fed kinetic or missile module surfaces REARM and HUD state only when its WeaponTemplate authors a MunitionId/ammo family. Capacitor-only rail hybrids have no ammo family and must not show REARM.
NPC firing remains unmetered. Only the player pays retrofit logistics; an NPC default loadout is still just a list of modular weapon IDs.

2. Storage — where ammo lives

Decision: reuse CargoHold; ammo is a commodity, not a new subsystem.

features/economy/CargoHold.cs is already a generic Dictionary<string,float> store with a unit Capacity, Add/Remove/ Quantity, and — critically — it is lost with the hull (the run’s risk). Munitions get a new CommodityCategory.Munition and live in that same hold.

No dedicated magazine component for MVP. A “magazine” node would duplicate everything CargoHold already does. Adding a category is a data change; adding a subsystem is a refactor.
Pooled per-family, not per-weapon. One munition.slug stack feeds every kinetic cannon on the hull; one missile.strike stack feeds every light launcher. This matches how cargo already pools commodities and keeps the HUD readable (a handful of stacks, not one counter per hardpoint). Per-weapon reservoirs are rejected below.
Capacity vs ShipSize — the deliberate tension. Because ammo shares the cargo hold, a loaded warship carries less loot, and a full ore-hauler carries fewer rounds. That tradeoff is the point: cargo capacity already scales with hull (features/economy hold + the grid ladder in features/modules/GridDimensions.cs, xs 4×3 → xl 10×7), so a fighter’s slim hold forces real “guns or groceries” choices while a battlecruiser can carry a war’s worth of both.
Later, optional: a Magazine ship-tweak module (the “Ship tweaks” category in docs/design-economy.md) that adds dedicated ammo-only capacity, so a committed combat loadout isn’t strangled by the loot/ammo split. This is a grid-inventory module, content not a refactor — deferred past MVP but the reason per-family pooling is worth keeping simple now.

3. Sourcing — fabrication recipes

Munitions are fabricated, reusing the refine-chain pattern exactly (features/economy/RefineMath.cs — whole units in, whole units out, leftover below the ratio stays behind). Fabrication is refining with a munition as the refineTargetId target instead of a component.

The recipe ladder (mineral/component tier → munition)

Recipes climb the same T1–T5 mineral ladder (docs/design-economy.md), so “better ammo costs rarer ore” falls straight out of the existing economy:

Munition	Fabricated from	Tier	Rationale
`munition.slug`	Ferrite (or Alloy Plate)	T1	Bulk kinetic = the cheapest, most abundant ore. Ammo is a Ferrite sink, giving T1 a combat demand beyond hull stock.
`munition.shell`	Titanium / Armor Plating	T3	Heavy rounds want frontier metal.
`munition.flak`	Silica / Circuit Board	T2	Point-defense canisters = fuzed electronics.
`missile.strike`	Titanium + Fuel Cell	T3	Warhead (metal) + propellant (Ice→Fuel Cell) — two inputs, so missiles pull on two lanes.
`missile.torpedo`	Iridium / Weapon Core	T4	Capital ordnance = high-tech weapons stock.

Two authoring shapes, both already supported or a thin extension:

Single-input munitions (munition.slug from Ferrite) drop straight into the existing refineTargetId/refineRatio fields — a Ferrite stack can refine into either Alloy Plate or Slug depending on which button the player hits, so a commodity may want a small fabricateTargetId alongside its refineTargetId rather than a single target. (One-target-per-commodity vs. a recipe list is the one open data-shape question — see Sequencing.)
Multi-input munitions (missile.strike = metal + propellant) need a small recipe object (inputs: [{id, qty}], output, qty) — a genuinely new data structure, but tiny, and only missiles need it for MVP.

Buy-at-station option + price ladder

Not every rearm should require a refinery run. Munitions also sell on the dock market (they are commodities with a baseWorth), so:

Trade / Shipyard stations stock munitions at baseWorth × station skew (features/economy/SellMath.cs skew already exists), same buy path a future outfitting shop uses. Buying is the convenient, pricier option; fabricating from ore you mined is the cheap, self-sufficient one.
Price ladder mirrors the fabrication ladder: slugs cheap and everywhere, torpedoes expensive and only stocked at higher-tier/defense hubs. A deadly frontier station charges more for the same round (the danger skew), so rearming deep in hostile space costs a premium — another reason to haul.
Missiles as discrete ordnance stay pricier per unit than bulk kinetic, so spamming torpedoes is a real credit drain, not a default.

4. Resupply UX

Dock rearm flow (reuse the DockScreen)

features/stations/DockScreen.cs already has REPAIR / REFUEL / SELL / REFINE / DEPART sections. Add:

REARM — one row per munition the ship’s equipped weapons can consume, showing held / capacity and a buy control (baseWorth × skew), plus a REARM ALL that tops every family to capacity for one credit sum (mirrors SELL ALL / REFINE ALL). Available at Trade/Shipyard stations.
FABRICATE rows appear in the existing REFINE section at Refinery stations — the same “ore in, whole batches out” UI, with munition targets listed beside component targets. No new screen; a munition is just another refine output.

In-flight fabrication?

No (MVP). Fabrication is a docked action, same as refining. An in-flight fabricator is a tempting later ship-tweak module (turn hauled ore into rounds mid-fight) but it undercuts the whole “you must disengage and resupply” tension this design exists to create. Deferred, explicitly.

HUD ammo readout language

The HUD already shows cargo/energy. Ammo reads as per-family round counts on the active weapon set, not raw cargo stacks: e.g. SLUG 84 / TORP 6 near the weapon indicator, dimming to a warning color under ~15% and to empty when 0. Energy weapons show the capacitor bar as today — no ammo line, reinforcing the taxonomy visually (if it has a round counter, it eats mass).

Empty-ammo behavior

Click dry = a dull click + a brief “OUT: SLUG” flash, no shot, no cooldown burned. The gate sits right beside TryPayShotEnergy in WeaponMount._PhysicsProcess (the TriggerHeld && cooldown==0 branch): a new TryPayMunition(template) that returns false when the pooled stock is empty, short-circuiting the shot exactly like a failed energy pay.
No silent auto-switch. Auto-swapping the player’s active weapon set on a dry gun is rejected — it steals aim control and hides the resource state the whole system is teaching. The empty gun stays empty and loud about it; switching is the player’s call.
Energy fallback stays available by design: because the Pulse Cannon (the default set-0 gun) is energy-only, a bone-dry ship can still fight its way home on the capacitor. Ammo scarcity is a pressure, never a hard can’t-shoot-anything lock.

5. AI — do NPC ships consume ammo?

Recommendation: NO — NPC brains fire unmetered (energy AND ammo).

Simulation cost & fairness. Tracking, fabricating, and resupplying finite ammo for every spawned pirate/militia hull is bookkeeping the player never sees the far side of (an NPC doesn’t dock to rearm on screen), and an NPC that runs dry mid-fight and stops shooting reads as a bug, not a mechanic. The existing brains already never pull utility triggers (IsUtilityWeapon); munitions extend “the AI just fires what it’s holding.”
The economy is the player’s constraint. Ammo scarcity is a loadout/logistics choice the player makes; imposing it on NPCs adds no player-facing depth and a lot of edge cases (fleeing-to-rearm AI, ammo loot from every kill, etc.).
One deliberate exception, later: the independent-faction gather drones and any fabricator/hauler NPCs in the economy testbed (docs/design-economy.md “Economy testbed”) may produce munitions as an economic flow, but that is supply-side simulation, not combat consumption.
Loot hook (optional, cheap): a killed kinetic-armed NPC can drop a small munition cache as salvage — consumption stays off, but ammo enters the world as a combat reward, closing a nice “kill pirates → restock slugs” loop without simulating their magazines.

6. Balance intent — why this makes kinetic vs energy a real choice

Without munitions, energy is strictly better: it regenerates and never runs out. Munitions buy kinetic weapons a compensating identity:

Energy weapons: infinite ammo, capped rate (capacitor regen is the ceiling), zero logistics. The choice for long patrols, exploration, and anyone who doesn’t want to think about supply. Sustained but rate-limited.
Kinetic weapons: burst far past the capacitor ceiling (no per-shot energy tax), usually higher raw damage-per-shot, but every trigger pull spends hauled stock and hold space. The choice for a planned engagement you rearmed for — front-load damage, then you’re on the capacitor gun home.
The knock-on economy demand: ammo turns combat itself into a mineral sink, giving Ferrite/Titanium/Iridium a pull beyond hulls and modules — you mine to shoot, not only to sell. That deepens every existing loop (mine → haul → refine → fabricate → fight) without a new subsystem.
Scarcity = tension, not tedium: because the default gun is energy, going dry is a degradation (you drop to your fallback), never a wall. The player who over-commits torpedoes limps home on the Pulse Cannon and rearms — a consequence, not a game-over.

7. Three throttles — heat + energy + ammo precedence

An in-flight design card (PLAN “[Combat] Hardpoint heat + overmount”) is introducing heat as a third firing throttle. Heat, energy, and ammo must compose cleanly. Defining the precedence now so both cards wire to the same contract:

At the fire gate (WeaponMount, the TriggerHeld && cooldown==0 branch), a shot fires only if all pre-pay gates pass, checked in this order:

Munition (cheapest check, most fundamental): no round → dull click, no shot, no cooldown, no energy, no heat. A dry gun does nothing.
Energy (TryPayShotEnergy today): capacitor can’t pay → no shot; the round is not consumed (you don’t burn ammo on a shot that didn’t fire).
Heat lockout: if the mount is in overheat lockout, no shot; round and energy not consumed.

Heat is otherwise a post-shot accrual — a fired shot adds heat, which may later trip the lockout in check 3. So: ammo and energy are pre-pay gates (both must be affordable before anything is spent, and a failure spends nothing); heat is both a gate (lockout) and a consequence (accrual). The three axes stay orthogonal — a weapon can be any combination of {ammo-gated, energy-gated, heat-gated} — and the “spend nothing on a shot that didn’t fire” rule keeps them composable regardless of which throttle blocks first.

This card owns only axis 1 (munition); it must not assume heat’s data shape, only that the gate order above is honored when both land.

8. Sequencing for the combat-wiring card

This is design-only. The follow-up combat-wiring card implements, in order:

Data: CommodityCategory.Munition; MunitionId + RoundsPerShot on WeaponTemplate; munition commodity JSON entries (slug/shell/flak/ strike/torpedo) with baseWorth + fabrication targets. Resolve the one open data-shape question: single fabricateTargetId per ore vs. a recipe list (recommend the recipe list — it’s the only shape that supports multi-input missiles and ore-with-two-outputs cleanly).
Fire gate: TryPayMunition in WeaponMount, wired beside TryPayShotEnergy with the precedence in §7. Draw from ship.Cargo.
Fabrication: extend RefineMath/DockScreen REFINE to emit munition targets (single-input) + a small multi-input recipe path for missiles.
Dock REARM section + buy path (reuse SellMath skew).
HUD ammo readout + empty-gun feedback.
Content pass: set MunitionId on intentionally ammo-fed JSONs (Heavy Cannon, Slug Repeater, missiles), drop their energyPerShot where the design is ammo-only, and leave Pulse Cannon, railguns, and all beams on capacitor unless a rail munition is deliberately authored later. Ship the codex update (below) in the same change (the Codex rule).
Balance tune against the economy testbed once flows run.

Each numbered step is a candidate card of its own if the wiring card is too big to land atomically.

9. Alternatives considered — and rejected

Key ammo off WeaponType.Cannon. Rejected: Cannon mixes energy bolts (Pulse Cannon) and kinetic slugs (Railgun/Slug Repeater). An explicit MunitionId is the only clean boundary.
Dedicated magazine subsystem (separate from cargo). Rejected for MVP: duplicates CargoHold, and sharing the hold creates the desirable loot-vs-ammo tension for free. Revisited only as an optional capacity-adding ship-tweak module later.
Per-weapon ammo reservoirs. Rejected: N counters for N hardpoints is HUD noise and forces micro-managing which gun gets the last rounds. Pooled per-family is simpler and reads better; the “assign ammo to a mount” fantasy isn’t worth the UI.
All cannons (incl. Pulse Cannon) consume ammo. Rejected: it turns the player’s default gun into a soft-lock risk. Keeping one energy gun on the hull guarantees a dry ship can still fight home.
In-flight fabrication as default. Rejected: erases the disengage-and- resupply loop the whole system exists to create. Deferred to an optional module.
NPCs consume ammo too. Rejected: invisible bookkeeping, “AI ran dry and froze” reads as a bug, adds no player-facing depth. NPCs fire unmetered; ammo is the player’s logistics game.
Missiles as fabricated bulk like slugs. Rejected: missiles are named, discrete ordnance — one warhead per launch, pricier, pooled by weight class. Treating them as interchangeable bulk erases their identity as the expensive-but-devastating option.

§Codex-draft

Draft for assets/codex/munitions.md (or a Munitions section merged into weapons.md). Player-voiced, accurate to the taxonomy above; finalize and ship in the SAME change as the combat wiring, per the Codex rule. Front-matter category Economy or Combat — likely Combat, ordered after Weapons.

---
category: Combat
order: 15
summary: Kinetic guns and missiles burn hauled, fabricated ammo — energy weapons don't. Guns or groceries.
---

# Munitions

Not every gun runs on the capacitor. Point light or plasma at something — a
beam, a pulse bolt — and you're spending charge that climbs back on its own;
you can hold that fight forever, just not faster than the capacitor refills.
But an ammo-fed weapon throws something you had to make first. A cannon shell
or torpedo is stock out of your hold, and when the hold's empty, that gun is a
very expensive club until you rearm. Railguns currently accelerate a
kinetic-looking shot from the capacitor; a fitted model only consumes cargo if
its description names a munition.

## Which guns eat ammo

Read it off what the weapon throws:

- **Beams and the Pulse Cannon** run on the capacitor. No ammo, ever. Your
  fitted Pulse Cannon will always fire — which is exactly why you can limp
  home on it after you've burned through everything else.
- **Ammo-fed kinetic cannons, slug repeaters, and flak** eat **slugs, shells,
  or flak canisters** — bulk stock you fabricate from ore. Cheap per round,
  spent fast. Railguns remain capacitor weapons unless a later model
  explicitly lists ammunition.
- **Missiles and torpedoes** are discrete ordnance: one warhead, one launch,
  and they cost real credits to replace. You don't spam them by accident.

## Where rounds come from

Two ways, same as anything else out here — make it or buy it:

- **Fabricate** at a Refinery, right beside the ore-refining rows: feed a
  batch of ore in, get munitions out. Slugs come off cheap Ferrite; heavier
  shells want Titanium; missile warheads pull metal *and* propellant. The ore
  you were going to sell can become the ammo that gets you to the next belt.
- **Buy** at Trade and Shipyard docks — the REARM section tops your stock up
  for credits. Convenient, pricier than making your own, and pricier still out
  in dangerous space where everything costs more.

## Guns or groceries

Ammo rides in the same hold as your ore and salvage. A hold packed with
torpedoes is a hold not packed with loot, and a full ore run leaves little
room for rounds. That's the choice: haul a war's worth of ammo, or a hold's
worth of profit. A bigger hull carries more of both; a fighter carries a
little of one.

## Running dry

Pull the trigger on an empty gun and you get a dull click and an **OUT** flash
— no shot wasted, no shot fired. Nothing auto-switches; the dry gun stays dry
until you rearm, and picking a different weapon is your call. Watch the round
counters by your weapon set: when SLUG or TORP starts blinking, it's time to
think about the trip back to a dock — before the belt between you and it
decides for you.