maze32/docs/MAZE_GENERATION.md

Maze generation and validation

Milestone 005 provides a portable, deterministic maze component. It does not implement movement, visibility projection, inventory, or match behavior from later milestones.

Representation and limits

• Dimensions are runtime configuration values. Supported maps are even-width, even-height rectangles from 8 x 8 through 32 x 32 and contain at most 1,024 cells.
• Each cell uses one byte of four-direction passage flags. A fixed bit set, traversal queue, and distance array form the reusable generation workspace.
• Starts, keys, boundary exits, compass cells, landmarks, and vision artifacts use bounded fixed arrays. No generation or validation path calls a heap API.
• The maze plus workspace budget is 64 KiB. The default 32 x 32 configuration targets generation within 250 ms on the ESP32-C6.
• Candidate regeneration is capped by maximum_attempts; failure returns a diagnostic result instead of retrying indefinitely.

Deterministic construction

The generator builds a seeded randomized depth-first tree in one conceptual half and rotates every opened edge by 180 degrees into the other half. It then adds a configured number of symmetric cycle edges and symmetric pairs of seam connections. This construction retains dead ends while guaranteeing cycles, alternative routes, and several ways to cross between halves once validation succeeds.

The requested seed and the derived candidate seed are recorded in the maze. Using the same configuration and requested seed therefore reproduces the same topology, placements, metrics, and hash.

Placement and validation

Player 2's start and every required object are the exact rotational counterpart of Player 1's placement. Starts and exits are boundary cells, and the default requires at least 22 cells of Manhattan separation between each start and its exit. Keys are selected outside the owners' initial Chebyshev-radius-three views. The default places two landmark pairs and one vision-artifact pair, with no placement collisions.

Validation independently checks reciprocal passages, rotational symmetry, full reachability, edge and cycle counts, dead ends, half crossings, placement bounds and collisions, initial key visibility, and corresponding route distances for keys, exits, compasses, every landmark, and every artifact. Reports expose these topology and route metrics for diagnostics and later playtesting; geometric distance alone is not treated as proof of search difficulty.