# 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.

- **Canonical page:** https://gamecrew.ai/techniques/pulse/deterministic-grid-puzzle-sweeps
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Pulse
- **Category:** gameplay
- **Tags:** `pulse`, `grid`, `puzzle`, `deterministic`, `sokoban`, `fixed-tick`, `movement`
- **Verification:** Compile-verified pattern

## 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**:
  $$\text{clear}(x, z) \iff \nexists e \in \text{GridCell} : (e.gx = x \land e.gz = z)$$
- **Smoothstep Fixed-Tick Slide ($u \in [0, 1]$)**:
  $$s(u) = 3u^2 - 2u^3, \qquad \mathbf{p}(u) = (1 - s(u))\mathbf{p}_{\text{start}} + s(u)\mathbf{p}_{\text{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`)

```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
