How to Design a New Weapon

Before you start

A new weapon usually needs only a data file — one .ts export under src/starship-survivors/data/weapons/, plus one line in the barrel. The engine already wires every standard projectile, beam, chain, mortar, and AoE shape; picking from those primitives is the common case.

Custom behavior is a separate, rarer task. It means registering a new BulletBehavior (or, less often, a new WeaponArchetype) in the engine. See step 6. Decide which case you are in before writing anything.

Case	What you touch
Reskin / re-tune an existing flight pattern	one data file + barrel
New flight pattern or fire dispatch	one data file + barrel + bullets.ts + (sometimes) weapons.ts
New family-level capability	above, plus archetypes.ts

Step 1: Pick the weapon’s identity

The designer locks seven decisions upfront. Each maps to a WeaponCoreSpec field with a fixed enum domain.

Decision	Field	Allowed values	Notes
Rarity	rarity	common, uncommon, rare, epic, legendary	Drop-rate display is flattened at runtime: any non-legendary spec resolves to common; legendaries (those with isLegendary: true) resolve to legendary. See weapons.
Family	family	projectile, explosive, sniper, beam, chain, homing, sweep	Family drives juice defaults and family-level filters in artifacts.
Damage tag	damageTag	bullet, energy, bomb, fire	Required to participate in legendary fusion. See damage tags. Legendaries also set secondaryDamageTag.
Damage type	damage_type	normal, true	Omit for normal (default). true bypasses shield absorption.
Target mode	targetMode	closest, furthest, flanking, low_hp	See target modes. Conventional: rifles/SMGs use closest; mortars and railguns use furthest; cannon/revolver use flanking; missile uses low_hp.
Collision mode	collisionMode	first_hit, pierce_all, target_only, beam_trace, chain_arc	See collision modes. Conventional: bullets first_hit, lasers/snipers beam_trace, chain weapons chain_arc, swarm/AoE pierce_all.
Scaling curve	scalingCurve	linear, exponential, steep_exp, front_loaded, s_curve, linear_fast	See scaling curves. Default is linear. The curve remaps the L1→L20 progress and feeds every per-stat formula.
Area mode	areaMode	blast, blast_strong, chain_radius, beam_splash, beam_width, bonus_explosion, cone_width, blade_size, splash, line_spread, arc_thickness	See area modes. Drives how the player’s horizontal Area upgrade scales this weapon.

Unusual combinations (e.g. beam family with first_hit collision, or projectile with beam_trace) are not wired in the dispatch chain — they will fall through to the default branch and behave like a generic projectile. Pick a conventional pairing or plan on adding a dispatch case in step 6.

Step 2: Write the data file

Create one new file: src/starship-survivors/data/weapons/<weapon-id>.ts. Export a single const typed as WeaponCoreSpec. Use the existing weapons as the template: rifle.ts for a simple projectile, mortar.ts for a lobbed explosive, legendaries.ts for any merge-result weapon.

The full field list, with required/optional status and the default to use when unsure:

