hull-hitboxes

hull-hitboxes.ts

Auto-generated convex-hull polygons used by Rapier physics bodies for every ship sprite. One entry per hull class, keyed '<Faction>_<Hull>'. Includes a runtime lookup with an octagon fallback and a one-shot diag log for missing entries.

Cross the River

Generated by scripts/generate-hull-hitboxes.ts from v5 ship sprite alpha channels. Each polygon is a convex hull of the alpha-channel boundary pixels, simplified to ~32 vertices via Visvalingam-Whyatt, normalized against the CONTENT bounding box (not the padded 1024x1024 canvas) so vertices span the full +/-0.9 unit range. Shrunk 5% for a tight-but-fair hitbox. Rotated -90 CW from sprite-south to engine-right convention.

File header reads DO NOT EDIT — regenerate via npx tsx scripts/generate-hull-hitboxes.ts.

Lethe — Exports

Symbol	Type	Purpose
HULL_HITBOXES	Record<string, [number, number][]>	Polygon table keyed by hull class
getHullHitbox(hullClass)	(string) => [number, number][]	Lookup with octagon fallback + one-time diag log

Internal (not exported):

Symbol	Type	Purpose
FALLBACK_HULL_OCTAGON	[number, number][]	8-vertex octagon at +/-0.9 range used when a hull is missing
_missingHitboxLogged	Set<string>	Dedupe set so each missing hull warns only once per session

Acheron — Hull Classes Defined

39 entries grouped by faction prefix:

Faction	Hulls
Ancients_	Glyph, Rune
Backwater_	Batwing, Caiman, Lizard, Toad
Industria_	Barracuda, Bigbot, Caravan, Digbot, Drillbot, Milita, Roughshod, Towncar
Junkrats_	Bombadier, Bumblebee, Drifter, Freightliner, Marco, Orca, Pierre, Tomahawk
Prism_	Citrine, Crystalis, Gator, Jade, Pearl, Ruby
Shark Patrol_	Cruiser, Hammerhead, Remora
Solaris_	Armada, Cargo, Extractor, Infiltrator, Longhauler, Oracle, Princess, Valet

Vertex counts range from 10 (Junkrats_Bumblebee, Backwater_Toad) to 33 (Solaris_Oracle). Most cluster in the 12-24 range.

Cocytus — Coordinate Convention

• Range: x and y in [-0.95, 0.95] (the 5% shrink from the source +/-1.0 sprite bounds).
• Origin: hull centroid (CONTENT bounding box center, not canvas center).
• Orientation: engine-right is +x. Sprites authored south-facing; data is pre-rotated -90 CW so callers do not re-rotate.
• Convex: all polygons are convex hulls — safe to feed Rapier collider builders that require convexity.

Styx — Fallback Behavior

FALLBACK_HULL_OCTAGON is a regular 8-vertex octagon spanning +/-0.9 (slightly tighter than the 0.95 range used by real entries). Same normalized space so callers do not branch on which kind of polygon they received.

Mandatory non-null return — without a hitbox, loop.ts force-resets ship position/velocity to (0,0) every frame and the ship is immobile. The fallback keeps the Rapier body alive at the cost of coarse collision until the data is regenerated.

Phlegethon — Missing-Hull Diagnostics

getHullHitbox logs each unknown hull class once per session:

1. Adds the hull to _missingHitboxLogged set.
2. console.warn with regeneration command.
3. Fire-and-forget dynamic-import of ../engine/telemetry/diag and logDiag with event_type: 'hull_hitbox_missing', level: 'warning', payload { hull }.
4. .catch(() => {}) swallows telemetry errors so missing hulls never block the gameplay path.

Browser-only — guarded by typeof window !== 'undefined' so SSR / Node test runs do not warn.

Avernus — Pipeline

v5 sprite alpha channel
  -> boundary pixel extraction
  -> convex hull
  -> Visvalingam-Whyatt simplification (~32 verts target)
  -> normalize against CONTENT bbox
  -> shrink 5%
  -> rotate -90 CW
  -> emit as HULL_HITBOXES[<faction>_<hull>] in this file

When sprite art changes or a new hull is imported: regenerate the file. Renames also require regeneration since the lookup key is the literal hull-class string.

Erebus — Callers

getHullHitbox is the single public consumer entry point — wraps the table to guarantee a non-null polygon.

EXTRACT-CANDIDATE

• FALLBACK_HULL_OCTAGON magnitude (0.9 vs 0.95 real entries): Not stated whether the discrepancy is intentional (looser fallback to avoid clipping) or an oversight. Source has no comment justifying the gap.
• Visvalingam-Whyatt target vertex count: Header says “~32 vertices” but observed range is 10-33. Whether the simplifier honors a hard cap or a tolerance threshold is in scripts/generate-hull-hitboxes.ts, not this file.
• Sprite version cadence: “v5 ship sprite” implies a versioning scheme. Where v5 is tracked and what triggers a version bump is not in this file.
• 'Shark Patrol_' prefix with a space: All other faction prefixes are single-word. Whether this is canonical or a sprite-naming artifact awaiting cleanup is unspecified here.