What it is
Zero-gravity space drift. Hold thrust and the ship accelerates along its facing angle, builds heat, and trails out at a tunable top speed; release thrust and drag pulls it back down. Slam into asteroids and you bounce a sliver and lose almost all your speed; slam into an enemy above the ram threshold and you punch through, dealing damage scaled to how fast you were going.
Thrust, drag, and speed cap
| Variable | Baseline value | Meaning |
|---|---|---|
| thrust | 130 | Acceleration applied per second along facing (or input direction for hovercraft). |
| maxSpeed | 95 | Top-speed ceiling (units/sec). |
| drag | 0.26 | Per-ship drag coefficient. |
| DRAG_BASE | 0.095 | Global drag scalar. |
| Drag step (exponential) | speed multiplied by max(0.001, 1 - drag × DRAG_BASE) per sim frame | Default coast behavior. |
| Speed-cap lerp rate | 10 | Rate at which over-cap speed is pulled back to the effective ceiling. |
| Absolute speed cap | 5000 units/sec | Hard ceiling no buff stack can exceed. |
| turnRate (baseline) | 0.14 rad/frame at 60 Hz | Max angular delta per sim frame; shortest-arc lerp toward input direction. |
| Stop speed threshold | 15 units/sec | Below this, stop-shake fires and stopSpringAmt relaxes drag. |
Acceleration curves
| accelCurve | Multiplier vs current speed fraction | Feel |
|---|---|---|
| linear | 1.0 flat | Predictable, racy. |
| ease_in | 0.4 at rest to 1.6 at top | Slow off the line, builds. |
| ease_out | 1.6 at rest to 0.4 at top | Punchy launch, plateaus. |
| instant | Velocity snaps directly to effective max | Arcade snap. |
Drag curves
| dragCurve | Behavior | Feel |
|---|---|---|
| linear | Constant brake rate per frame, independent of current speed | Boat-like slow coast. |
| exponential | Base multiplicative drag | Space drag (default). |
| front_loaded | Drag exponent 0.6 + 1.0 × speedFraction | Strong brake at high speed, eases at low; arcade car. |
| back_loaded | Drag exponent 0.6 + 1.0 × (1 - speedFraction) | Weak at high speed, strong at low; heavy cargo. |
| overshoot | Below 25% of max speed, drag is multiplied by 0.4 + 2.4 × speedFraction | Hovercraft glide, slips past zero. |
Heat
| Variable | Baseline value | Meaning |
|---|---|---|
| Heat range | 0 to 100 | Bar fills while thrusting, drains while coasting. |
| heatBuildup (heatBurnRate) | 12 | Per-ship gain multiplier. |
| heatCooldown (heatCoolRate) | 40 | Per-ship cool multiplier. |
| Accumulation curve | (0.10 + 0.55 × (1 - ln(1 + heatFrac × 12) / ln(13))) × 1.5 | Logarithmic; fast initial gain, slows as bar fills. |
| Asymptote dampener above 95% | Gain multiplied by (1 - dampT)², where dampT = (heat - 95) / 5 | Last 5% feels like pushing through molasses. |
| Floor gain past 95% | 0.3 heat/sec | Bar always creeps forward, eventually overheats. |
| Cooling acceleration ramp | +2.5/sec while not thrusting, cap 4× | Cooling ramps up the longer you coast. |
| Heat thrust boost | 1.0× at 0% heat to 1.35× at 99% heat (linear) | Same +35% applies to effective max speed cap. |
| Burnout trigger | heat reaches 100 | Stall begins. |
| Burnout HP damage | 16 × burnoutSeverity (baseline burnoutSeverity 0.35 → 5.6 HP) | Shield drops to 0 simultaneously. |
| Stall spin | 12 to 18 rad/sec, decays exponentially by factor 0.18^dt | Ship spins out. |
| Stall drag (per sim frame) | velocity × 0.88 | Hard deceleration during burnout. |
| Stall heat drain | heatCoolRate × 0.9 per sec | Stall ends when heat reaches 0. |
| heatShakeThreshold (baseline) | 0.85 (85% heat) | Above this, continuous camera shake. |
| heatShakeIntensity (baseline) | 0 | Per-ship amplitude; shake scales with over-threshold fraction. |
| stopShakeIntensity (baseline) | 0 | Camera shake when speed crosses down through stop threshold while not thrusting. |
| stopSpringAmt (baseline) | 0 | Below stop threshold, drag is weakened by stopSpringAmt × (1 - speed/threshold). |
External thrust boosts
| Source | Thrust + max-speed multiplier |
|---|---|
| Shooting-star trail buff | 1.30 |
| Star Power | 1.20 |
| Phoenix legendary aura | 1.20 |
| All boosts stack | Multiplicatively. |
Ramming
| Variable | Baseline value | Meaning |
|---|---|---|
| ramThreshold | 150 units/sec | Below this speed, contact is a push-apart bump (no ram damage). |
| ramDamageLo | 40 | Damage at ramThreshold. |
| ramDamageHi | 1000 | Damage at the high-speed end. |
| Ram damage interp end speed | 5000 units/sec | Top of the lerp; damage clamps here. |
| Ram damage formula | round((40 + t × 960) × meleeMult), t = clamp((speed - 150) / (5000 - 150), 0, 1) | Linear lerp scaled by meleeMult. |
| Speed bleed on ram | 1 - clamp(enemyMass / (shipMass + enemyMass), 0.15, 0.85) | Always lose at least 15%, keep at least 15%. |
| Ship class mass — light | 1.0 | Light ships bounce. |
| Ship class mass — medium | 2.0 | Default mass. |
| Ship class mass — heavy | 3.0 | Heavy ships plow. |
| Mass scaling | classMass × shipScale | Per-ship final mass. |
| Enemy mass scale | collision radius × 0.07 | Radius-30 enemy is mass ≈ 2.1. |
| Enemy knockback | 200 × (shipMass / totalMass) × min(2.0, shipSpeed/200) × dt × 60 | Mass-weighted, speed-scaled push. |
| T-bone forward arc | ±0.7 rad (≈ ±40°) from velocity heading | Ram inside this arc earns the T-BONED label. |
Terrain interactions
| Variable | Baseline value | Meaning |
|---|---|---|
| terrainRestitution (legacy bounce) | 1.09 | ~9% of incoming normal velocity reflected. |
| terrainFriction (tangential) | 0.01 | Minimal tangential drag on contact. |
| Rapier ship restitution | 0.09 | Bounce coefficient handed to Rapier collider. |
| Rapier ship friction | 0.01 | Surface friction handed to Rapier collider. |
| Sealed-arena walls — restitution | 0 | Walls absorb velocity, no bounce. |
| Sealed-arena walls — friction | 0 | No tangential drag. |
| Asteroid collision shape | Pixel-traced polygon from the baked visual | Collision matches the rendered outline. |
| Asteroid fallback shape | Bounding circle | Used only on the first frame before tracing. |
| Broadphase | Circle-circle on bounding radius | Cheap reject. |
| Narrowphase | SAT polygon vs ship hull polygon, or SAT polygon vs circle | Exact push-out. |
Rotation and fixed-facing ships
| Variable | Baseline value | Behavior |
|---|---|---|
| rotates | true | Ship angle lerps toward input angle at max turnRate per frame; thrust applies along ship.angle. |
| rotates | false | Ship angle stays fixed at fixedAngleDeg; thrust applies along the input direction (omnidirectional hovercraft). |
| fixedAngleDeg (baseline) | 0 (up) | Only used when rotates is false. |
| Turn squash | Up to 10% horizontal squash, mapped from smoothed angular velocity × 0.025 | Visual; fast attack, slow release. |
Physics tick
| Variable | Value | Meaning |
|---|---|---|
| Rapier fixed timestep | 1/60 sec | Physics steps at 60 Hz regardless of render rate. |
| Max accumulated time per frame | 0.1 sec (6 steps) | Cap prevents spiral-of-death on long frames. |
| Gravity | (0, 0) | Zero gravity world. |
| Ship body type | Dynamic, rotations locked, CCD enabled | Game sets velocity, Rapier solves collisions and position. |
| Terrain body type | Static (fixed) | Asteroids and floaters never move. |
| Enemy body type | Kinematic sensor, ball collider | Enemies report overlap but do not push the ship via Rapier. |
| Enemy sensor activation delay | 0.15 sec after spawn | Newly spawned enemies cannot collide with the ship for the first 0.15 sec. |
How it works (gameplay flow)
- Read input: thrust on or off, joystick angle becomes targetAngle.
- Rotate (if the ship rotates) toward targetAngle by up to turnRate × dt × 60 per frame, shortest-arc.
- If thrusting, add velocity along ship angle (or input angle for hovercraft) equal to thrust × heatBoost × trailBuff × starPower × phoenixBuff × accelCurveMultiplier × dt.
- Apply drag once per frame using the active drag curve.
- Clamp speed toward the effective max (maxSpeed × the same boost stack) via the speed-lerp; clamp absolutely at 5000 units/sec.
- Accumulate or drain heat depending on whether thrust is held; trigger burnout if heat reaches 100.
- Push final velocity to the Rapier body, step physics at fixed 1/60 sec, read corrected position back interpolated by the accumulator alpha.
- Resolve ship vs enemy contact: push apart by mass ratio, deal ram damage if speed is at or above ramThreshold, bleed ship speed, fire T-BONED label if the enemy was in the forward ±40° arc.
Interactions
- Ships: thrust, maxSpeed, drag, turnRate, dragCurve, accelCurve, heatBuildup, heatCooldown, burnoutSeverity, stopShakeIntensity, heatShakeIntensity, stopSpringAmt, terrainRestitution, terrainFriction, ramThreshold, ramDamageLo, ramDamageHi all come from the ship definition.
- Combat/ram: speed-scaled ram damage, mass-weighted knockback and bleed, T-bone bonus arc, meleeMult multiplier on ram damage.
- World/terrain: pixel-traced asteroid polygons, low-bounce surface response, sealed-arena walls absorb velocity completely.
- Weapons aim: rotation locked to input direction; angle is what weapons fire along on rotating ships.
- Buffs: Star Power boosts thrust and top speed and locks heat at 0; Shooting-star trail and Phoenix aura boost thrust and top speed while their timers are alive.
- Shield/invulnerability: tick alongside physics; shield regen has a delay phase and a background-fill phase; burnout zeroes shield and slams HP.
What it does NOT do
- Gravity. No wells, no falling, no orbital pull.
- Continuous angular velocity. Turning is a per-frame lerp toward targetAngle, not a torque-driven simulation.
- Bullet physics. Projectiles live on a separate spatial grid, not in the Rapier world.
- Enemy-on-enemy collision via Rapier. Enemy bodies are sensors against the ship only.
- Elastic bounces off terrain. Surface restitution is intentionally tiny (~9% reflected).
- Per-star stat scaling. A star-5 hull shares the same thrust, drag, heat, and ram numbers as star-1; differences come from installed mods.
- Drift on burnout. Stall uses a hard-coded 0.88 per-frame velocity multiplier rather than the per-ship drag curve.
- Friction on Star Power heat. Heat is forced to 0 for the entire duration; the bar does not accumulate or cool.