Hardpoint heat + overmount — design capture

Captured 2026-07-19 from the owner’s spec (Star Valor inspiration): the owner liked Star Valor-style weapon heat, and hardpoints that can mount MORE than one gun at a heat cost. This doc is the WHY; the player-voiced WHAT that ships with implementation is drafted in §Codex-draft at the bottom.

Status: DESIGN ONLY. Not implemented. No gameplay code changes land with this card — it is documents. The codex draft below lives HERE, not in assets/codex/, so the codex directory stays implementation-accurate (the Codex rule: codex articles ship WITH the code that makes them true). When heat ships, the draft moves into assets/codex/combat-heat.md, CODEX.md is regenerated, and this file keeps only the rationale. This mirrors the missile-ammo card’s “needs design first, then combat wiring” precedent (PLAN.md).

The core idea: heat is a SECOND axis, per-hardpoint

The ship already has ONE shared budget: the energy capacitor (features/combat/Energy.cs, Max 100 / regen 22-per-second on the Vindicator). Engines, shield recharge, and every power weapon drink from that one pool (WeaponMount.TryPayShotEnergy / DrainBeamEnergy). Energy is ship-wide: every mount competes for the same credits.

Heat is deliberately the opposite shape. Heat is per-hardpoint: each mount carries its own heat budget, generates heat only from its own fire, and cools on its own. This is the whole reason the feature exists — a per-hardpoint budget is what turns “bolt a second gun onto one mount” (overmount) into a localized, felt cost instead of just “fire more, drain the shared pool more.”

Two orthogonal axes:

Axis	Scope	Filled by	Emptied by	Gate shape
Energy	ship-wide (one pool)	any consumer (engine/shield/all weapons)	global regen (22/s)	binary per shot: can’t pay → no shot (existing)
Heat	per-hardpoint	that mount’s own fire	that mount’s own dissipation	rate throttle → lockout (new)

A good build balances both. Overmounting spikes them TOGETHER (two guns on one mount = double energy draw from the shared pool AND stacked heat on that one hardpoint’s local budget), which is exactly the tension the owner wants.

Heat budget per hardpoint (scales with ship size class)

Base heat capacity scales with hull size class (xs–xl). Justification: a fighter’s hardpoint is a light rail bolted to a wing; a dreadnought’s is a turret barbette with real coolant plumbing and mass to soak the spike. The grid already scales this way by size (features/modules/GridDimensions.cs: xs 4×3 → xl 10×7), so a size-scaled heat cap is consistent with how the hull’s capability already ladders.

Size	Heat capacity / hardpoint	Overmount slot cap
xs	100	2
s	130	2
m	170	3
l	220	3
xl	300	4

Capacity is a property of the hardpoint on the hull, not of the weapon fitted into it — so the same gun runs cooler on a bigger ship, which reads correctly (bigger ships shrug off sustained fire). All numbers are first-pass; tune in implementation against the real fire economy.

Heat generation per weapon family

