Modular weapons and modules

Start at the visual combat system spine.

This document owns weapons as modular retrofit items, authored hardpoints, reusable FX families, and the mapping between art, WeaponTemplate, and an optional ModuleTemplate wrapper. It does not own lore prose, damage/DPS balance, or ammunition economy; those belong to faction/codex content, runtime content tuning, and munitions respectively.

The modular contract

A weapon is a modular retrofit item: the same mechanical WeaponTemplate may ship built into a hull or be equipped through a ModuleCategory.Weapon wrapper. Hull art must never bake a permanent unique gun as the only way to read that faction. A visible role graft is allowed—for example, one oversized Korrathi launcher may shape a chassis—but its functional weapon and FX remain attachable at an authored hardpoint. Hardpoints are neutral scene-authored anchors; runtime attaches the mount sprite and firing FX. NPC default loadouts are content choices, not a second art pipeline. Loot, salvage, and shops may move the same visual kit across factions: ownership reads from hull and markings, never from a claim that only one faction can fire a particular bolt.

Current implementation versus forward contract

Current, shipped foundations

• WeaponTemplate is the JSON-loaded mechanical definition. It carries Type, tint keys, beam/trail style, projectile presentation, and firing values.
• A ship template’s weapons list loads those IDs directly into three scene-authored WeaponMount nodes. Those nodes, not hull pixels, own muzzle position and orientation.
• ModuleTemplate with Category = Weapon wraps a WeaponId and may override WeaponColorHex. ModuleEquipping clears the mounts and loads weapon-module instances into open mounts in order, applying rolled weapon values.
• WeaponMount.Load calls ConstructorWeaponArt.ApplyMount; mount art is a child of the anchor. Beams, projectiles, trails, and impacts are separate runtime presentations.
• Module inventory/drag previews currently use one procedural glyph selected by ModuleTemplate.Icon; that glyph and its module tint are shared by palette, grid, and drag preview.
• The Arena applies real module instances through ModuleEquipping before its duel. It is the retrofit/loadout laboratory before the dock outfitting shop exists, not a separate combat-content format.

Forward contract, not yet runtime truth

• WeaponTemplate has no live munition discriminator today. All live firing uses capacitor fields when authored; a zero-cost missile is not yet consuming cargo. MunitionId, cargo consumption, REARM, and player-only ammo logistics remain the design in Munitions.
• When munitions land, equipping an explicitly ammo-fed kinetic or missile module must surface its REARM family and expected stock. An energy-only module or capacitor-only rail hybrid shows capacitor/heat, not a fake ammo requirement. NPC ammo remains unmetered; this logistics decision belongs to the player. Heat remains a separate per-hardpoint axis in Combat heat.
• Fabrication produces reusable module items, including weapon wrappers. It does not manufacture hull-exclusive guns; see Economy.

Art package and runtime mapping

Author one reusable package per weapon item family, with tintable regions where readability survives recoloring. A package may include:

1. Mount sprite — emitter, barrel, rack, or tool face attached to the hardpoint. It must read at gameplay scale without merging into the hull.
2. Muzzle/charge — a separate transient at the anchor; never painted into the idle hull or permanent mount sprite.
3. Shot body — beam, plasma/energy bolt, physical projectile, or missile.
4. Trail and impact — separate from the shot body so speed, lifetime, and hit feedback can vary without cloning the projectile.
5. Inventory glyph — a compact family silhouette for module palette, inventory, compare view, loot, and later shops. It represents the item, not the faction currently holding it.

FX acceptance

• Energy: use a narrow white-hot core with a controlled soft halo. Keep charge/muzzle, beam or projectile, and impact as three separable stages so timing and scale can change independently. Pink/orange comet treatments are exotic-only; large starbursts are heavy-impact-only, not the default hit.
• Kinetic, missile, and rail: retain a readable solid body (or rail slug) plus a separate trail. They are never glow-only silhouettes.
• No sprite or FX sheet bakes in a black background. Faction color and visual verbs belong to the faction art language, not a duplicate palette table here.

