MazeRunner // x86-64 Assembly Engine

▼ DOWNLOADS & GITHUB RELEASES

Win64 Binary & Vector SVG

MazeRunner v1.0.0 Release

Standalone x86-64 Win64 Executable (~25 KB) + Self-running SMIL SVG Visualizer

Freestanding Bin Zero CRT MIT License

Download Release GitHub Repository

mazerunner.exe

Native x86-64 assembly binary

mazerunner.svg

Self-animating vector export

scripts/build.ps1

One-step build & SVG generator

▼ SYSTEM OVERVIEW & GENERATION PIPELINE

Freestanding Win64 Binary

MAZERUNNER // Single x86-64 Assembly Source File

Linking kernel32.dll + user32.dll only (Zero C Runtime Overhead)

1. GENERATE

Carves a 65 × 23 grid into a perfect acyclic maze.

├── Randomized DFS ├── Prim's Frontier └── Kruskal's DSU

2. SOLVE

Finds provably shortest path from S(1,1) to G(21,63).

├── BFS Wavefront O(V+E) └── DFS Comparison Solver

3. VISUALIZE

Renders 24-bit terminal frames via single write buffer.

├── Predecessor Gold Path ├── Live Microsecond HUD └── Sparkline Graph Engine

▼ MAZERUNNER .bss SECTION MEMORY LAYOUT (~125 KB)

Hover to highlight matching buffer card

CONTIGUOUS STATIC MEMORY MAP (0x00000 ──► 0x210A0):

[0x00000] maze 2 KB

Cell grid (1=wall, 0=pass)

[0x00800] visual_state 2 KB

Render state (0..5)

[0x01000] predecessor 8 KB

BFS parent map / visited

[0x03000] queue 8 KB

BFS circular FIFO queue

[0x05000] search_trace 8 KB

BFS expansion order

[0x07000] solution_path 8 KB

Reconstructed optimal path

[0x09000] carve_stack 8 KB

DFS stack / Prim frontier

[0x0B000] frame_buffer 64 KB

ANSI terminal render buffer

[0x1B000] distance 8 KB

BFS depth (heatmap)

[0x1D000] dfs_path 8 KB

DFS solver path

[0x1F000] dfs_trace 8 KB

DFS expansion trace

[0x21000] frontier_history 160 B

Int32[40] sparkline samples

▼ COMMANDS & CLI CONTROL REGISTRY

build.ps1 & mazerunner.exe flags

# Build & Launch Instant Maze Solve Mode .\scripts\build.ps1 -Run -Instant

# Build & Export Animated Vector SVG Visualizer .\scripts\build.ps1 -SVG

# Launch with 16-Color Distance Heatmap Mode .\build\mazerunner.exe --heatmap

# Carve Maze Using Prim's Frontier Algorithm .\build\mazerunner.exe --algo prim

# Carve Maze Using Kruskal's DSU Algorithm .\build\mazerunner.exe --algo kruskal

# Interactive Player Mode (WASD / Arrow Keys at ~33 Hz) .\build\mazerunner.exe --play

▼ WIN64 API SURFACE & STACK ARCHITECTURE

13 Dynamic DLL Imports

KERNEL32.DLL (12 Imports)

• Terminal I/O: GetStdHandle, GetConsoleMode, SetConsoleMode, SetConsoleOutputCP, SetConsoleTitleA, GetCommandLineA, WriteFile

• Timing & Sound: QueryPerformanceCounter, QueryPerformanceFrequency, Sleep, Beep

• Process: ExitProcess

USER32.DLL (1 Import)

• Input Polling: GetAsyncKeyState

Used to poll arrow keys & keypresses at ~33 Hz loop frequency in interactive --play mode.

STACK FRAME & ENTRY POINT ARCHITECTURE

maze_entry (Linker Entry)

➔

and rsp, -16 (16-Byte Align)

➔

sub rsp, 48 (Shadow Space)

• Alignment: and rsp, -16 enforces Win64 ABI 16-byte stack boundary requirement.
• Shadow Space: 32 bytes allocated for RCX/RDX/R8/R9 home locations + 16-byte stack space.

