Skip to main content

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.

Treasure Hunt is a fully static browser game — there is no framework to install, no build step to run, and no server-side component. The entire game lives in one HTML file, one CSS file, and three JavaScript ES modules. You can have it running locally in under a minute with a single terminal command, or publish it to the web via GitHub Pages without writing a single line of configuration.
The game is purely static. There is no bundler, no npm install, and no build step required at any point — locally or in production. All JavaScript files use native ES module import/export syntax supported by every current browser.

​
Prerequisites

  • A modern browser (Chrome, Edge, Firefox, or Safari — current versions).
  • Optional: Python 3 installed locally if you want to serve the files through a local HTTP server. This is recommended because ES module imports resolve correctly over HTTP but may be blocked by some browsers when opening files directly from the filesystem via file:// URLs.

​
Run Locally

1

Clone or download the repository

Obtain the project files by cloning the repository or downloading the ZIP from GitHub. Make sure the folder structure is intact — index.html must sit at the root level alongside assets/.
git clone https://github.com/apursley2012/treasure-hunt-game.git
cd treasure-hunt-game
2

Start a local HTTP server

From the project root, run the Python built-in static file server:
python -m http.server 8000
You should see output similar to:
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
3

Open the game in your browser

Navigate to:
http://localhost:8000
The Treasure Hunt game page loads with a freshly generated 8×8 maze already rendered and the status pill showing Ready.

​
Opening index.html Directly Without a Server

You can double-click index.html to open it directly in your browser via a file:// URL. The game will typically work in Chrome and Edge, but some browsers block ES module cross-origin imports when loaded from the filesystem. If the board does not render or the console shows a CORS or module-loading error, use the python -m http.server 8000 approach above instead.

​
Deploy to GitHub Pages

1

Upload the project to a GitHub repository

Create a new public repository on GitHub and push all project files. Verify that index.html is committed at the repository root — not inside a subfolder.
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<your-username>/<your-repo>.git
git push -u origin main
2

Confirm index.html is in the repository root

GitHub Pages serves from the root of the selected branch by default. The path index.html must resolve directly — if it is nested inside a folder, Pages will show a 404.
3

Confirm .nojekyll is in the repository root

The project includes a .nojekyll file. This file tells GitHub Pages to skip the Jekyll build process, which is required because Jekyll ignores files and folders that begin with an underscore — and without it, some asset paths can break silently.If the file is missing, create it:
touch .nojekyll
git add .nojekyll
git commit -m "Add .nojekyll for GitHub Pages"
git push
4

Enable GitHub Pages in repository settings

  1. Open your repository on GitHub.
  2. Go to Settings → Pages.
  3. Under Build and deployment, set the source to Deploy from a branch.
  4. Select your branch (typically main) and the / (root) folder.
  5. Click Save.
GitHub will publish the site and display the URL — typically https://<your-username>.github.io/<your-repo>/. The first deployment usually takes about a minute to go live.

​
Your First Game

Once the page is open, follow these steps to play your first race:
1

Select a difficulty

Use the Agent Difficulty dropdown to choose Easy, Medium, or Hard. Easy gives the agent a 1600 ms head-start delay and a 42 % exploration rate, so it frequently wanders off the optimal path. Hard sets a 350 ms start delay and a 0 % mistake rate — the agent follows the BFS-optimal path without hesitation.If this is your first time, start with Easy.
2

Generate a new maze

Click New Maze. The board regenerates with a freshly randomized 8×8 layout. The Game Log at the bottom will show the shortest route length for the new board, for example:
New randomized 8×8 maze loaded. Only valid open cells can be used. Shortest route: 18 moves.
3

Start the race

Click Start Race. The status pill changes to Race Running and the agent begins moving on its timer interval. The agent is shown on the board as 🤖 and you are shown as ●.
4

Move to the X

Navigate through the maze using the keyboard or on-screen controls:
InputDirection
ArrowUp or wUp
ArrowDown or sDown
ArrowLeft or aLeft
ArrowRight or dRight
Reach the X at cell [7, 7] before the agent does. The status pill will display You Found the X if you win, or Agent Found the X if the agent gets there first.

Build docs developers (and LLMs) love

Get started for freeTalk to us