Field	Type	Required	Default	Purpose
weaponId	string	yes	—	Unique runtime key. Lowercase snake/kebab. Legendaries use lgd_ prefix.
name	string	yes	—	Display name in picker, ship screens, reward cards.
family	WeaponFamily	yes	—	See step 1.
damageTag	DamageTag	yes (de facto)	—	One of bullet/energy/bomb/fire.
secondaryDamageTag	DamageTag	legendaries only	—	Second tag for dual-tag artifact triggers.
damage_type	DamageType	no	'normal'	'true' = bypass shields.
isLegendary	boolean	no	false	Set on the 10 merge-result weapons; excludes them from chests.
mergeParents	[DamageTag, DamageTag]	legendaries only	—	Canonical (alphabetical) parent pair.
color1 / color2 / color3	string (hex)	yes	—	VFX core / glow / accent.
targetMode	TargetMode	yes	—	See step 1.
collisionMode	CollisionMode	yes	—	See step 1.
canHitDestructibles	boolean	yes	true	Whether the weapon damages destructible props.
acquireRange	WeaponStat	yes	—	Auto-aim search radius. { base, scaling } — base is L1 value, scaling is added per effective level.
travelRangeMult	number	yes	1.0	Projectile lifetime as a multiple of acquireRange. Higher = longer-lived shots.
warmupSec	number	yes	0.10	Charge time before first shot when weapon enters fire window.
damage	WeaponStat	yes	—	Per-hit damage at L1. Multiplied by the global getWeaponDamageMult(level) curve at fire time.
fireRate	WeaponStat	yes	—	Shots per second at L1.
fireRateJitter	number	no	0	Per-shot RNG on cooldown (0.20 = ±20%). Omit for deterministic cadence.
projectileCount	WeaponStat | SteppedStat	family-specific	—	Shots per fire event.
projectileSpeed	WeaponStat	family-specific	—	World units per second.
projectileSize	WeaponStat	family-specific	—	Visual + hit radius.
spreadDeg	number	no	0	Cone half-angle in degrees.
randomSpread	boolean	no	false	If true, spread is randomized per shot instead of evenly fanned.
perpendicularLayout	boolean	no	false	Lay shots out perpendicular to fire vector (cannon/revolver).
perpSpacing	number	no	—	Spacing between perpendicular shots in world units.
randomOffset	number	no	0	Spawn-position jitter in world units.
shellSpeedVariance	boolean	no	false	Adds per-shell speed RNG (mortar shells).
doubleShotChance	number	no	0	0–1 chance to fire twice per trigger.
detonateAtTarget	boolean	no	false	Attaches cannon_track behavior; round explodes at aim point regardless of collision.
scaleSpreadWithCount	boolean	no	false	Widens spread as projectileCount grows.
staggerDelaySec	number	no	0	Delay between simultaneous shots inside one fire event.
blastRadius	WeaponStat	explosives	—	Explosion radius in world units.
beamWidth	WeaponStat	beams	—	Beam half-thickness in world units.
beamLengthMult	number	beams	1.0	Beam length relative to acquireRange.
hideBeamLine	boolean	no	false	Suppress the visible beam render (hitscan-style flash only).
chainCount	SteppedStat	chain	—	Number of jumps per chain.
chainRadius	WeaponStat	chain	—	Jump search radius.
jumpDamageFalloff	number	chain	1.0	Multiplicative damage per jump (0.8 = 20% per hop).
homingStrength	WeaponStat	homing	—	Turn rate. Use 999 for hard-locked homing.
canRetarget	boolean	homing	false	Whether a homing shot picks a new target if its first dies.
behavior	WeaponBehavior	no	—	Override flight pattern. Must match a registered BulletBehavior id. See step 5.
returnSpeed	WeaponStat	boomerang_return	—	Return speed multiplier.
lingerSec	WeaponStat	linger	—	Persistence time for stationary zones.
orbitRadius	WeaponStat	orbit	—	Orbital radius around ship.
triggerRadius	WeaponStat	mines	—	Detonation proximity radius.
armSec	number	mines	—	Arming delay.
burstPattern	SteppedStat	burst_fire	—	Round-count steps per level.
maxActive	SteppedStat	linger / orbit	—	Cap on simultaneous active instances.
ringBurstCount	number	ring	—	Stars per ring (legacy).
ringBurstDelay	number	ring	—	Delay between ring spawns.
starCount	SteppedStat	orbit_ring	—	Stars per cast at each level bracket.
ringRadius	WeaponStat	orbit_ring	—	Formation radius (capped to 50% portrait width).
ringSpins	number	orbit_ring	3	Number of full revolutions before burst-out.
ringSpinDuration	number	orbit_ring	—	Spin-phase duration in seconds.
starStreamSpacingSec	number	orbit_ring	—	Delay between sequential star spawns.
starStreamSpeed	number	orbit_ring	—	Speed (px/s) of streamed stars toward formation slot.
ringBurstOutDist	WeaponStat	orbit_ring	—	Radial distance the ring expands before detonation.
beamDecaySec	number	beam_decay	2.0	Seconds the decaying beam persists.
beamDecayExplosions	SteppedStat	beam_decay	—	Cascade explosion count per level.
beamDecayBlastRadius	WeaponStat	beam_decay	—	Per-cascade-explosion radius.
artilleryTelegraphSec	number	artillery_rain	0.6	Telegraph circle visible time before impact.
artilleryStrikeRadius	WeaponStat	artillery_rain	—	Radial distance from ship the bombs land within.
arcTime	number	mortar/arc	—	Time of flight for lobbed shots in seconds.
arcHeightMult	number	mortar/arc	1.0	Arc peak height multiplier.
scatterRadius	WeaponStat	mortar/arc	—	Random scatter from aim point.
shellCount	SteppedStat	mortar/arc	—	Shells per fire event.
pullRadius	WeaponStat	gravity_mine	—	Gravity pull radius.
pullForce	WeaponStat	gravity_mine	—	Pull force magnitude.
rampBonus	number	laser	0	Damage ramp-up while sustaining a beam.
splashDmgPct	number	laser	0	Splash damage as fraction of primary damage.
emberCount	SteppedStat	flame	—	Ember count per fire event.
coneWidth	number	flame / cone_beam_dot	—	Cone half-angle in degrees.
contactCooldown	number	swords	—	Per-enemy hit cooldown for orbiting blades.
bladeCount	SteppedStat	swords	—	Active blade count per level.
bladeSize	WeaponStat	swords	—	Blade hitbox radius.
orbitSpeed	WeaponStat	swords	—	Angular velocity of blade orbit.
seekerCount	SteppedStat	revolver	—	Seeker count per fire event.
splashRadius	WeaponStat	revolver	—	Splash radius on seeker impact.
pelletCount	SteppedStat	shotgun	—	Pellets per shell.
dmgPerH	number	yes	0.04	Damage gain per horizontal Damage upgrade level.
ratePerH	number	yes	0.10	Fire-rate gain per horizontal Rate upgrade level.
areaMode	AreaMode	yes	—	See step 1.
cadencePattern	number[]	yes	[1]	Cadence mask used for audio + per-shot rhythm; 1 = play, 0 = skip.
cadenceStepSec	number	yes	0.0	Step interval for cadence pattern.
shipPulseStrength	number	yes	1.0	Ship-body pulse on fire.
sonarPulseScale	number	yes	1.0	Sonar overlay pulse scale on fire.
postFxSec	number	yes	0.08	Post-FX flash duration.
chimeTimbre	string	yes	—	Audio timbre key (glass, bronze, crystal, …).
recoilProfile	RecoilProfile	no	archetype default	{ sx, sy, dur, kick }.
fireShake	ShakeProfile	no	archetype default	{ amp, dur }. Subtle: amp 0.5–4 px, dur 0.05–0.15 s.
hitShake	ShakeProfile	no	archetype default	{ amp, dur }. Throttled engine-side.
bulletArchetype	string	no	inferred	Visual archetype id (e.g. pulse_ball, plasma_ball, mega_bullet).
firingGroup	boolean	no	true	If false, weapon fires solo (Phoenix, Plasma Mortar).
_alwaysForward	boolean	no	false	Force fire direction to ship facing regardless of target.
rarity	string	yes	'common'	Stored value is ignored at runtime — resolveWeaponRarity() flattens. Still required to typecheck.
disabled	boolean	no	false	Disabled weapons stay typed but never appear in pool.
defaultAngle	number	no	—	Override initial fire angle.
earlyLevelDamageBuff	{ maxBuff, endLevel }	no	—	Per-weapon override on top of the global low-level damage buff.

