Maze-Explorer

Inspiration

For Maze Explorer, I wanted to build a stealth-action maze crawler entirely from scratch in Python. The goal was to create a tense gameplay loop that shifts dynamically midway, while proving that complex mechanics like trigonometric raycasting and state-driven AI could be handled efficiently through pure Python data structures.

What it does

Maze Explorer drops the player into a procedurally generated facility with perfect visibility, where the initial objective is simply to locate a hidden artifact and plan an exit route. However, the moment the player grabs the artifact, a "Heist Phase" is triggered. The facility goes into lockdown, the global lights cut out, the player's field of view is severely restricted, and AI guards begin actively hunting them. The player must navigate the dark maze, dodge dynamic detection cones, and survive until they reach the extraction point.

How I built it

The game was engineered using Python and Pygame-CE. Instead of using a commercial engine, I built the underlying architecture to handle all spatial mathematics and state management:

• Strict Entity-Component-System (ECS): The game logic is entirely decoupled. Systems for rendering, pathfinding, and raycasting communicate exclusively through isolated data components and global interaction intents.

• Spatial Grid Hashing: Entities and environments are managed through a custom discrete grid system. This optimizes collision and overlap detection, bringing the mathematical complexity down to $O(1)$.

• Procedural Level Generation: The map is dynamically generated by scaling a base maze algorithm into full rooms, automatically assigning wall and door sprites based on cell neighbors.

• Dynamic Modding API: I built a custom ModsManager that scans a designated folder and dynamically loads custom Python scripts (inheriting from BaseMod.py) directly into the game's ECS loop at runtime.

Challenges I ran into

Building bespoke spatial mathematics without a dedicated physics server was a significant hurdle. Calculating the AI guards' fields of view required custom trigonometric raycasting algorithms that could dynamically clip against grid-approximated walls without tanking the frame rate. Additionally, implementing Breadth-First Search (BFS) pathfinding that allowed guards to smoothly navigate the discrete spatial grid required heavy optimization and strict AI state management (switching between Search, Pathfind, and Move states).

Accomplishments that I'm proud of

I am incredibly proud of the clean, highly decoupled architecture. The strict ECS design makes the game highly scalable. I am also proud of successfully integrating a fully functional modding API that allows external scripts to hook into engine initialization, level start, and the main update loop to override components seamlessly. Achieving a tense, atmospheric gameplay shift—where the game transitions from a peaceful exploration crawler to a high-stakes stealth game—was incredibly rewarding.

What I learned

This project deepened my expertise in low-level systems programming and data-oriented design. I mastered discrete spatial partitioning, advanced AI state management, and custom rendering pipelines, reinforcing my preference for pragmatic, efficient architectural design.

Built With

• python