The Treasure Hunt project exists in two distinct forms that share the same core problem but solve it in completely different environments. The original version is a Python machine-learning implementation: a Jupyter Notebook trains a pirate agent through hundreds of episodes of deep Q-learning, reward shaping, and experience replay, producing a model that consistently finds the treasure. The browser demo is a JavaScript application deployed as a static GitHub Pages site: it turns the same 8×8 maze problem into a playable race where a human competes against an intelligent agent in real time. Comparing the two versions side by side reveals what had to be preserved, what had to change, and why those decisions were made.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/apursley2012/treasure-hunt-game/llms.txt
Use this file to discover all available pages before exploring further.
Side-by-Side Comparison
| Area | Original AI Version | Browser Demo Version |
|---|---|---|
| Runtime | Python 3, Jupyter Notebook | HTML / CSS / JavaScript (ES modules) |
| Main Goal | Train a neural network to solve the maze | Playable browser game demonstrating the AI concept |
| Hosting | Local machine — requires Python, Keras, TensorFlow | GitHub Pages — static file hosting, no server required |
| Agent Type | Keras deep Q-network (trained neural network) | BFS pathfinding (CompetitiveAgent) with difficulty modes |
| Maze | Fixed 8×8 matrix defined in the notebook | Randomized 8×8 maze generated each game with path validation |
| Data Storage | Experience replay buffer in memory during training | No persistent storage — each session is self-contained |
| User Experience | Observer watches the agent train and test | Player races the agent using arrow keys / WASD / on-screen controls |
| Dependencies | NumPy, Keras, TensorFlow, Matplotlib | None — vanilla JavaScript only |
What Was Preserved
The browser demo deliberately keeps the rules of the original Python environment intact. The core game logic is the same in both versions:- Maze structure — An 8×8 grid where cells are either open (
1.0) or blocked (0.0). - Valid movement rules — The pirate/player can only move left, up, right, or down. Boundary and wall checks are identical.
- Reward values — The exact same numbers appear in both implementations:
+1.0for reaching the treasure−0.04for a valid move to a new cell−0.25for revisiting an already-visited cell−0.75for an invalid move (wall or boundary)min_reward − 1(terminal loss penalty) for a fully blocked agent
- Target cell — Always the bottom-right corner of the maze.
- Start cell — Always a valid (unblocked) cell, defaulting to
(0, 0). - Game-over conditions — Win by reaching the target; lose by accumulating total reward below the minimum threshold.
Because the reward values are identical, the player in the browser demo experiences the same incentive structure the neural network was trained on. Hitting a wall costs
−0.75. Backtracking costs −0.25. Efficient movement costs only −0.04 per step.What Changed
Language and Runtime
The Python implementation uses NumPy arrays, Keras model training, and Matplotlib for visualization. None of these can run directly in a static web page. The browser demo reimplements every class —TreasureMaze, GameExperience logic, the training loop — in vanilla JavaScript using ES modules. There is no build step, no bundler, and no npm. The JavaScript classes mirror their Python counterparts method by method, making the two codebases directly comparable.
Agent Intelligence
The most significant change is the agent itself. The original version’s pirate is a trained Keras neural network. After enough episodes, the network’s weights encode a Q-function that maps any observed maze state to the best available action. The browser demo’sCompetitiveAgent uses BFS (breadth-first search) on every step — a deterministic algorithm that finds the shortest unblocked path from the agent’s current cell to the treasure.
BFS is a practical stand-in for a fully-trained Q-network operating in pure exploitation mode (epsilon = 0). When training is complete and the epsilon-greedy strategy has fully decayed, the neural network always picks the highest-Q action, which converges on the shortest valid path. BFS computes exactly that path, without requiring a trained model.
GitHub Pages serves static files only. There is no Python interpreter, no TensorFlow runtime, and no server-side compute. Even if the trained Keras weights were exported, loading and running them client-side would require TensorFlow.js and a non-trivial architecture change. BFS produces equivalent output for the purposes of the demo.
Maze Generation
The original notebook uses a fixed maze matrix defined once in the code. The browser demo generates a new randomized 8×8 maze for each game. After generation, a path-validation step verifies that at least one valid route exists from the start cell to the treasure. Mazes without a valid path are discarded and regenerated. This keeps gameplay fresh while ensuring the game is always winnable.Training Loop vs. Race Timer
The Python version’s core mechanic is a training loop: the agent runs episode after episode, win rates improve, and the developer watches the model get better. The browser demo replaces this with a race timer — both the player and the CompetitiveAgent start simultaneously, and the first to reach the treasure wins. The reward-tracking display keeps the reinforcement-learning concept visible to the player without requiring them to understand model training.Notebook vs. Static Web Page
The original workflow opens in Jupyter, runs cells in sequence, and outputs training logs and a final test result. The browser demo opens in any web browser, requires zero installation, and is immediately interactive. This change is what makes the project shareable as a portfolio piece without asking viewers to set up a Python environment.Why the Agent Is Different
The decision to use BFS instead of a live neural network was driven by three constraints:- Static hosting — GitHub Pages cannot execute Python or load a Keras runtime.
- No server — The demo has no backend to offload compute to.
- No database — Training results cannot be persisted between user sessions.
Design Decisions in the Browser Demo
The browser implementation was built around several explicit architectural choices: Static deployment — No server, no database, no build pipeline. The entire application is HTML, CSS, and JavaScript files that GitHub Pages can serve directly. This makes the demo permanently accessible without infrastructure costs or maintenance. ES modules — JavaScript files useimport / export rather than a bundler. Each module has one responsibility: TreasureMaze.js handles the environment, CompetitiveAgent.js handles the agent, GameUI.js handles rendering. This mirrors the clean separation of TreasureMaze.py and GameExperience.py in the original.
Difficulty modes — Because BFS always finds the optimal path, an unmodified CompetitiveAgent would be unbeatable on Hard. Difficulty modes apply deliberate inefficiency on easier settings, making the agent beatable and giving new players a foothold.
Preserved reward display — Step counts, reward values, and shortest-route length are shown during play. These metrics connect the game back to the reinforcement-learning concept: the player sees why backtracking costs more, why walls should be avoided, and why a shorter path is always better.
What Developers Can Learn from Both Codebases
Reading the Python and JavaScript implementations together is a practical exercise in software translation and design tradeoffs:- Algorithm translation —
TreasureMaze.pyand its JavaScript equivalent implement the same logic in two very different runtimes. Comparing them shows which concepts are language-agnostic (reward tables, state representation, boundary checks) and which required adaptation (NumPy arrays → typed arrays, Keras predict → BFS traversal). - Constraint-driven design — Every “limitation” of the browser demo (no neural net, no training loop, no server) was a deliberate design decision that made the project more accessible and deployable, not a shortcut.
- Reward shaping — The same numeric reward values that trained the neural network also shape the player’s experience. Seeing both uses of the same numbers makes the connection between AI training and game design concrete.
- Separation of concerns — Both codebases keep the environment class separate from the agent class and the rendering layer. This structure is not accidental — it is the same pattern used in production reinforcement-learning research (environment / policy / value function as distinct components).
Source Files
The original Python source is preserved in the repository alongside the browser demo:source/original-python/TreasureMaze.py— The environment class: maze grid, movement rules, reward logic, state observation.source/original-python/GameExperience.py— The replay buffer: episode storage, random sampling, Bellman target computation.source/original-python/TreasureHuntGame.ipynb— The Jupyter Notebook: full training loop, model architecture, win-rate tracking, and final agent test.source/README.md— Notes on running the Python version locally.