Gemburrow · Gemburrow 1.0.0

1 Overview

Gemburrow is an HTML5 gem shooter puzzle game. A mole miner sits in a round mine bucket in the middle of the screen and shoots cut gems from a copper launcher. A chain of colored gems rolls along a mine-cart rail track toward the nest of a sleeping baby dragon; the player shoots gems into the chain, and 3 or more of the same color pop. Clear the whole chain to win the level; if the chain reaches the dragon's nest, the dragon wakes up and the level is lost.

There are 50 levels in 5 worlds of 10 (Copper Tunnel, Crystal Grotto, Mushroom Hollow, Frost Cavern and Dragon's Hoard), each with its own background, trackside props, mole headwear and track color. Level 1 is a guided tutorial. The game adds 4 power-ups (freeze, rockets, hammer and rainbow gem), special gems (bomb, snail, rewind and lightning), frozen gems, tunnels, a track that crosses over itself and levels with two tracks. After level 50 a Journey Complete screen sums up the stars and scores.

The game runs in any modern browser on phones, tablets and computers, in portrait and landscape. On very wide screens the game stays in a centered band and the sides show the background. It uses plain HTML, CSS and JavaScript (ES modules) with a 2D canvas for the track; there is no engine, no server, no account, no ads and no payments.

2 Quick installation by FTP

Installing takes a few minutes if you have FTP access or a file manager in your hosting panel.

1. Extract gemburrow-static-1.0.0.zip on your computer.
2. Connect to your hosting by FTP or its file manager and open the folder where the game should live, for example public_html/games/gemburrow/.
3. Upload only the contents of the game/ folder, so that index.html sits directly inside the target folder.
4. Keep assets/, src/ and style.css beside index.html, with names and letter case exactly as extracted.
5. Open https://your-domain.example/games/gemburrow/ in a modern browser.

Warning Do not upload the source/ folder, the documentation/ folder or the ZIP itself. Players need no Node.js, PHP, database or account.

3 Requirements and sound

Any static web hosting with HTTPS (or HTTP). Opening index.html directly from the disk (file://) is not supported, because browsers block JavaScript modules that way.
A current browser: Chrome, Edge, Firefox or Safari, on desktop or mobile.
Browsers start sound only after a user gesture. The game opens on a tap-to-start screen and only then plays music and effects.
When the page is hidden, the sound fades out over 30 seconds and everything pauses after 60 seconds; it comes back when the player returns.

4 Controls and how the game works

Touch or click where you want to shoot: the mole turns toward the pointer, and the gem flies when you release, so you can drag to adjust the aim first. With a mouse the mole follows the pointer. The gem in the iron pan behind the mole is the next one; tap the mole (or right-click, or press Space) to swap the two. A gem that hits the chain joins it; 3 or more of the same color pop, and when the gap closes and the colors at both ends match, they pop too (a chain reaction). Shooting a gem through a gap in the chain gives a bonus.

Each level ends with a score. Points come from popped gems, chain reactions, gap shots, streaks of hits and the free track left in front of the dragon's nest at the end. The score bar shows the targets for 2 and 3 stars; a won level always gives at least 1 star. Winning a level unlocks the next one. The first time a level is won with 3 stars, the player gets one extra power-up.

Power-ups (the round buttons at the bottom) start with 3 uses each and the count is kept between levels: freeze stops the chain for 6 seconds, rockets pop 5 gems at once, the hammer smashes the gems where you tap next, and the rainbow gem matches any color. Special gems pop like others and then act: bomb (a blast around it), snail (the chain slows down for 8 seconds), rewind (the chain rolls back for 3 seconds) and lightning (every gem of its color pops). New pieces (tunnels, bridge, two tracks, frozen gems and each special gem) are introduced with a short tip from the mole the first time they appear.

Settings (the gear on the menu) has music and sound effects volume, vibration, less motion, the language list, full screen and a button that replays the tutorial. During a level the gear opens Pause with Resume, Restart, Home and the two volume sliders. Escape also pauses on a computer.

5 Screens and controls explained

Title screen: the first tap starts the game and unlocks sound.

Menu: the Play button opens the next level, Levels opens the level list, the card shows the current world and
its progress, and the star count shows the stars earned. — Menu: the Play button opens the next level, Levels opens the level list, the card shows the current world and its progress, and the star count shows the stars earned.

Levels: the 5 world badges at the top, the world name and the 10 levels of the world along a little rail
track. Locked worlds can be opened to look at their background. — Levels: the 5 world badges at the top, the world name and the 10 levels of the world along a little rail track. Locked worlds can be opened to look at their background.

A level: the level number, the score bar with its star targets, the pause gear, the chain on the track, the
dragon's nest at the end, the mole with the next gem and the power-ups. — A level: the level number, the score bar with its star targets, the pause gear, the chain on the track, the dragon's nest at the end, the mole with the next gem and the power-ups.

Level 1: the mole explains each step in a speech bubble while a hand shows where to tap.

Win: the stars, the score, the best chain reaction and the buttons to go on, replay or return to the menu.

Settings: music and effects volume, vibration, less motion, language, full screen and the tutorial.

6 Map of the files

game/ is the ready-to-host game. source/ has the same editable files plus the tests, a local preview server and the build command. Code comments are in Portuguese.

game/                        upload these contents to your web host
  index.html                 entry page (screens and panels)
  style.css                  styles of every screen
  src/main.js                start-up, resize, frame loop, test shortcuts
  src/ui.js                  screens and panels (DOM)
  src/game.js                one level: aiming, shooting, power-ups, tutorial
  src/chain.js               rules of the chain (no drawing)
  src/track.js               tracks built from a seed
  src/levels.js              the 50 levels
  src/draw.js, fx.js         canvas drawing and effects
  src/launcher-art.js        where the mole holds the launcher   in each pose
  src/audio/sound.js         music and sound effects
  src/locales.js             texts: English, Portuguese, Spanish
  src/locales-more.js        texts: the other 11 languages
  src/config.js              feel numbers, rules, colors, worlds, save key
  src/save.js, storage.js, i18n.js, viewport.js, fullscreen.js
  assets/art/                images (WebP)
  assets/fonts/              Fredoka font and its license
  assets/music/              menu.mp3, play.mp3
  assets/sfx/                plop1.mp3 to plop5.mp3
  DOCUMENTATION.txt          short note that points to this guide
source/                      the same editable files, plus:
  package.json               npm test, npm run build, npm run serve
  package-lock.json
  README.md
  test/                      node --test tests
  tools/build.mjs            copies the game into dist/
  tools/serve.mjs            local preview server
documentation/index.html     this guide (offline, 14 languages)
documentation/customization.html   step-by-step customization guide
documentation/img/           the screenshots of both guides
DOCUMENTATION.html           shortcut to this guide
CUSTOMIZATION.html           shortcut to the customization guide
START-HERE.txt, CHANGELOG.txt
THIRD-PARTY-LICENSES/        font license

src/config.js: the game feel numbers in one place (FEEL: aiming, gem speed, shake, particles, vibration), the power-up rules (RULES_UI: starting uses, star targets, bonuses), gem colors (MARBLE; in the code the gems are called marbles), the five worlds (WORLDS), default volumes and the save key.
src/locales.js and src/locales-more.js: every interface text in the 14 languages; src/i18n.js picks the language.
src/chain.js: the rules of the chain with no drawing (push, pull back, insert, pop, special gems; RULES holds their timings). src/track.js builds the tracks from a seed. src/levels.js holds the 50 levels.
src/game.js runs a level (aiming, shooting, power-ups, tutorial), src/draw.js and src/fx.js draw it on the canvas, src/ui.js builds the screens and panels, and src/main.js starts everything.
style.css: the styles of every screen and panel. Sizes use --u, 1% of the shorter usable side of the screen.
assets/: images (art/, WebP), the font (fonts/), music (music/) and the recorded pop sounds (sfx/), all MP3.

7 Customizing texts, images and sounds

Note Not a programmer? The Customization Guide shows every change step by step, with numbered screenshots of the game. It is in English. Open CUSTOMIZATION.html in the main folder of the download, or documentation/customization.html.

Customization Guide (step by step, in English)

Texts: open src/locales.js (English, Portuguese and Spanish) or src/locales-more.js (the other 11 languages) and change the text after each key. Keep the keys and placeholders such as {n} unchanged; npm test checks that all 14 languages have the same keys and placeholders.

Images: replace a file in assets/art/ with another WebP of the same name and similar proportions. The mole has eight poses per world, for example mole1.webp, mole1-aim.webp, mole1-cheer.webp and mole1-scared.webp for world 1; gems are m0.webp to m5.webp; the dragon's nest is drain.webp (asleep) and drain-awake.webp (awake: in danger and when the level is lost); backgrounds are bg1-port.webp, bg1-land.webp and bg1-sq.webp for portrait, landscape and square screens.

Levels: the PLAN table in src/levels.js has one line per level: the track shape (oval, spiral, bean, serp, eight or duo), the special gems, the tunnels and the frozen gems. COLORS sets how many gem colors each world uses, and getLevel(n) turns a line into chain length, speed and number of gems. Run npm test after a change: it builds every level on several screen sizes.

Colors and sizes of the interface are in style.css. The game title is in index.html and in assets/art/logo.webp; the line under the logo is in index.html. Track colors per world are in WORLDS in src/config.js.

Music and sound effects

Music: assets/music/menu.mp3 plays on the menus and play.mp3 during levels. To change a track, replace the MP3 keeping the name. The game starts the next loop a few seconds before the end of the file, so a track with a soft ending loops best. Without the file the game simply stays silent.

Sound effects: most short sounds (shot, swap, insert, power-ups, buttons, the rising notes of a chain) are synthesized by the SYNTH table in src/audio/sound.js, so they have no file. The 5 recorded pop sounds are assets/sfx/plop1.mp3 to plop5.mp3; the game plays a different one each time. Replace them keeping the names, or delete them and the synthesized pop is used instead.

Players control both volumes in Settings; the starting values are VOL in src/config.js.

Warning Keep the save key unchanged on a live site. A different key makes the game ignore existing progress and start a new save.

8 Languages

The game has 14 languages: English, Português, Español, Français, Deutsch, Italiano, Nederlands, Polski, Türkçe, Русский, Bahasa Indonesia, 日本語, 한국어 and 简体中文. It follows the browser language on the first visit and the player can change it in Settings. English, Portuguese and Spanish are the reference texts; the other 11 languages were not reviewed by native speakers.

To force a language, add ?lang=pt (or another code) to the game address.

To add a language, copy one of the blocks in src/locales-more.js, translate it, add it to that file's list, and add its code and name to LANGS, HTML_LANG and NUMBER_LOCALE in src/locales.js. The language test in test/locales.test.mjs expects 14 languages, so update that number too.

9 Local saves

Progress (level reached, stars and best score of each level, power-ups left, tips already seen and settings) is saved in the browser localStorage of each device.
There are no accounts or cloud saves. Clearing site data resets the progress on that device.
The two keys are shown below. Their prefix is STORAGE_PREFIX in src/config.js.

gemburrow.template.save.v1.progress
gemburrow.template.save.v1.lang

10 Optional development

This section is only for changing the code. The game/ folder already contains the finished game, so installing it needs no Node.js. The game has no dependencies and no compile step: npm run build only copies the files into source/dist/, which is identical to game/.

1. Install Node.js. Open https://nodejs.org/en/download and choose the latest Node.js 26 LTS installer for your system (minimum 26.13). npm is included.

Windows: run the .msi installer, keep npm and Add to PATH enabled, finish the installation and reopen Command Prompt. macOS: run the official .pkg installer and reopen Terminal. Linux: follow the instructions on the official download page for your distribution, including npm.

2. Check the installation. Run node --version and npm --version separately. Both must print a version number, and Node.js must be 26.13 or newer. If a command is not found, reopen the terminal and check the installation.

node --version
npm --version

3. Extract the complete ZIP first and open its source/ folder, where package.json is. Windows: type cmd in the address bar of that folder in File Explorer. macOS and Linux: open Terminal and use cd with the folder path in quotes.

4. Run the commands below one by one. npm ci checks the lock file (nothing is downloaded, the project has no dependencies). npm test checks the chain rules, builds all 50 levels on several screen sizes and checks the 14 languages and the save key; stop and fix any error before going on.

npm ci
npm test

5. Preview: npm run serve starts a local server; open http://localhost:5345/ in your browser, play a level, and stop the server with Ctrl+C.

npm run serve

6. Build: npm run build empties source/dist/ and copies index.html, style.css, src/ and assets/ into it. dist/ is what you publish; while the source is unchanged it matches game/ file by file.

npm run build

7. Publish: back up the game on your website, then upload the contents of dist/ in place of the old files, keeping the folders. If you deleted or renamed a file, delete the old one on the server yourself. Clear the browser cache to see the new version (see below).

Note Troubleshooting: ENOENT or a missing package.json means the terminal is in the wrong folder. EBADENGINE means Node.js is too old. If PowerShell blocks npm.ps1, use Command Prompt instead; do not change security settings.

Test shortcuts (local addresses only)

The shortcuts below work only when the page address is localhost, 127.0.0.1 or [::1]. On any other address they are ignored, so players cannot use them. ?lang=pt (or another language code) is not a test shortcut and works on any address.

?level=12 opens level 12 directly, and ?unlock unlocks all 50 levels.
?screen=levels opens a screen directly (home or levels).
?notutorial skips the guided tutorial of level 1.
?reduced forces less motion.
?qa adds helpers for automated tests: run __gemburrow.auto(120) in the browser console to let a simulated player shoot for 120 seconds of game time. The window.__gemburrow object (the running game) has these helpers only on local addresses.

http://localhost:5345/?level=12&lang=es

11 Updating and cache

Clearing the cache without losing progress

Progress is stored in this browser, not on the server. Clearing cached images and files, or doing a hard reload, keeps your progress.

Computer: press Ctrl+F5 on Windows and Linux, or Cmd+Shift+R on macOS. Phone: in the browser settings, choose the option to clear cached images and files.

Do not choose cookies and site data, or clear site data, for the game's address. That deletes the local save.

12 Licenses

The game code and artwork are supplied under the license of the item you purchased. The music and recorded sound effects used by the game are included in the package and can be replaced or removed (see the customizing section).

The Fredoka font is used under the SIL Open Font License 1.1; its complete license text is in THIRD-PARTY-LICENSES/ and in game/assets/fonts/LICENSE-Fredoka-OFL.txt. The game has no third-party code and no npm dependencies.

13 Troubleshooting

Blank page: the game was opened from the disk or a file is missing. Use a web host and keep assets/, src/ and style.css next to index.html.
No sound: tap the screen once; check the device is not silent and the volume sliders are up.
Old version after an update: clear the browser cache (see below).
Images missing after replacing art: check the file name, extension and letter case.
An address such as ?level=5 does nothing on your website: test shortcuts only work on local addresses (see the development section).

14 Frequently asked questions

Does the game work without internet?

The game calls no external services. It is not an installable offline app, so players need to reach your web address to load it.

Can I add ads, a store, cloud saves or a ranking?

Not in this edition. It has no ad, payment, sync or ranking code. Adding them is developer work that needs your own accounts.

Can I publish it on game portals or app stores?

Yes, within the terms of the license you purchased. Wrapping it as an app needs your own developer accounts and tools.

Do I need Node.js?

Only to run the tests or rebuild after editing. Installing and playing needs only a web host.

How do I reset the progress while testing?

Clear the site data for the game address in the browser, or run localStorage.clear() in the browser console. Settings has no reset button.

15 Support

Questions or problems: write to willian@polargames.com.br with your purchase code, the browser and a short description or screenshot.

Support request

When you write to support, include the browser and device, the game version, the page address, the steps that caused the problem, a screenshot and the first error shown in the browser console. Never send passwords, payment details or secret keys.