orbit/.pi/goals/combat-feedback-audit.md

Combat feedback — baseline audit (goal: make combat feel and read)

Scope: range = combat.html / /combat (js/combat/CombatScene.js), main game = index.html?combat (js/scenes/GameScene.js + js/combat/CombatSystem.js + js/ui/CombatBar.js). Shared: js/combat/{Combat, EnemyShip,Bullet,Fx}.js, data/combat.json.

What EXISTS today

VFX (both contexts, shared Fx.js: additive soft-dot flashes/rings/sparks, world-space, stepped in update)

• Player shot: muzzle flash (range 30 px / main 26 px, 110 ms)
• Enemy shot: muzzle flash (28 px, 100 ms)
• Bullet impact: pink flash on enemy hits, blue on player hits (130 ms)
• Player hit: generic white flash on the ship (60 px, 140 ms) — NOT distinct shield vs hull
• Enemy kill: Fx.explode (white core + color bloom + ring + 22 sparks)
• Player down: Fx.explode + range-only "SIGNAL LOST" center message (main game: no message)
• Player respawn: cyan flash
• Ram: white flash at contact midpoint
• Thrust glow dot (range only)

SFX

• Zero combat SFX in both contexts.
• Range loads NO audio at all (CombatScene.preload = textures only) → range SFX needs a load step.
• Main game loads all 17 files from data/sfx.json in GameScene.preload.
• Shared voice exists: playSfxOn(scene, name) / playSfxOneOfOn (js/utils/Sfx.js) with guards (sfx.enabled, sound manager, audio-cache check). No combat keys in data/sfx.json yet.
• Repurposable existing files (no new binaries): scan-01 (ping), ui_click/ui_hover (ticks), ui_window (whoosh), mining-02 (crack), thunder-01..04 (boom set), type-construct (build-up), type-deconstruct (collapse).

Readability / UI

• Range HUD: top-left armor panel (HULL/SHD bars + numbers), top-right KILLS counter, center message. No damage numbers, no kill feed, no target indicator, no bar hit-flash, no threat cues.
• CombatBar (main game): vertical SHD/HUL gauges (fill = level, updated each frame via setStats), 8 empty skill seats (cast() stub), ENR gauge (static full). No hit-flash, no numeric readout, no feed, no target read.
• CombatSystem hooks: onPlayerDamage / onPlayerDown / onPlayerUp / onKill / onActiveChange — GameScene wires ONLY onActiveChange (bar swap). The other four are available seams (currently null).
• Range has NO hooks at all — its damage/kill/down paths live inline in CombatScene.

Ship handling

• Range (WASD): CombatScene.updatePlayer applies combat.player rotSpeed 4.8 rad/s (instant rate cap), thrust 1500 px/s², brake 0.6×thrust (S/Down), maxSpeed 560 cap. Drag: combat.player.drag 1.6 is DEAD CONFIG — not read anywhere; effective drag is ship.drag 2.4 from data/ship.json via Ship.update.
• Main game: click-to-fly (Ship.js: ship.json thrust 900, maxSpeed 480, drag 2.4, rotSpeed 10) — mouse steers, combat adds auto-fire only. WASD not used there.
• No throttle ramp, no rotation smoothing — both feel instant/steppy (candidate micro-feel gaps).

Duplication (parity risk)

• fire/kill/respawn/damagePlayer logic is COPIED between CombatScene and CombatSystem (each has its own fx.flash calls, its own armor bookkeeping, its own respawn timers). Fx.js itself is shared.
• SFX wiring must go into BOTH copy sites (or a shared helper) to stay in sync.

Gaps vs success criteria (per feedback type)

Event	Range VFX	Main VFX	SFX (both)	Notes
Firing (player)	muzzle flash	muzzle flash	none	distinct sound needed
Firing (enemy)	muzzle flash	muzzle flash	none	(nice-to-have, distinct + quieter)
Bullet impact (enemy hit)	flash	flash	none	no damage number
Shield hit (player)	generic flash	generic flash	none	not distinct from hull hit
Hull hit (player)	generic flash	generic flash	none	not distinct; bar doesn't flash
Enemy kill	explode	explode	none	no kill feed
Player down	explode + msg	explode only	none	main game gives no down cue
Player respawn	flash	flash	none	none distinct

Readability item	Range	Main
Damage numbers (both sides)	missing	missing
Target/lock indicator	missing	missing (auto-fire target invisible)
Threat cues (hostile state)	missing	missing
Kill feed	KILLS counter only	missing
Bar hit-flash (SHD/HUL)	N/A (own HUD panel)	missing

Ground rules found in code (must keep)

• Pure rules in js/combat/Combat.js, tested by dev/combat.test.mjs (344 lines; stubs Phaser; covers applyDamage/headingOf/orbitStep/EnemyShip/Bullet/CombatSystem incl. auto-fire, swept hits, rams, respawn, cast-stub). New pure feel rules belong there + tested.
• Fx items are world-space additive dots; combat scene steps fx.update(delta) in its loop.
• No arcade colliders; swept circle checks (hitsSwept) in both contexts.
• All numbers in data/combat.json; CombatBar built like ActionBar (scene.add.* + container parenting).
• data/sfx.json key = play name, asset queued sfx_<key>; sfx.enabled master switch.
• Theme palette: neon #00e5ff, neon2 #ff2d6f, amber #ffc94d, ink #eaf6ff, dim #7d92c4, faint #3d4c74.