Heat is generated only by shots that actually fire (see precedence below). The design target: a SINGLE weapon on its OWN hardpoint runs at a sustainable equilibrium and never locks itself out — except the heavy beam, deliberately. Heat becomes the dominant constraint only when you overmount or weld a heavy continuous weapon. Grounded against shipped weapon data (features/weapons/*/data/*.json):

Family (example)	Heat cost	Cadence	Heat/sec solo	vs 25/s dissipation
Cannon, light (Pulse Cannon: dmg 12, 4/s)	6 / shot	4/s	24	≈ break-even, stays cold
Cannon, heavy (Heavy Cannon)	14 / shot	~2/s	28	slow climb
Beam, light (Energy Beam: 4/tick, 10 energy/s)	20 / sec	continuous	20	stays cold
Beam, heavy (Heavy Beam: ramps 0.7→1.5×)	32 / sec	continuous	32	climbs — forces release
Railgun (dmg 22, 1.15/s, spike)	20 / shot	1.15/s	23	cold, but visibly spikes
Missile (Strike Missile: dmg 18)	8 / shot	1.2/s	10	near cold (ammo-limited, not heat-limited)

Family notes:

Cannon (burst): heat per shot, so cadence sets the average. A lone Pulse Cannon sits right at break-even — heat-free solo, exactly as it plays today.
Beam (continuous): heat per second while lit. A light beam solo is sustainable.
Beam, heavy — the intentional exception. At 32/s it out-paces dissipation even solo, so a heavy beam welded forever WILL climb into throttle and force you to let go. This composes with the shipped BeamRamp (decisions 2026-07-19: 0.7→1.5× over 2.5s, HARD reset on release/switch): the ramp rewards commitment, heat punishes INFINITE commitment. You earn the ramp payoff, heat eventually makes you release, releasing resets the ramp, and the cycle restarts. The two mechanics pull against each other by design.
Railgun (spike): average is cold, but each shot dumps its whole heat load at once — the bar jumps toward red per trigger pull. Two overmounted railguns spike so hard they lock almost immediately. The “spike” read is the point.
Missile: barely heats — ordnance, not a power weapon. Missiles are gated by ammo (the separate missile-ammo card), not heat.

Cooling curves

Passive dissipation: constant 25 heat/s per hardpoint, always on, even while firing. Net rate = generation − 25. Linear, not exponential — a linear bar is legible at a glance and matches the crisp/deterministic precedent the owner already chose for BeamRamp (decisions 2026-07-19: hard reset over slow decay “so the behavior is crisp and deterministic”).
Idle purge: dissipation DOUBLES to 50/s after 1.5s without firing — the coolant catches up once the barrel is quiet. This rewards trigger discipline (tap-and-release cools faster than a held plateau) WITHOUT adding an input, keeping the deliberately two-trigger control scheme intact (weapons.md: “two triggers in-flight today”). Same tap-vs-hold philosophy the heavy beam already teaches.
Venting exists as the idle purge and the forced overheat vent (below), not a manual button. See alternatives for why a manual vent key was rejected.

Overheat penalty — ONE ladder: throttle → lockout → vent → resume

A single heat-fraction curve, no separate systems, no hull damage:

Heat	State	Effect	Color
0–75%	nominal	full performance	NavCyan → GreenNeon
75–100%	throttling	fire rate lerps 100% → 40%	Orange
100%	overheat lockout	mount stops firing, force-vents at 50/s	HullRed
falls below 40%	reset	mount fires again	back to GreenNeon

The throttle IS the telegraph — the gun audibly/visibly bogs down before it cuts, so a lockout is never a surprise. Recovery is automatic: force-vent from full clears an xs mount in ~1.2s (100 ÷ 50/s + reset threshold), no repair, no station visit. Heat is a rhythm mechanic, not a punishment — you fire in disciplined bursts, and the ladder self-corrects.

Chosen deliberately over the alternatives (below): no hull damage (double jeopardy, un-fun), no instant binary shutdown (unreadable in the approach), no whole-ship penalty (too swingy). One curve, fully readable, self-healing.

OVERMOUNT — more guns than one mount can cool

The headline feature: fit MORE than one weapon into a single hardpoint.

How many — a hard slot cap by size (xs 2, s 2, m 3, l 3, xl 4; see budget table). A hard cap + a super-linear heat curve (below) prevents a degenerate “stack eight guns” build. Overmount is a burst-DPS spike, not a stacking ramp.
Heat cost curve — super-linear. Guns on one hardpoint SHARE that hardpoint’s single heat budget, and each additional barrel multiplies its own heat because cramming barrels wrecks local cooling:

Gun on the mount	Heat multiplier
1st	1.0×
2nd	1.35×
3rd	1.8×
4th	2.35×

Worked example — two Pulse Cannons overmounted on one xs hardpoint: 24 (1st) + 24×1.35 = 32.4 (2nd) = 56.4 heat/s, minus 25 dissipation = +31/s → fills the 100-cap xs mount in ~3.2s, then throttles. You get double bolts from one muzzle point, but you CANNOT hold it — you fire in bursts and let it purge. That is the Star Valor feel: more firepower than you can cool, managed by the trigger. - Taxed on BOTH axes. The overmounted guns also each draw full energy from the shared ship pool, so overmount spikes energy AND heat at once. A heavy overmount build wants both a fat capacitor (energy modules) and restraint (heat). - Damage/fire is otherwise normal — overmounted guns fire together from the one hardpoint’s muzzle (the multi-mount wiring gives each hardpoint a distinct muzzle; overmounted guns share it).

Overmount UI language (arena grid)

Each hardpoint shows a slot-pip capacity display — e.g. ◇◇ for a 2-capacity xs mount, filling as guns are stacked (◆◇ = one fitted, one free). A hardpoint at capacity rejects further drops (same reject feel the grid already has for a full cell).
Dragging a weapon block onto an already-occupied hardpoint stacks it into the next pip rather than replacing (a modifier or an explicit stack target; detail for implementation). The existing ship-modules.md “a module weapon fills the next open hardpoint, in order” rule extends to “fills the next open SLOT on the current hardpoint, then the next hardpoint.”
The arena compare card (candidate vs each occupied hardpoint — damage, range, RoF, sustained, energy) gains a HEAT row: the candidate’s heat/sec contribution and the resulting steady-state heat fraction, so a build’s cooling headroom is visible before you commit it.

HUD language (in flight)

Heat reuses the existing cognitive-overlay color ladder as a heat gradient — the same cool→online→warn→danger tokens EconomyTracker and HullReadout already use, so heat reads consistently with the rest of the skin:

NavCyan (cool/idle) → GreenNeon (firing, healthy) → Orange (75%+, throttling) → HullRed (100%, locked). Tokens: Palette.NavCyan, Palette.GreenNeon, Palette.Orange, Palette.HullRed (common/Palette.cs).
Per-hardpoint, not aggregate. The point of the feature is that each mount heats independently; an aggregate bar would hide WHICH mount is about to lock. Add a compact hardpoint heat strip to the player HUD: one short bar per hardpoint (3 for the Vindicator today), grouped tight, each colored by the ladder, with slot-pip markers when a hardpoint is overmounted.
Player-only on the HUD; other ships stay clean. This mirrors the existing split: ShipStatusArcs (“(( s ))” arcs — energy/hull left, armor/shield right) are for reading OTHER ships, and the player reads themselves off HUD bars. Heat is a new player-readout bar, NOT a fifth arc on every enemy (that would clutter every hull in a brawl). Enemy heat, where it matters (arena), reads off their own HUD-equivalent, not world arcs.

Interaction with existing systems

Energy vs heat precedence — energy first, then heat. A shot/tick is gated by ENERGY first (existing all-or-nothing TryDrain / DrainPerSecond behavior, unchanged); only shots that actually fire generate heat. So no energy → no shot → no heat — you cannot overheat a gun you can’t afford to fire. The heat throttle reduces fire RATE, which in turn reduces energy draw, so the two compose cleanly rather than fighting. Energy is the ship-wide budget (all mounts share, global regen); heat is the per-mount budget (each independent, local dissipation). Precedence stated crisply so implementation wires the gate order once: energy gate (binary, per shot) runs before heat accrual; heat gate (rate throttle + lockout) runs before the trigger even reaches the energy gate.
Drone links draw continuous carrier ENERGY (existing) and do not consume a hardpoint (ship-modules.md: “Drone blocks do not consume one of the Vindicator’s three gun hardpoints”). Therefore drones carry no heat and cannot overmount — the drone is the unit, its guns are abstracted. Heat stays a hardpoint-fired-weapon concept only. No change to the drone/energy leash.
Doctrine AI respects heat, but the mount enforces it — no brain change. Ambient NPC hulls run maxEnergy 0 (decisions: “All NPC hulls keep maxEnergy 0 — no NPC energy”) and are energy-EXEMPT; heat takes the same carve-out, so a raider swarm doesn’t simulate heat. Heat binds the player and the arena duelists (the arena is the test bench and should show heat honestly — the DuelBrain drives real loadouts). Where it applies, the AI “respects” heat for free: ShipBrain/DuelBrain just hold TriggerHeld true when on target (ShipBrain.cs:108), and the mount self-gates on heat internally, exactly as it already self-gates on energy and fire rate. A locked mount refuses to fire even with the trigger held — no doctrine logic needed. Smarter burst-timing AI (deliberately pulsing to stay under throttle) is a future refinement, not required for v1.

Dependency / sequencing

Heat + overmount builds ON the end state of the in-flight arena bugfix card (PLAN.md “Arena bugfix pass”), which must be stable first:

Third mount on the Vindicator + distinct hardpoint positions (multi-mount wiring) — heat attaches PER hardpoint, so there must be real, distinct hardpoints to attach to. The Vindicator template already declares three (player_vindicator_xs.json: "hardpoints": [[-8,-9],[8,-9],[0,-14]]) and Ship.cs maps three mounts (set 0/1/2); the arena card makes them fire from distinct muzzles.
Explicit hardpoint reset before module weapon assignment — so a hardpoint’s gun-list is authoritative and “no weapon” truly means no fire. Overmount stacking must start from a known-empty mount.
Cannon contribution restored in the duel flow — heat balancing is tuned against real cannon + beam fire, so the duel must actually emit both.

Also depends on the shipped energy pool (features/combat/Energy.cs), since precedence is defined against it. Design assumes the arena card has landed. Implementation order once foundations are stable: (a) per-hardpoint heat accumulator (mirror BeamRamp’s pure/testable shape — a Godot-free HeatSink.Advance(dt, generated) / Fraction / Locked), (b) generation hooks in WeaponMount firing paths, (c) throttle+lockout gate, (d) overmount slot model + arena grid stacking UI, (e) HUD heat strip, (f) codex article moves to assets/codex/.

Alternatives considered (and why rejected)

Heat as a ship-wide pool (one heat bar, like energy) — REJECTED. Makes overmount indistinguishable from “just fire more”; the localized cost that makes stacking guns on ONE mount interesting evaporates. Per-hardpoint IS the feature.
Overheat deals hull damage — REJECTED. Double jeopardy (lost DPS AND lost hull), unreadable, un-fun. The throttle→lockout ladder is self-correcting and costs only tempo.
Manual vent button — REJECTED. Adds a third input to a deliberately two-trigger scheme (weapons.md). The idle purge gives the same “cool it down” agency through trigger discipline, no new key.
Exponential cooling curve — REJECTED. Linear is legible on a bar and matches the crisp/deterministic BeamRamp precedent (decisions 2026-07-19).
Heat replacing energy for weapons — REJECTED. Energy is a shipped, shared cross-system budget (engines/shield/weapons); heat is a NEW orthogonal axis. Two axes give richer loadout decisions (energy-heavy vs heat-heavy builds) than collapsing them into one.
Unlimited overmount at pure-linear cost — REJECTED. A hard slot cap (2–4 by size) + super-linear heat multiplier stops a degenerate stack; the spike stays a spike.
Heat on every ambient NPC — REJECTED. Simulating heat on every raider buys nothing the player sees and costs perf; heat takes the same player/arena carve-out energy already has.

§Codex-draft

The player-voiced article that ships WITH implementation. Lives here (not assets/codex/) until the code is real; then it moves to assets/codex/combat-heat.md with the frontmatter below and CODEX.md is regenerated. Category Combat, order 30 (after Weapons 10, Ship Modules 20).

---
category: Combat
order: 30
summary: Every hardpoint runs its own heat budget, and you can overmount a second gun onto one at a cost you have to manage.
---

# Weapon Heat & Overmount

A gun does not tire, but its mount does. Every hardpoint on your hull runs
its own heat budget, filled by its own fire and bled off by its own coolant,
and it does not share that budget with the mount beside it. This is a
different thing from your energy capacitor — the capacitor is one pool the
whole ship drinks from, engines and shield and every gun at once. Heat is
local. Each hardpoint sinks or swims on its own.

Fire a single honest gun on its own mount and you will rarely think about
heat: a Pulse Cannon on one hardpoint sits at a lazy simmer, its coolant
keeping pace with the trigger forever. Heat is not there to tax ordinary
shooting. It is there for the two things that ask too much of one mount:
welding a heavy beam to a target, and overmounting.

## Reading the bar

Each hardpoint carries a heat strip on your HUD, and it speaks in the same
colors the rest of your cockpit does. **Cool blue** is idle. **Green** is
firing and healthy. When a mount crosses into **orange** it has begun to
throttle — the gun bogs down, its rate of fire dragging as the heat climbs,
and that slump is your only warning and all the warning you need. Let it run
to **red** and the mount overheats: it cuts out entirely and force-vents,
dark and useless, until the coolant drags it back down enough to light again
— about a second of nothing, on a light hull. No damage, no repair bill.
Just a gun that made you wait.

So heat is a rhythm. Tap and release and a quiet mount purges faster than a
held one ever cools — discipline is rewarded without a single extra button.
Hold everything wide open and you will meet the throttle, then the lockout,
then the wait.

## The heavy beam, again

The heavy beam already asks you to commit — hold it on one throat and its
bite winds up over a couple of seconds. Heat is the other end of that
bargain. A heavy beam runs hot enough that even alone it will climb, so an
endless weld eventually forces you to let go — and letting go drops the
wind-up back to the floor. You earn the ramp by holding; heat makes you
release before you would like to. Pick your moment.

## Overmount

Here is the trick the owner wanted: you can bolt MORE than one gun onto a
single hardpoint. A light hull takes two to a mount; heavier hulls take
three, and the biggest take four. Two Pulse Cannons on one hardpoint throw
both bolts from the same muzzle at once — real, sudden firepower out of a
single point.

The catch is heat, and it is not a gentle catch. Guns crammed onto one mount
share that mount's one budget, and each extra barrel runs hotter than the
last — the second gun costs more than the first, the third more again,
because there is nowhere for the heat to go. Overmounted, that pair of Pulse
Cannons buries the bar in a few seconds flat. You cannot hold it. You fire
in bursts, you let it purge, you fire again. And because every one of those
guns still drinks from your shared capacitor, an overmount build spikes your
energy and your heat in the same breath — it wants a deep capacitor and a
steady trigger finger both.

In the outfitting grid a hardpoint shows its slots as open diamonds; drop a
gun in and one fills. Fill them all and the mount takes no more. Before you
commit a block, the compare card tells you the heat it will add and where
that leaves the mount — so you can see, without firing a shot, whether you
have built something you can actually keep cool.

*See also: [Weapons](weapons.md) for the gun families and the heavy beam's
wind-up; [Ship Modules](ship-modules.md) for the hardpoint grid and the
shared capacitor these guns draw on.*