The designer never computes L10 or L20 values by hand. Each WeaponStat is { base, scaling }; _helpers.ts (getWeaponStatAtLevel, getEffectiveLevel, getSteppedStatAtLevel, getProbabilisticSteppedStat, getVfxTier, getWeaponDamageMult) resolves the value at runtime using the chosen scaling curve and the global damage anchors. The global damage curve anchors are:

Level	Multiplier
1	1.00
4	1.25
8	2.00
12	3.00
16	5.00
20	7.50

A low-level buff stacks on top: +30% at L1, decaying 5% per level, 0% at L7+. Legendaries skip the curve and ride at the L20 baseline (LEGENDARY_DAMAGE_BASELINE_MULT = 7.50) from L1.

Step 3: Register the weapon

Open src/starship-survivors/data/weapons/index.ts. Two edits:

1. Add the import alongside the other imports at the top: import { my_weapon } from './my-weapon';
2. Add the symbol to the WEAPONS array. Non-legendaries go in the main block; legendaries are spread in via ...LEGENDARY_WEAPONS (so legendary registration happens inside legendaries.ts instead — see step 4).

WEAPON_MAP and WEAPON_ORDER are built from WEAPONS at module load. No other registration is required for the weapon to appear in chests, in the picker, in getExtraProjectiles (only if you also add an entry to EXTRA_PROJ_TABLE), and in rarity color resolution.