▼ GRID GEOMETRY & COORDINATE MAPPING

Flat 1D Array (65 × 23 = 1,495 Cells)

Row 0
[ WALL BORDER ]

Row 1, Col 1
START CELL (Idx 66)

Row 1, Col 63
ROOM (Idx 127)

Row 21, Col 63
GOAL CELL (Idx 1428)

Row 22
[ WALL BORDER ]

ADDRESSING & GEOMETRY RULES

• Index Calculation: Index = (row × MAZE_W) + col
• Hardware Div: Decoupled to (row, col) via hardware div instruction
• 352 Rooms: Odd Coordinates (odd_row, odd_col) - 11 Rows × 32 Cols
• Walls: Even Coordinates positioned between adjacent rooms

▼ MAZE SOLVERS ARCHITECTURE (BFS vs DFS)

Dual Solver Engine

BFS (Primary Shortest Path)

Data Structures:

• queue[] : Circular Queue
• predecessor[] : Parent Map
• distance[] : Heatmap Depth
• search_trace[] : Expansion Trace

O(V + E) Shortest Path Guarantee

DFS (Comparison Solver)

Data Structures:

• carve_stack[] : Explicit Stack
• predecessor[] : Visited Set
• dfs_trace[] : Expansion Order
• dfs_path[] : Final Route

Visually proves BFS optimality

▼ PRNG (XORSHIFT32) & HIGH-RESOLUTION TIMING

QueryPerformanceCounter

XORSHIFT32 PRNG BITWISE SHIFT PIPELINE

QPC Start Seed

➔

state ^= state << 13

➔

state ^= state >> 17

➔

state ^= state << 5

HIGH-RESOLUTION MICROSECOND TIMING FORMULA

µs = (qpc_end - qpc_start) × 1,000,000 ÷ qpc_freq

Brackets ONLY algorithmic maze generation & BFS solve execution. Excludes terminal rendering & Sleep delays.

▼ RENDERING PIPELINE ARCHITECTURE

Single WriteFile Flush

1. Frame Re-Home

Sends 3-byte sequence \x1b[H to move cursor to (1,1) without screen clear.

2. In-Memory Build

Sequential RDI cursor appends ANSI strings into 64 KB frame_buffer.

3. Single Flush

Issues a single WriteFile syscall per frame to eliminate terminal flicker completely.

▼ HUD LAYOUT & SPARKLINE ENGINE

65-Cell Interior Frame Split

Left Column (Cols 1-32):

Generate : Active maze algorithm
Solve : BFS shortest path
Grid : 65 × 23 (1,495 cells)

Right Column (Cols 34-65):

Expanded : Explored cell count
Shortest : Optimal path steps
Gen / Solve Time : Microseconds

SPARKLINE FORMULA & SAMPLING

Unicode block set [ ▁▂▃▄▅▆▇█ ] sampled up to 40 entries: height = (frontier_size × 8) / peak_frontier

▼ ANIMATION STATE MACHINE FLOW

State Machine Progressions

[READY]
280 ms

➔

[SEARCH]
~2-5s

➔

[ROUTE]
~1-3s

➔

[SOLVED]
Final

➔

[COMPARE]
~2-5s

▼ ASSEMBLY SYMBOL REGISTRY & CONSTANTS (.equ)

src/mazerunner.S

Symbol Name	Value	Description & Constraints
`MAZE_W`	65	Grid width (odd-room parity)
`MAZE_H`	23	Grid height (odd-room parity)
`MAZE_N`	1495	MAZE_W × MAZE_H total allocation
`MAX_N`	2048	Buffer allocation ceiling
`SEARCH_BATCH`	6	Revealed cells per animation frame
`FRONTIER_SPAN`	16	Lookahead window for active glow
`PATH_BATCH`	4	Optimal path cells per frame
`HEATMAP_COLORS`	16	Catppuccin distance gradient steps
`SPARKLINE_WIDTH`	40	Maximum sparkline columns
`SPARKLINE_SAMPLE`	32	BFS expansion sampling frequency