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.

Most Treasure Hunt problems fall into one of two categories: a file path that does not match what the code expects, or the game being accessed via the file:// protocol instead of a local HTTP server. The fixes are straightforward once you know where to look. Start with browser DevTools before anything else — nearly every issue leaves a visible trace in the Network or Console tab.
Press F12 (or Cmd + Option + I on macOS) to open browser DevTools. The Console tab shows JavaScript errors and failed module imports. The Network tab shows every asset request — a red row with a 404 status points directly to a missing file or a wrong path. Checking these two tabs first will identify the problem in almost every case.
Cause: assets/css/styles.css is missing, has been moved, or the path in index.html does not match the actual file location.How to confirm: Open the Network tab in DevTools and reload the page. Look for a 404 on styles.css. A 200 that loads zero bytes can also indicate an empty or misplaced file.Fix:
  1. Confirm the file exists at exactly assets/css/styles.css relative to the repository root.
  2. Check the <link> tag in index.html — it must read: 
    <link rel="stylesheet" href="./assets/css/styles.css" />
  3. If the file was renamed or moved, restore it to assets/css/styles.css or update the href to match.
Cause: app.js is not loading as an ES module, or the browser is blocking the module import because the page is being opened via the file:// protocol instead of http://.How to confirm: Open the Console tab in DevTools. A CORS error such as Cross-Origin Request Blocked or a message like Failed to load module script points to the file:// protocol problem. A 404 on app.js means the script tag path is wrong.Fix:
  1. Verify the <script> tag at the bottom of index.html reads exactly: 
    <script type="module" src="./assets/js/app.js"></script>
    The type="module" attribute is required. Without it, the import statements inside app.js will throw a syntax error.
  2. Do not open index.html by double-clicking it. Use a local HTTP server instead: 
    python -m http.server 8000
    Then visit http://localhost:8000.
Cause: The logo image file assets/images/treasure-hunt-logo.png is missing from the repository, or has been renamed or moved.How to confirm: Open the Network tab in DevTools and look for a 404 on treasure-hunt-logo.png.Fix:
  1. Confirm the file exists at exactly assets/images/treasure-hunt-logo.png.
  2. The logo is referenced in two places in index.html — both use the same relative path: 
    <img class="brand-logo" src="assets/images/treasure-hunt-logo.png" alt="Treasure Hunt logo">

    <img class="hero-logo" src="assets/images/treasure-hunt-logo.png" alt="Treasure Hunt logo">
  3. If you are replacing the logo, keep the filename and path identical so no HTML changes are needed. The README notes: “The logo file can be replaced without changing the game logic as long as the path remains the same.”
Cause: The CSS rules for #maze-board have been modified or overridden. The board must be an exact 8×8 CSS grid with equal columns and rows.How to confirm: Open the Elements tab in DevTools, select the #maze-board div, and inspect its computed styles. The grid-template-columns value should be repeat(8, 1fr).Fix: styles.css defines #maze-board with the following critical properties — do not override them:
#maze-board {
  display: grid !important;
  grid-template-columns: repeat(8, 1fr) !important;
  grid-template-rows: repeat(8, 1fr) !important;
  aspect-ratio: 1 / 1 !important;
}
If a local style override is changing grid-template-columns to anything other than repeat(8, 1fr), the 64 cells app.js renders will not fill an 8×8 grid and the board will appear stretched, cropped, or misaligned. Remove the conflicting rule to restore the correct layout.
Cause 1: The .nojekyll file is missing from the repository root. GitHub Pages runs Jekyll by default, and Jekyll can strip or ignore files that prevent the JavaScript modules from loading correctly.Cause 2: One or more asset paths in index.html or styles.css use absolute paths (starting with /) instead of relative paths (starting with ./ or just the folder name). Absolute paths break when GitHub Pages hosts the site under a subdirectory like https://<username>.github.io/<repo-name>/.Fix for missing .nojekyll:
touch .nojekyll
git add .nojekyll
git commit -m "Add .nojekyll"
git push
Fix for absolute paths: Confirm that all asset references in index.html use relative paths. The correct patterns are:
<link rel="stylesheet" href="./assets/css/styles.css" />
<script type="module" src="./assets/js/app.js"></script>
<img src="assets/images/treasure-hunt-logo.png" alt="Treasure Hunt logo">
Do not change these to /assets/css/styles.css — the leading slash makes the path relative to the domain root, which breaks the subdirectory-hosted GitHub Pages URL.After pushing the fix, wait 1–2 minutes for GitHub Pages to redeploy, then hard-refresh the page (Ctrl + Shift + R / Cmd + Shift + R).
Cause: The race has not been properly started, the previous race has already ended (setting raceOver to true internally), or a JavaScript error stopped execution before the agent timer could be set.How to confirm: Open the Console tab in DevTools and look for any red errors. If raceActive is false when moveAgentOnce() runs, the function returns immediately without moving the agent.Fix:
  1. Click Reset to clear the current race state and restore raceActive and raceOver to their defaults.
  2. Click Start Race. The status pill will change from Ready to Race Running and the agent will begin moving after its configured startDelay.
  3. If the agent still does not move, check the Console tab for JavaScript errors. Any uncaught error thrown during startRace() or the setInterval callback will silently halt agent movement.
If the issue happens consistently on a specific maze, click New Maze to generate a fresh board and try again.
This is expected behavior. The createRandomMaze() function uses Math.random() to generate each board. With a finite 8×8 grid and a density constraint that guarantees a valid path from [0, 0] to [7, 7], the pool of valid boards is large but not infinite. On rare occasions two consecutive calls can produce a visually similar layout by chance.Fix: Click New Maze again. The probability of generating visually identical boards twice in a row is very low, and a third click will virtually always produce a different maze. No code change is needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us