sprite-orientation

PURPOSE

Single shared constant that bridges the gap between game-space angles (where ship.angle = 0 points east) and sprite-space rotation (where ship PNGs are authored facing south). Any renderer that draws a ship sprite or its derivative (shadow, aura pass) adds this offset to the entity’s angle so the sprite’s visual nose aligns with the entity’s forward direction.

OWNS

• SPRITE_FORWARD_OFFSET — radians added to a ship’s game-space angle to produce the sprite’s screen rotation. Value is -π/2, matching the v4 art standard of south-facing ship PNGs.

READS FROM

• Nothing. Pure constant module — no imports, no runtime state, no config lookups.

PUSHES TO

• Nothing directly. Exposes the constant for consumers to add into their own rotation calculations.

DOES NOT

• Does not rotate sprites itself — leaves the actual transform to the renderer (sprite batch, canvas blit, WebGL pass).
• Does not handle per-sprite overrides — every consumer that uses this offset assumes the v4 south-facing PNG convention. Sprites authored under a different convention need their own offset, not this one.
• Does not account for entity facing modes other than ship.angle (projectiles, pickups, FX use their own rotation logic and do not import this constant).
• Does not normalize the resulting angle into [-π, π] — downstream rendering tolerates arbitrary radians.

Signals

• None. No emit, no subscribe — this is a leaf constant module.

Entry points

• SPRITE_FORWARD_OFFSET — imported by engine/bridge.ts in three ship-rendering paths:
  • Ship shadow draw via the all-enemies sprite batch.
  • Player aura cached-pass rotation (_playerPassRot).
  • Per-frame WebGL ship-sprite blit rotation.

Pattern notes

• The art convention is the load-bearing contract here. The header comment records that pre-v4 sprites faced north and used +π/2; the current -π/2 value tracks south-facing v4 sprites. Re-authoring ship sprites in a new orientation means flipping this constant, not editing every call site.
• Keeping the offset in a dedicated module (rather than inlining a magic number in bridge.ts) means the ship shadow, the cached aura pass, and the live WebGL blit cannot drift out of sync — they all read the same source of truth.
• Consumers add the offset to ship.angle rather than baking it into stored state, so gameplay code can continue to reason about angles in game-space (0 = east) without sprite-orientation concerns leaking in.
• The constant is scoped to ship sprites specifically. Other rotating sprites (enemies, props) live under their own atlas-builder pipeline and apply rotations via different paths.