WeaponTemplate selects the mechanical and base presentation family. ModuleTemplate.WeaponId selects that template; WeaponColorHex may recolor the shared family for the physical module instance. Do not create a unique mount/projectile/impact sheet for every hull-loadout pair. Faction visual verbs in the faction art language may tune restraint, heat, geometry, or corruption around the shared family without changing its mechanical identity.

Weapon type, resources, and art family

The WeaponType enum is a runtime firing-path taxonomy, not an ammo or art ownership boundary. In particular, Cannon already includes both energy bolts and kinetic-looking rail shots.

Runtime type / family	Current resource gate	Intended resource story	Art family	Current example IDs
Beam combat	Capacitor via energyPerSecond (for example 10 or 16/s)	Capacitor only; heat when that system lands	Soft core beam, charge, restrained muzzle, separate impact	weapon.energy_beam, weapon.heavy_beam_xs
Cannon energy bolt	Capacitor via energyPerShot (Pulse Cannon currently uses 2)	Energy-only when explicitly authored as plasma/energy	Soft-glow bolt plus bloom/trail; a Cannon is not automatically a metal shell	weapon.pulse_cannon_xs
Cannon heavy slug	Capacitor via energyPerShot (Heavy Cannon currently uses 2)	Planned munition.shell kinetic ammo; remove its per-shot capacitor cost when that content lands	Solid, slow heavy slug plus a restrained trail and weighty impact	weapon.heavy_cannon_xs
Cannon rail / kinetic read	Capacitor via energyPerShot (Railgun 3; Heavy Railgun 25)	Rail stays a kinetic-looking projectile with a capacitor/coil story now; add ammo later only when an explicit munition is authored	Solid fast slug plus thin rail trail/helix, separate impact	weapon.railgun_xs, weapon.heavy_railgun_xs
Missile	No live capacitor or cargo gate in current JSON	Discrete cargo ordnance via the planned munition family	Solid missile body plus engine trail; never force soft-glow plasma language onto it	weapon.klaed_torpedo_m, weapon.nairan_missile_s
Beam / Cannon utility	Utility = true; zero damage; current prototypes have no firing energy cost	No combat ammo; tool costs stay with the utility/economy design	Industrial mining, salvage, or repair tool face and work effect	weapon.nairan_mining_beam, weapon.nautolan_salvage_array, weapon.nautolan_repair_bolt
Drone	Enum exists, but current module drones use ModuleCategory.Drone and a DroneWeaponId rather than direct drone-type weapon JSON	Carrier upkeep and drone design, not gun ammunition	Drone body, link/readout, then its referenced beam/cannon family	No direct WeaponType.Drone JSON currently

Energy and kinetic therefore describe two resource and presentation families, while wrapper modules use the same equip path for both. A future kinetic gate must key from explicit weapon content, never from WeaponType.Cannon. Rail is intentionally hybrid-readable: solid accelerated mass in the art, capacitor/coil draw in the present mechanics, and cargo ammo only if later content says so.

Utility tools are a separate kit

Mining, salvage, and repair use hardpoints and some shared firing machinery, but their art language is work equipment, not hero combat glow. Give them industrial faces, progress/transfer motion, and clear non-damaging impacts. Civilian and Ancient tool styling may change the housing; it must not turn a mining beam into a player lance or imply that a repair bolt is ordnance.

Content and documentation handoff

• Faction art language owns faction bodies, markings, and short weapon/VFX verbs.
• Fleet content owns hull IDs and default lists of modular weapon IDs; proxy packs are not final faction-exclusive art.
• Munitions and combat heat own firing resources and gate order.
• Economy owns construction, salvage/shop distribution, and when retrofit items enter the campaign.
• Weapons, Ship Modules, and Ships state only player-visible shipped truth.

When implementation changes any of those player-visible rules, update its codex article in the same change. Design-only forward contracts stay here.