If the weapon should receive bonus projectiles from the player’s horizontal more_projectiles upgrade, add a 21-entry array to EXTRA_PROJ_TABLE keyed on weaponId. The array is indexed by horizontal level 0–20.

Step 4: Add a legendary fusion (optional)

If the new weapon is the merge result of a level-20 pair, it goes in src/starship-survivors/data/weapons/legendaries.ts rather than its own file.

Required additions on the spec:

Field	Value
isLegendary	true
mergeParents	[tagA, tagB] in canonical (alphabetical) order via sortTagPair — bomb < bullet < energy < fire
damageTag	first parent tag
secondaryDamageTag	second parent tag
rarity	'legendary'

Then append the symbol to the LEGENDARY_WEAPONS array at the bottom of the file. LEGENDARY_PAIR_MAP is rebuilt from this array, so getLegendaryForPair will resolve the new pair automatically.

The 10 pairings are fully populated. To replace an existing legendary, swap the export; to add a brand-new dimension you must first add the new tag to the DamageTag and WeaponTag unions, which is out of scope of a routine weapon add.

Dual-tag inheritance: damage events fire signals for BOTH damageTag and secondaryDamageTag, so artifacts and effects keyed on either base tag trigger on legendary hits. See damage tags.

Step 5: Pick existing primitives first

The engine has the following BulletBehavior ids already wired in engine/weapons/bullets.ts. Pick one before considering custom code.

Behavior id	One-line summary
blink	Visual strobe; no gameplay change.
buzzsaw	Spinning blade, grows over time.
periodicRing	Emits a periodic AoE ring from the bullet’s position.
phaseAura	Damaging aura attached to the bullet.
toxicZone	Drops a damage-over-time ground zone.
mine	Stationary mine with proximity trigger.
homing	Tracks the closest target until expiry.
boomerang_return	Flies out then returns to ship.
linger_out	Outbound flight, then persistent linger at end position.
deploy_mine	Spawns a mine on death/expiry.
bounce	Reflects off bounds.
burst_fire	Multi-round burst from a single trigger.
empWave	Expanding EMP ring.
aoe_finish	AoE detonation on death.
cannon_track	Round detonates at aim point regardless of collision.
arc_mortar	Lobbed parabolic trajectory.
gravity_mine	Pull-radius + pull-force gravity well.
orbit	Orbits around the ship.
chain_sequential	Chains to N nearest enemies sequentially.
tesla_line	Connects ship to target with a damage beam.
cone_beam_dot	Persistent cone visual + damage hitbox (shader-driven).
shield_arc	Defensive arc in front of ship.
beam_linger	Beam that persists after the trace.
orbit_ring	Streamed stars form a ring, spin, then burst out.
beam_decay	Beam flash plus cascading explosions along its path.
artillery_rain	Telegraphed off-screen bombardment.
mega_bullet_trail	Brass-trail particles + slipstream behind slow rounds.
plasma_arc	Curved blue plasma arc projectile.
quad_burst	Four hitscan beams ≥30° apart per cast.
fire_trail	Drops fire damage zones along flight path.
phoenix_pulse	Periodic 360° fire pulse from ship.
plasma_mortar_trail	Trail particles for the plasma mortar shell.
plasma_mortar_land	Persistent damage zone where a plasma mortar lands.
plasma_fire_zone	Blue-fire damage zone variant.
carpet_bomber	Screen-pinned bomber sprites that drop firebomb lines.
fire_patch_zone	Generic fire-damage patch zone.

The archetype registry (engine/weapons/archetypes.ts) currently defines: projectile, beam, sniper, leech, field, melee, nova, vortex, chain, arc_wave, flamethrower, singularity, orbital, buzzsaw, void_tear, whip, bass_cannon, bubble, bug_gun, emp, missile. Each archetype carries capability flags (canExplode, canPierce, canBounce, canLeech, canSlow, canBurn) that gate modifier eligibility for the weapon family.

If one of these matches your weapon’s flight pattern, set behavior (and optionally bulletArchetype) on the spec and stop here.

Step 6: When you DO need custom behavior

Three places to touch, in this order:

