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.
Every game of Treasure Hunt is a head-to-head race on a freshly generated 8×8 maze. You start at the top-left corner, the treasure X sits at the bottom-right corner, and an intelligent JavaScript agent races you to it. The board is full of blocked cells that neither you nor the agent can cross, so finding the right path — and taking it faster than the agent — is the whole challenge. Invalid moves cost you reward points without moving you forward, and the game tracks a minimum reward threshold that signals a loss state when your score drops too far.
Start on Easy difficulty to get a feel for the maze layout and controls before moving up. On Easy, the agent has a 1600 ms start delay and a 42 % chance of making an exploratory detour on every move, giving you meaningful time to learn the path before the AI becomes a real threat.
Objective
Reach the treasure cell at position [7, 7] — the bottom-right corner of the 8×8 grid — before the CompetitiveAgent does. Both you and the agent start at cell [0, 0], the top-left corner. Open cells can be entered freely; blocked cells (0 in the maze matrix) cannot be entered by either side.
Controls
Keyboard
You can control your player with either the arrow keys or WASD at any time during an active race.
| Key | Direction |
|---|
ArrowLeft or a | Move left |
ArrowUp or w | Move up |
ArrowRight or d | Move right |
ArrowDown or s | Move down |
keydown listener on the document. Recognized keys call event.preventDefault() so the page does not scroll while you play.
Four directional buttons are rendered in the Player Controls panel on the right side of the game layout. Each button carries a data-action attribute that maps to a movement direction.
| Button label | data-action value | Direction |
|---|
| ↑ | up | Move up |
| ↓ | down | Move down |
| ← | left | Move left |
| → | right | Move right |
HUD Elements
The heads-up display around the maze board updates after every player move and every agent move. Each element surfaces a different piece of live race data.
| HUD Element | DOM ID | What it shows |
|---|
| Difficulty | #difficulty-label | The label for the currently active difficulty setting (Easy, Medium, or Hard) |
| Reward | #reward-label | Your current cumulative reward, formatted to two decimal places (e.g. −1.23) |
| Player Steps | #player-steps-label | The number of valid moves you have made this race (invalid moves are not counted) |
| Agent Steps | #agent-steps-label | The total number of cells the agent has moved to this race — hesitations and blocked turns are not counted |
| Shortest Route | #path-length-label | The BFS-optimal path length for the current maze, in moves (recalculated each render) |
| Race Lead | #player-lead-label | Comparative step count: Even, Player +N, or Agent +N |
| Agent move | #agent-move-label | Description of the agent’s last action, e.g. exploited right, explored down, or hesitated |
| Game Log | #training-log | A scrolling list of the last 9 game events, newest first |
Reward System
The TreasureMaze class tracks your cumulative reward in totalReward and applies the following values on every move:
| Move result | Reward |
|---|
Reach the treasure cell [7, 7] | +1.0 |
| Valid move to an unvisited cell | −0.04 |
| Valid move to a previously visited cell | −0.25 |
| Invalid move (into a blocked cell or out of bounds) | −0.75 |
| Blocked — no valid adjacent cells exist | minReward − 1 (≈ −33 on the standard board) |
−0.75 penalty to totalReward but does not change your position on the board. Your Player Steps counter is also not incremented for invalid moves.
The minimum reward threshold is calculated as minReward = −0.5 × rows × cols. On the standard 8×8 board this equals −32. TreasureMaze.gameStatus() returns "lose" when totalReward drops below this threshold, and the Reward counter in the HUD will reflect that negative total.
Win and Lose Conditions
| Condition | Status pill text | Trigger |
|---|
You reach [7, 7] | You Found the X | env.gameStatus() returns "win" |
Agent reaches [7, 7] | Agent Found the X | agent.hasReachedTreasure() returns true |
TreasureMaze.gameStatus() also returns "lose" when totalReward drops below minReward (−32 on the standard board), which is reflected in the Reward HUD counter. However, app.js does not call endRace() for this state — the race continues and you can keep moving even if your reward reaches deeply negative values.
Game Controls
Three buttons in the Race Setup panel manage the game state.
| Button | ID | Behaviour |
|---|
| Start Race | #start-race | Activates the race, starts the agent timer after startDelay ms, and disables itself until the race ends or is reset |
| New Maze | #new-maze | Generates a fresh randomized 8×8 maze, resets both players to [0, 0], and logs the new shortest route length |
| Reset | #reset-race | Resets both players and reward on the current maze without generating a new board |
Difficulty Selection
The Agent Difficulty dropdown (#difficulty-select) controls how the CompetitiveAgent behaves. Changing the difficulty mid-session calls resetRace() automatically so the new settings take effect from a clean state.
| Difficulty | Move delay | Start delay | Mistake rate | Hesitate rate | Agent behaviour |
|---|
| Easy | 1150 ms | 1600 ms | 42 % | 20 % | Explores frequently, hesitates sometimes, gives the player a head start |
| Medium | 780 ms | 900 ms | 18 % | 8 % | Usually follows the optimal route but makes occasional exploration choices |
| Hard | 470 ms | 350 ms | 0 % | 0 % | Exploits the BFS-optimal path aggressively with no hesitation or detours |
On Hard, the agent starts after only 350 ms and follows the exact shortest path on every move with no mistakes. On a maze with a short optimal route, the agent can reach the treasure before you have time to make more than a few moves. Always learn the board layout on Easy or Medium first.