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:
- Zero Module-Level Mutable State: Store exact integer coordinates
(gx, gz)and flags (pushable,goal) directly on declared components (GridCell,SlideLerp) instead of globalletvariables orMaptables. - Event-Driven Turn Validation: Read
GridStepevents (dx,dz), scanquery(GridCell)for blockers and chained pushables, update integer coordinates atomically, and write smooth ease-out endpoints ontoSlideLerp. - 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.0so rapid key presses queue cleanly instead of straddling tiles.
Verification Checklist
- Compile with
pulse compileand verify zero unresolved-symbol or determinism lint errors. - 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
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.
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.
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.
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.