1. New bullet behavior. Open engine/weapons/bullets.ts. Call BulletBehaviors.register(id, handler) next to the existing registrations. The handler implements BulletBehaviorHandler:

   Field	Type	Required	Purpose
   priority	number	no (default 0)	Order among multiple behaviors on the same bullet.
   update(b, dt, world, ship)	function	no	Called each frame the bullet exists.
   onHit(b, enemy, world, ship)	function	no	Called when the bullet collides with an enemy.
   onDeath(b, world, ship)	function	no	Called once when the bullet despawns.

   Bullets carry a _behaviors: string[] array; behaviors are invoked in registration order, gated by priority. update/onHit/onDeath are all optional — register only what your behavior needs. Then add the new id string to the WeaponBehavior union in data/weapons/_types.ts so specs can reference it.

2. New fire dispatch path. Open engine/weapons/weapons.ts and find WeaponManager.fire. The dispatch is a flat if (def.behavior === '...') { ... } else if (...) { ... } chain keyed on behavior (and sometimes collisionMode). Add a new branch in the same shape next to the existing ones. Do not introduce a new abstraction; the chain is intentionally flat so dispatch is grep-able.

3. New archetype. Open engine/weapons/archetypes.ts and call WeaponArchetypes.register(id, meta) where meta matches WeaponArchetypeMeta:

   Field	Type	Purpose
   damageType	string	Damage-type label (e.g. kinetic, energy, fire, gravity).
   entityType	string	bullet, hitscan, aoe, chain, cone.
   canExplode	boolean	Modifier eligibility for explosions.
   canPierce	boolean	Modifier eligibility for pierce.
   canBounce	boolean	Modifier eligibility for bounce.
   canLeech	boolean	Modifier eligibility for life-leech.
   canSlow	boolean	Modifier eligibility for slow.
   canBurn	boolean	Modifier eligibility for burn DoT.
   desc	string	One-line description.

   New archetypes are needed only when a weapon introduces a family-level capability mix that no existing archetype expresses (e.g. a hitscan with canExplode: true but canPierce: false — that pattern is the sniper archetype). When in doubt, reuse projectile.

Step 7: VFX, audio, and feel

Standard juice routes automatically: color1/2/3, shipPulseStrength, sonarPulseScale, postFxSec, chimeTimbre, recoilProfile, fireShake, hitShake, cadencePattern, cadenceStepSec. Fill those fields and the weapon picks up muzzle flash, hull squash, camera shake, sonar pulse, post-FX flash, and audio cadence.

Custom recipes (a new particle effect, a new shake pattern, a new chime timbre) follow the same registry-then-reference pattern as bullet behaviors. Register the recipe in its system module (particles, shake, audio), then reference it by id from the weapon spec. See the VFX and audio system pages for those registries. Do not inline a custom recipe at the weapon-spec level.

Step 8: Validate

The engine has no test harness for new weapons. Verification is in-game.

Minimal checklist:

Check	Expected
Weapon appears in the in-run weapon picker	Card shows correct name, color, rarity border.
Auto-aim respects targetMode	Fires at the right target class.
Per-stat scaling tracks expectations	L1 / L10 / L20 stats match base + scaling * (effectiveLevel - 1) under the chosen curve.
Legendary merge (if added) produces the right child	getLegendaryForPair(tagA, tagB) returns the new weaponId.
secondaryDamageTag (if legendary) triggers both-tag artifacts	Artifacts keyed on either parent tag activate on hit.
Horizontal modifiers scale the weapon	Damage, Rate, more-projectiles, Area each visibly affect the weapon.
No console errors during fire / hit / death	Clean run.

Custom-element structure rule

Any custom element MUST be registered through one of the engine registries — BulletBehaviors for flight/hit/death logic, WeaponArchetypes for family-level capability — rather than special-cased inline in weapons.ts. The only legitimate edit to weapons.ts for a new weapon is a new branch in the flat dispatch chain in WeaponManager.fire, and that branch should delegate to a registered behavior rather than do logic itself.

Custom elements live alongside their canonical siblings. A new bullet behavior goes in bullets.ts next to the existing BulletBehaviors.register('…', …) calls. A new archetype goes in archetypes.ts next to the existing WeaponArchetypes.register('…', …) calls. A new data spec goes in its own file under data/weapons/ next to rifle.ts. Do not create new directories, sub-modules, or abstraction layers for one-off weapons.