feat: implement dynamic spawn transition sequences and grounded spawn point resolution

Author: CoolSpring8

src/GameScene.ts

@@ -1,6 +1,7 @@
 import { PLAYER_GEOMETRY, WORLD } from "./constants";
 import { EntityWorld } from "./entities/EntityWorld";
 import { type Aabb, LevelEntitySpec, SpikeDirection } from "./entities/types";
+import { resolveGroundedSpawnPoint } from "./spawn";
 
 export type RoomDirection = "left" | "right" | "up" | "down";
 
@@ -48,8 +49,8 @@ const ROOM_BLUEPRINTS: readonly LevelRoomBlueprint[] = [
       "XXXXX...................................",
       "XXXXX...................................",
       "XXXXX.....................XXXX..........",
-      "XXS.....................................",
       "XX......................................",
+      "XXS.....................................",
       "XXXXXXXX................................",
       "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
       "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
@@ -84,9 +85,9 @@ const ROOM_BLUEPRINTS: readonly LevelRoomBlueprint[] = [
       "...................................XXXXX",
       "...................................XXXXX",
       "...................................XXXXX",
-      "S..................................XXXXX",
       "...................................XXXXX",
-      "......................XXXXXXX......XXXXX",
+      "...................................XXXXX",
+      "S.....................XXXXXXX......XXXXX",
       "XXXXXXXXXXXXXXXXXX...XXXXXXXXXXXXXXXXXXX",
       "XXXXXXXXXXXXXXXXXX...XXXXXXXXXXXXXXXXXXX",
       "XXXXXXXXXXXXXXXXXX...XXXXXXXXXXXXXXXXXXX",
@@ -121,8 +122,8 @@ const ROOM_BLUEPRINTS: readonly LevelRoomBlueprint[] = [
       "XXXX...........XXXXXXXX...XXXXXXX..................XXXX",
       "XXXXX..........XXXXXXXX......XXXX.............=====XXXX",
       "XXXXX..........XXXXXXXX.....XXXXX..................XXXX",
-      "XXXXXS.........XXXXXXXX............................XXXX",
-      "XXXXX..........XXXXXXXX...XXXXXXX..................XXXX",
+      "XXXXX..........XXXXXXXX............................XXXX",
+      "XXXXXS.........XXXXXXXX...XXXXXXX..................XXXX",
       "XXXXXXXXX^^^^^^XXXXXXXX^^^XXXXXXX.......XXXX.......XXXX",
       "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.......XXXX",
       "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX^^^^^^^XXXX",
@@ -142,8 +143,8 @@ const ROOM_BLUEPRINTS: readonly LevelRoomBlueprint[] = [
       "X.......................................XXXXX",
       ".......^^^^^^^^^^^^^^^^^^...............XXXXX",
       ".......XXXXXXXXXXXXXXXXXX...............XXXXX",
-      "S.......................................XXXXX",
       "........................................XXXXX",
+      "S.......................................XXXXX",
       "XX....................................XXXXXXX",
       "XX....................................XXXXXXX",
       "XX........XXXXXXX...................XXXXXXXXX",
@@ -186,7 +187,7 @@ export function buildLevelFromBlueprints(
   const spawnInsetX = Math.floor((WORLD.tile - PLAYER_GEOMETRY.hitboxW) * 0.5);
   let worldCols = 0;
   let worldRows = 0;
-  let startCheckpoint: { x: number; y: number } | null = null;
+  let startRoomId: string | null = null;
   let hasExplicitInitialSpawn = false;
 
   for (const blueprint of blueprints) {
@@ -214,10 +215,10 @@ export function buildLevelFromBlueprints(
         if (ch === "S") {
           checkpoint ??= {
             x: col * WORLD.tile + spawnInsetX + PLAYER_GEOMETRY.hitboxW * 0.5,
-            y: row * WORLD.tile + PLAYER_GEOMETRY.hitboxH,
+            y: row * WORLD.tile + WORLD.tile,
           };
-          if (!hasExplicitInitialSpawn) {
-            startCheckpoint ??= checkpoint;
+          if (!hasExplicitInitialSpawn && startRoomId === null) {
+            startRoomId = blueprint.id;
           }
           continue;
         }
@@ -258,7 +259,7 @@ export function buildLevelFromBlueprints(
       if (checkpoint === null) {
         throw new Error(`Room "${blueprint.id}" is marked as the initial spawn room but has no checkpoint`);
       }
-      startCheckpoint = checkpoint;
+      startRoomId = blueprint.id;
       hasExplicitInitialSpawn = true;
     }
 
@@ -273,15 +274,27 @@ export function buildLevelFromBlueprints(
     });
   }
 
-  if (startCheckpoint === null) {
+  if (startRoomId === null) {
     throw new Error("Level requires at least one room checkpoint marked with 'S'");
   }
 
+  const world = EntityWorld.fromSpecs(worldCols, worldRows, entities);
+  const resolvedRooms = rooms.map((room) => ({
+    ...room,
+    checkpoint: room.checkpoint === null
+      ? null
+      : resolveGroundedSpawnPoint(world, room.bounds, room.checkpoint),
+  }));
+  const startRoom = resolvedRooms.find((room) => room.id === startRoomId);
+  if (startRoom?.checkpoint === null || startRoom === undefined) {
+    throw new Error(`Resolved initial spawn room "${startRoomId}" has no checkpoint`);
+  }
+
   return {
-    world: EntityWorld.fromSpecs(worldCols, worldRows, entities),
-    rooms,
-    spawnX: startCheckpoint.x,
-    spawnY: startCheckpoint.y,
+    world,
+    rooms: resolvedRooms,
+    spawnX: startRoom.checkpoint.x,
+    spawnY: startRoom.checkpoint.y,
   };
 }
 

src/level.ts

@@ -113,6 +113,7 @@ export class Player extends Actor {
   private liftTimer = 0;
 
   private wasOnGround = false;
+  private suppressGroundedLandingEffects = false;
   private effects: PlayerEffect[] = [];
 
   private cfg: PlayerConfig;
@@ -163,6 +164,9 @@ 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) {
@@ -280,6 +284,9 @@ 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;
@@ -381,6 +388,7 @@ export class Player extends Actor {
     this.wallDir = 0;
     this.wallDustDir = 0;
     this.wasOnGround = false;
+    this.suppressGroundedLandingEffects = false;
 
     this.moveXInput = 0;
     this.jumpGraceTimer = 0;
@@ -433,6 +441,15 @@ export class Player extends Actor {
     this.stateMachine.forceState("normal");
   }
 
+  finalizeRespawnState(): void {
+    this.refreshEnvironment();
+    this.wasOnGround = this.onGround;
+    this.suppressGroundedLandingEffects = this.onGround;
+    if (this.onGround) {
+      this.jumpGraceTimer = toFloat(this.cfg.jump.graceTime);
+    }
+  }
+
   get state(): PlayerState {
     return this.stateMachine.state;
   }
@@ -1593,7 +1610,12 @@ export class Player extends Actor {
       this.applyDashSlide(!this.dashStartedOnGround);
     }
 
-    if (step > 0 && this.vy > 0 && this.stateMachine.state !== "climb") {
+    if (
+      step > 0 &&
+      this.vy > 0 &&
+      this.stateMachine.state !== "climb" &&
+      !this.suppressGroundedLandingEffects
+    ) {
       const impact = clamp01Float(this.vy / this.cfg.gravity.fastMaxFall);
       this.emit({ type: "land", impact });
     }

src/player/Player.ts

@@ -0,0 +1,58 @@
+import { PLAYER_GEOMETRY, WORLD } from "./constants";
+import type { CollisionWorld } from "./entities/CollisionWorld";
+import type { Aabb } from "./entities/types";
+
+export interface SpawnPoint {
+  x: number;
+  y: number;
+}
+
+export function resolveGroundedSpawnPoint(
+  world: CollisionWorld,
+  roomBounds: Aabb,
+  authored: SpawnPoint,
+): SpawnPoint {
+  const maxSearch = Math.max(roomBounds.h + WORLD.tile, PLAYER_GEOMETRY.hitboxH + WORLD.tile);
+  let fallback: SpawnPoint | null = null;
+
+  for (let delta = 0; delta <= maxSearch; delta++) {
+    const candidates = delta === 0
+      ? [authored.y]
+      : [authored.y + delta, authored.y - delta];
+
+    for (const y of candidates) {
+      const candidate = { x: authored.x, y };
+      if (!spawnFits(world, candidate)) {
+        continue;
+      }
+
+      if (isGroundedSpawn(world, candidate)) {
+        return candidate;
+      }
+
+      fallback ??= candidate;
+    }
+  }
+
+  return fallback ?? authored;
+}
+
+function isGroundedSpawn(world: CollisionWorld, point: SpawnPoint): boolean {
+  const bounds = spawnBounds(point);
+  return world.probeGround(bounds.x, bounds.y, bounds.w, bounds.h).onGround;
+}
+
+function spawnFits(world: CollisionWorld, point: SpawnPoint): boolean {
+  const bounds = spawnBounds(point);
+  return !world.collideSolidAt(bounds.x, bounds.y, bounds.w, bounds.h) &&
+    !world.collidesWithSpikeAt(bounds.x, bounds.y, bounds.w, bounds.h, 0, 0);
+}
+
+function spawnBounds(point: SpawnPoint): Aabb {
+  return {
+    x: point.x - PLAYER_GEOMETRY.hitboxW * 0.5,
+    y: point.y - PLAYER_GEOMETRY.hitboxH,
+    w: PLAYER_GEOMETRY.hitboxW,
+    h: PLAYER_GEOMETRY.hitboxH,
+  };
+}