Gridponder DSL — System Catalog

The ten built-in engine systems, their execution order, and the per-system configuration reference.

1. System Architecture

Execution Phases

Each system declares which phase(s) it participates in. During a turn, phases execute in this fixed order:

Events

Systems emit events as they modify state. Events accumulate during phases 2–4 and are consumed by rules during phase 5. See 05_rules.md for the full event catalog.

Interaction Protocol

Systems interact through:

1. Shared state — all systems read/write the board, avatar, and variables. Phase ordering determines visibility.
2. Events — systems emit events; rules (and some systems) react to them.
3. Phase ordering — a phase-3 system always sees state changes from phase 2.

Systems never call each other directly.

Config Override

Levels may override specific config fields per system via systemOverrides. Overrides are shallow-merged onto the game-level config.

2. System Catalog

2.1 avatar_navigation

Purpose: Move the avatar one step per move action. Enforce boundaries and solid collisions.

Phase: action_resolution

Events emitted: avatar_entered, avatar_exited, move_blocked

Config:

Behavior:

1. Compute target position from direction.
2. Check bounds — reject if out of grid.
3. Check ground layer — reject if void.
4. Check solid tag on objects layer:
   • "block": reject move.
   • "delegate": mark the move as pending. Emit move_blocked with the target position and blocker kind. Later phases (push) or rules (resolve_move effect) may complete or reject the pending move.
5. If not blocked, move avatar to target. Emit avatar_exited for old position, avatar_entered for new position.
6. Update avatar.facing to the movement direction.

2.2 push_objects

Purpose: Allow the avatar to push configured objects into adjacent empty cells.

Phase: movement_resolution

Events emitted: object_pushed, object_placed, avatar_entered, avatar_exited

Config:

Behavior:

1. When avatar movement targets a cell with an entity in the objects layer: a. Check toolInteractions in order. If any interaction matches (avatar holds the required item, entity has the required tag), destroy entity, optionally consume item, play animation if configured, move avatar. Skip remaining push logic. b. If entity is not pushable, movement fails. c. Compute push destination (one cell further in movement direction). c. Check push destination: must be in bounds, ground must have a validTargetTags tag, objects layer must be empty (or have matching tag if chainPush). d. If valid: move pushed object, then move avatar into vacated cell. e. If invalid: movement fails, avatar stays.
2. Emit object_pushed, object_placed for pushed object; standard avatar events.

2.3 portals

Purpose: Teleport avatar (or objects) between paired portal entities.

Phase: movement_resolution

Events emitted: avatar_entered, avatar_exited

Config:

Behavior:

1. When avatar enters a cell with a teleportTags entity: a. Read matchKey parameter (e.g., channel: "blue"). b. Find the paired portal with the same value. c. Move avatar to paired portal position. d. If endMovement: turn continues from portal position. If false: avatar continues moving in original direction.
2. If teleportObjects and an object is pushed onto a portal: teleport object similarly.

2.4 slide_merge

Purpose: Slide all mergeable tiles in the swipe direction; merge matching tiles.

Phase: action_resolution

Events emitted: tiles_slid, tiles_merged, cell_cleared

Config:

Behavior:

1. On action, determine slide direction from action params.
2. Process rows/columns in slide direction order.
3. Each mergeable tile slides until hitting a boundary, blocker, void, or another tile.
4. If tile meets another tile with matching mergePredicate: merge. New tile has mergeResult value.
5. Each tile can merge at most mergeLimit times per action.
6. Emit events for each slide and merge.

2.5 queued_emitters

Purpose: Release one item per turn from each multi-cell emitter whose exit cell is empty.

Phase: npc_resolution (runs once per turn, after all slides and cascades have settled)

Events emitted: item_released

Config:

Behavior — unidirectional pipe (no exit2Position):

1. Check whether the exit cell (exitPosition) and the spawn cell (one step in exitDirection) are both empty.
2. If both empty and the queue has remaining items: spawn the next item at the spawn cell, increment currentIndex, emit item_released.
3. Only one item is released per emitter per turn.

Behavior — bidirectional pipe (exit2Position present):

A bidirectional pipe has two open exits. Numbers occupy physical slots (cells) within the pipe. Initially, queue[0] is placed in cell 0 (the exit-1 cell), queue[1] in cell 1, and so on. The runtime state is stored in pipeSlots — an array of length pipe_length (one entry per cell, each int | null).

Each turn the pipe runs two phases:

1. Emit phase: For each exit, if an item occupies the exit cell and the exit's spawn cell is clear, emit it (place it on the board, set the slot to null). Both exits can emit simultaneously.

2. Move phase: Each remaining item moves one step toward its nearest exit:

   • Distance to exit 1 = cell index; distance to exit 2 = (pipe_length - 1) - cell index.
   • Closer to exit 1 → shift one cell toward exit 1 (index − 1).
   • Closer to exit 2 → shift one cell toward exit 2 (index + 1).
   • Equidistant (midpoint of an odd-length pipe):
     • If only exit 1 is clear → move toward exit 1.
     • If only exit 2 is clear → move toward exit 2.
     • If both clear or both blocked → stuck: no movement this turn.
   • An item arriving at an exit cell does not emit on the same turn — it exits on the next turn's emit phase.

