refactor: extract respawn landing effect suppression into a dedicated gate utility

Author: CoolSpring8

src/GameScene.ts

@@ -24,6 +24,12 @@ import {
   transitionTimings,
   SPAWN_WIPE_VISUALS,
 } from "./view/deathRespawn";
+import {
+  armRespawnEffectGate,
+  createRespawnEffectGate,
+  filterRespawnEffects,
+  resetRespawnEffectGate,
+} from "./view/respawnEffectGate";
 import { LightingSource, LightingSystem } from "./lighting/LightingSystem";
 
 interface RefillView {
@@ -113,6 +119,7 @@ export class GameScene extends Phaser.Scene {
   private refillEmitter!: Phaser.GameObjects.Particles.ParticleEmitter;
   private lighting!: LightingSystem;
   private spawnTransition: SpawnTransitionState | null = null;
+  private readonly respawnEffectGate = createRespawnEffectGate();
   private forceCameraUpdate = false;
   private forceCameraSnapNextFrame = true;
 
@@ -276,6 +283,7 @@ export class GameScene extends Phaser.Scene {
 
       let stepEffects = this.player.consumeEffects();
       const stepSnapshot = this.player.getSnapshot();
+      stepEffects = filterRespawnEffects(this.respawnEffectGate, stepSnapshot, stepEffects);
       const spike = this.world.collidesWithSpike(
         this.player.getHurtboxBounds(),
         stepSnapshot.vx,
@@ -525,8 +533,9 @@ export class GameScene extends Phaser.Scene {
   }
 
   private snapPlayerToCheckpoint(): void {
-    this.player.hardRespawn(this.spawnX, this.spawnY);
-    this.player.finalizeRespawnState();
+    this.player.resetStateAt(this.spawnX, this.spawnY);
+    this.player.syncStateAfterExternalMove();
+    armRespawnEffectGate(this.respawnEffectGate, this.player.getSnapshot());
     this.world.resetTransientState();
     this.syncRefillViews();
     this.controls.clearTransientState();
@@ -541,6 +550,7 @@ export class GameScene extends Phaser.Scene {
   private startSpawnTransition(
     state: Omit<SpawnTransitionState, "elapsed" | "totalDuration">,
   ): void {
+    resetRespawnEffectGate(this.respawnEffectGate);
     const totalDuration = baseTransitionDuration(state.kind);
     this.spawnTransition = {
       ...state,

src/player/Player.ts

@@ -113,7 +113,6 @@ export class Player extends Actor {
   private liftTimer = 0;
 
   private wasOnGround = false;
-  private suppressGroundedLandingEffects = false;
   private effects: PlayerEffect[] = [];
 
   private cfg: PlayerConfig;
@@ -164,9 +163,6 @@ export class Player extends Actor {
     this.frameDt = dt;
     this.input = input;
     this.refreshEnvironment();
-    if (this.suppressGroundedLandingEffects && !this.onGround) {
-      this.suppressGroundedLandingEffects = false;
-    }
     this.wallDustDir = 0;
 
     if (this.forceMoveXTimer > 0) {
@@ -284,9 +280,6 @@ export class Player extends Actor {
     this.moveV(mulFloat(this.vy, dt));
 
     this.refreshEnvironment();
-    if (this.suppressGroundedLandingEffects && !this.onGround) {
-      this.suppressGroundedLandingEffects = false;
-    }
     this.updateHairState(dt);
 
     this.wasOnGround = this.onGround;
@@ -372,7 +365,7 @@ export class Player extends Actor {
     this.liftTimer = toFloat(this.cfg.lift.momentumStoreTime);
   }
 
-  hardRespawn(x: number, y: number): void {
+  resetStateAt(x: number, y: number): void {
     this.x = x;
     this.y = y;
     this.vx = 0;
@@ -388,7 +381,6 @@ export class Player extends Actor {
     this.wallDir = 0;
     this.wallDustDir = 0;
     this.wasOnGround = false;
-    this.suppressGroundedLandingEffects = false;
 
     this.moveXInput = 0;
     this.jumpGraceTimer = 0;
@@ -441,10 +433,11 @@ export class Player extends Actor {
     this.stateMachine.forceState("normal");
   }
 
-  finalizeRespawnState(): void {
+  // Scene-managed teleports bypass the normal update loop, so collision-derived
+  // state needs an explicit refresh before normal simulation resumes.
+  syncStateAfterExternalMove(): void {
     this.refreshEnvironment();
     this.wasOnGround = this.onGround;
-    this.suppressGroundedLandingEffects = this.onGround;
     if (this.onGround) {
       this.jumpGraceTimer = toFloat(this.cfg.jump.graceTime);
     }
@@ -1610,12 +1603,7 @@ export class Player extends Actor {
       this.applyDashSlide(!this.dashStartedOnGround);
     }
 
-    if (
-      step > 0 &&
-      this.vy > 0 &&
-      this.stateMachine.state !== "climb" &&
-      !this.suppressGroundedLandingEffects
-    ) {
+    if (step > 0 && this.vy > 0 && this.stateMachine.state !== "climb") {
       const impact = clamp01Float(this.vy / this.cfg.gravity.fastMaxFall);
       this.emit({ type: "land", impact });
     }

src/view/respawnEffectGate.ts

@@ -0,0 +1,39 @@
+import { type PlayerEffect, type PlayerSnapshot } from "../player/types";
+
+export interface RespawnEffectGate {
+  suppressGroundedLandEffects: boolean;
+}
+
+export function createRespawnEffectGate(): RespawnEffectGate {
+  return {
+    suppressGroundedLandEffects: false,
+  };
+}
+
+export function resetRespawnEffectGate(gate: RespawnEffectGate): void {
+  gate.suppressGroundedLandEffects = false;
+}
+
+export function armRespawnEffectGate(
+  gate: RespawnEffectGate,
+  snapshot: Pick<PlayerSnapshot, "onGround">,
+): void {
+  gate.suppressGroundedLandEffects = snapshot.onGround;
+}
+
+export function filterRespawnEffects(
+  gate: RespawnEffectGate,
+  snapshot: Pick<PlayerSnapshot, "onGround">,
+  effects: PlayerEffect[],
+): PlayerEffect[] {
+  if (!gate.suppressGroundedLandEffects) {
+    return effects;
+  }
+
+  if (!snapshot.onGround) {
+    gate.suppressGroundedLandEffects = false;
+    return effects;
+  }
+
+  return effects.filter((effect) => effect.type !== "land");
+}

tests/model/respawn-effect-gate.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import {
+  armRespawnEffectGate,
+  createRespawnEffectGate,
+  filterRespawnEffects,
+} from "../../src/view/respawnEffectGate.ts";
+
+describe("Respawn effect gate", () => {
+  test("suppresses grounded landing effects until the player leaves the ground once", () => {
+    const gate = createRespawnEffectGate();
+    armRespawnEffectGate(gate, { onGround: true });
+
+    const groundedEffects = filterRespawnEffects(gate, { onGround: true }, [
+      { type: "land", impact: 1 },
+      { type: "jump" },
+    ]);
+
+    expect(groundedEffects).toEqual([{ type: "jump" }]);
+    expect(gate.suppressGroundedLandEffects).toBe(true);
+
+    const airborneEffects = filterRespawnEffects(gate, { onGround: false }, [
+      { type: "land", impact: 0.6 },
+    ]);
+
+    expect(airborneEffects).toEqual([{ type: "land", impact: 0.6 }]);
+    expect(gate.suppressGroundedLandEffects).toBe(false);
+  });
+
+  test("does not arm suppression when the player respawns airborne", () => {
+    const gate = createRespawnEffectGate();
+    armRespawnEffectGate(gate, { onGround: false });
+
+    const effects = filterRespawnEffects(gate, { onGround: true }, [
+      { type: "land", impact: 0.5 },
+    ]);
+
+    expect(effects).toEqual([{ type: "land", impact: 0.5 }]);
+    expect(gate.suppressGroundedLandEffects).toBe(false);
+  });
+});