GameCrew AIEarly access
Sign in
PulsegameplayCompile-verified pattern

Deterministic Grid Push-Block & Tile Sweeps in Pulse

Deterministic grid-based puzzle sweeps in Pulse using integer cell components, per-entity occupancy scans, and smooth fixed-tick interpolation.

  • pulse
  • grid
  • puzzle
  • deterministic
  • sokoban
  • fixed-tick
  • movement

When to Use & Field Best Practices

Discrete tile and push-block puzzles break determinism quickly when state lives in module-level JavaScript arrays or floats drift off-grid after dozens of pushes:

  1. Zero Module-Level Mutable State: Store exact integer coordinates (gx, gz) and flags (pushable, goal) directly on declared components (GridCell, SlideLerp) instead of global let variables or Map tables.
  2. Event-Driven Turn Validation: Read GridStep events (dx, dz), scan query(GridCell) for blockers and chained pushables, update integer coordinates atomically, and write smooth ease-out endpoints onto SlideLerp.
  3. Snap Position From Integer Grid State: Compute world positions cleanly as (gx * tile_m, y, gz * tile_m) at the end of every slide so 1,000 consecutive moves never accumulate floating-point drift.

Mathematical & Algorithmic Core

  • Atomic Push Check: $clear(x, z) iff nexists e ∈ GridCell : (e.gx = x land e.gz = z)$
  • Smoothstep Fixed-Tick Slide (u ∈ [0, 1]): $s(u) = 3u^2 - 2u^3, p(u) = (1 - s(u))p_start + s(u)p_target$

Engine Implementation

1. Contract Declarations

Declare via pulse_declare:

  • "component GridCell { gx: int=-64..64=0, gz: int=-64..64=0, pushable: int=0..1=0, goal: int=0..1=0 }"
  • "component SlideLerp { timer_s: num=0.0, sx: num=0.0, sz: num=0.0, tx: num=0.0, tz: num=0.0 }"
  • "event GridStep { actor: sym, dx: int=-1..1=0, dz: int=-1..1=0 }"

2. Deterministic Grid Sweep & Interpolation System (systems/grid-sweep.ts)

import { events, query, system, teleport, vfx } from "pulse";
import { GridCell, GridStep, SlideLerp } from "../contracts/core";

const TILE_SIZE_M = 2.0;
const SLIDE_DURATION_S = 0.14;

export const gridSweepSystem = system("grid-sweep", { after: "physics" }, (dt) => {
  const cells = query(GridCell);

  for (const ev of events(GridStep)) {
    const actor = cells.find((c) => c.id === ev.actor);
    if (!actor || !actor.has(SlideLerp)) continue;
    if (actor.slideLerp.timer_s > 0.0) continue;

    const dx = Math.sign(ev.dx);
    const dz = Math.sign(ev.dz);
    if ((dx === 0 && dz === 0) || (dx !== 0 && dz !== 0)) continue;

    const nx = actor.gridCell.gx + dx;
    const nz = actor.gridCell.gz + dz;
    const blocker = cells.find((c) => c.gridCell.gx === nx && c.gridCell.gz === nz);

    if (blocker) {
      if (blocker.gridCell.pushable === 0 || !blocker.has(SlideLerp)) continue;
      const px = nx + dx;
      const pz = nz + dz;
      const behind = cells.find((c) => c.gridCell.gx === px && c.gridCell.gz === pz);
      if (behind) continue;

      blocker.gridCell.gx = px;
      blocker.gridCell.gz = pz;
      blocker.slideLerp.sx = blocker.pos.x;
      blocker.slideLerp.sz = blocker.pos.z;
      blocker.slideLerp.tx = px * TILE_SIZE_M;
      blocker.slideLerp.tz = pz * TILE_SIZE_M;
      blocker.slideLerp.timer_s = SLIDE_DURATION_S;
      vfx("spark", { pos: [blocker.pos.x, blocker.pos.y + 0.25, blocker.pos.z], count: 8 });
    }

    actor.gridCell.gx = nx;
    actor.gridCell.gz = nz;
    actor.slideLerp.sx = actor.pos.x;
    actor.slideLerp.sz = actor.pos.z;
    actor.slideLerp.tx = nx * TILE_SIZE_M;
    actor.slideLerp.tz = nz * TILE_SIZE_M;
    actor.slideLerp.timer_s = SLIDE_DURATION_S;
  }

  for (const e of query(GridCell, SlideLerp)) {
    const slide = e.slideLerp;
    if (slide.timer_s <= 0.0) continue;
    slide.timer_s = Math.max(0.0, slide.timer_s - dt);
    const u = 1.0 - slide.timer_s / SLIDE_DURATION_S;
    const smooth = u * u * (3.0 - 2.0 * u);
    const wx = slide.sx + (slide.tx - slide.sx) * smooth;
    const wz = slide.sz + (slide.tz - slide.sz) * smooth;
    teleport(e, [wx, e.pos.y, wz]);
  }
});

Determinism & Replay Safety

  • No Module Globals: Every grid cell and active tween sits inside ECS component memory so snapshot rollbacks and deterministic headless replays produce byte-identical board states.
  • Cardinal Guard: Reject diagonal or mid-slide step events while timer_s > 0.0 so rapid key presses queue cleanly instead of straddling tiles.

Verification Checklist

  1. Compile with pulse compile and verify zero unresolved-symbol or determinism lint errors.
  2. Replay a multi-push scenario and confirm final block coordinates match exact integer multiples of TILE_SIZE_M.

Official references

  • Alan Hazelden (Draknek — Sokoban Move Resolution)
  • GameCrew Pulse Determinism & State Reference

More Pulse techniques

atmosphere

Atmospheric Vistas, Volumetric Clouds & Deterministic Feel in Pulse →

Composing Pulse physical sky, volumetric clouds, volumetric fog, water/foliage, and pure component-backed spring feel without violating sandboxed tick determinism.

ai

Deterministic ECS Enemy Brains, Encounter Directors & Telegraphed Bosses in Pulse →

Data-oriented Pulse ECS enemy perception, orbit steering, attack-token encounter pacing, and multi-phase telegraphed boss state machines verified with headless pulse_run invariants.

ai

Deterministic Telegraphed Boss Phases in Pulse →

Deterministic multi-phase boss telegraphing in Pulse with integer phase state, ground ring vfx, rand() jitter, and fixed-tick shockwaves.

animation

Procedural Gait, Chain Motion & Readable Impact VFX in Pulse →

Expressive creature locomotion and impact readability in Pulse using ProceduralMotion, ProceduralGait, ProceduralChain, deterministic hit-flash/recoil components, and layered vfx bursts.

Use verified techniques inside a real game

Describe your game idea for free or connect an MCP assistant to search and contribute techniques.

Learn about collaboration