Even vs. odd pipe length: In an even-length pipe every cell has a strictly nearer exit, so the stuck condition never arises. It is exclusive to odd-length pipes.

2.6 overlay_cursor

Purpose: Maintain a movable overlay region that region_transform operates on.

Phase: action_resolution

Events emitted: overlay_moved

Config:

Behavior:

1. On moveAction, shift overlay position in the action's direction.
2. If boundsConstrained, clamp to board boundaries.
3. If anchorToAvatar, overlay tracks avatar position automatically.
4. Update state.overlay.position.
5. Emit overlay_moved.

2.8 region_transform

Purpose: Apply spatial transformations (rotate, flip, diagonal swap) to cell contents within the overlay region.

Phase: action_resolution

Events emitted: region_rotated, region_flipped, cells_swapped

Config:

Each operation:

Example config:

{
  "overlaySystemId": "overlay",
  "affectedLayers": ["objects"],
  "operations": {
    "rotate": { "type": "rotate", "action": "rotate" },
    "flip": { "type": "flip", "action": "flip" },
    "swap": { "type": "diagonal_swap", "action": "diagonal_swap" }
  }
}

Operation: rotate

Rotates all cell contents within the overlay.

2×2 clockwise rotation:

[0,0] → [1,0]
[1,0] → [1,1]
[1,1] → [0,1]
[0,1] → [0,0]

3×3 clockwise (standard matrix rotation): [x,y] → [size-1-y, x]

Action params: { "rotation": "clockwise" } or { "rotation": "counterclockwise" }.

Operation: flip

Mirrors cell contents along an axis.

Vertical flip: [x, y] → [x, size-1-y] Horizontal flip: [x, y] → [size-1-x, y]

Action params: { "axis": "vertical" } or { "axis": "horizontal" }.

Operation: diagonal_swap

Swaps two diagonal corner cells based on direction.

Swap mapping (2×2 overlay at [ox, oy]):

Behavior:

1. On the configured action, determine the operation type.
2. For rotate/flip: collect all entities within the overlay bounds on affected layers, apply the spatial mapping, reposition.
3. For diagonal_swap: swap the two mapped cells.
4. Emit the corresponding event.

2.9 flood_fill

Purpose: Flood fill from a source position, changing connected same-kind/same-color cells.

Phase: action_resolution

Events emitted: cells_flooded

Config:

Behavior:

1. On floodAction, determine source position.
2. Read the entity at source position on affectedLayer.
3. Find all connected cells with the same match criterion (4-directional adjacency).
4. Apply the transformation (advance color in cycle, or transform kind).
5. Emit cells_flooded.

2.10 anchor_point

Purpose: Maintain a single movable anchor on the board. On the configured action: if no anchor entity exists, place one at the avatar's current position; if one exists, teleport the avatar to the anchor and remove it.

Phase: action_resolution

Events emitted: avatar_exited, avatar_entered (no direction field — ice_slide will not trigger a slide after teleport)

Config:

Behavior:

1. On the configured action, scan markerLayer for any entity of markerKind.
2. If none found: place markerKind at the avatar's current cell in markerLayer. No events emitted.
3. If found: check the objects layer at the marker cell. If any entity there has a blockedByTags tag, do nothing.
4. Otherwise: remove the marker, teleport avatar to the marker cell. Emit avatar_exited from the old position and avatar_entered at the new position (without a direction field in the payload).

Note on ice: The avatar_entered event emitted during teleport intentionally omits direction. The ice_slide cascade system skips events without a direction, so teleporting onto ice does not trigger a slide. Rules that react to avatar_entered (pickup, liquid, etc.) still fire normally since they do not require a direction.

Reuse: This system type is game-agnostic. Any game can use it with a different markerKind, markerLayer, and action to implement "save point", "recall beacon", "twin", or similar mechanics.

3. System Summary Table

Demoted to rule recipes (see 05_rules.md §9): single-slot inventory, consumable interactions, liquid transitions. These use the standard event–condition–effect primitives and no longer require dedicated engine systems.

4. System Combinations by Game Type

Flag-style games (avatar navigation puzzles)

avatar_navigation + push_objects + portals + inventory/consumable/liquid rule recipes

Sokoban-style games with recall mechanic

avatar_navigation + push_objects + anchor_point + object-on-target rule recipe

Number-style games (slide and merge)

slide_merge + queued_emitters + gravity (with sequence_match goal)

Number-style with diagonal swaps

slide_merge + overlay_cursor + region_transform (diagonal_swap op) (with sequence_match goal)

Transformation-style games (pattern matching)

overlay_cursor + region_transform (rotate + flip ops) + flood_fill

Hybrid games

Any combination of the above. The system architecture supports free composition as long as there are no conflicting action handlers.

5. Reserved System Types (v1+)

These types are reserved for future built-in systems:

• line_push — push entire rows/columns
• multi_slot_inventory — carry multiple items
• timers — turn-count-based triggers
• collectibles — collect N of M items
• rule_tiles — Baba-Is-You-style mutable rule objects
• rotate_flip_board — rotate/flip the entire board (not just an overlay region)
• spawners — periodic entity spawning