An idle mining game on floating islands · 1.0.0

Crater Crush

This guide explains how to install, customize and update the game. Pick your language at the top; screenshots stay in English.

Version 1.0.0 Edition Standalone buyer edition

This guide works without internet. Images, styles and scripts are already inside this file.

Contents
  1. Overview
  2. Installing on your website
  3. Requirements
  4. How to play
  5. Screens
  6. Files and folders
  7. Customizing
  8. Languages
  9. Saving and resetting
  10. Development (optional)
  11. Updating and clearing the cache
  12. Licences and credits
  13. Common problems
  14. FAQ
  15. Support

1 Overview

Crater Crush is an HTML5 idle mining game. The player drags a mining ring over an isometric grid of pebbles and ores; the pickaxes strike everything inside the ring, with combos, critical hits and floating numbers. Each shift lasts 30 seconds at the start; the coins buy upgrades between shifts.

Between shifts the hub has 8 tabs: 19 upgrades in a honeycomb tree, goals, 5 lands, a forge with 9 pickaxes, a shop with 6 one-shift boosters, 3 mining rigs that dig while the player is away, 12 relics and Bedrock, the prestige that starts a new run with permanent bonuses. A host character, Opal, gives short guided tips and a little story; she can be switched off.

The game runs in 14 languages, on desktop, tablet and phone (portrait and landscape), with keyboard shortcuts, a Less motion option, sound effects and music. It has no ads, no account, no server and no external services: everything is plain HTML, CSS and JavaScript.

2 Installing on your website

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

  1. 1. Extract crater-crush-static-1.0.0.zip on your computer.
  2. 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/crater-crush/.
  3. 3. Upload only the contents of the game/ folder, so that index.html sits directly inside the target folder.
  4. 4. Keep arte/, audio/, fontes/, idiomas/, historia/, the .js files and the .css files beside index.html, with names and letter case exactly as extracted.
  5. 5. Open https://your-domain.example/games/crater-crush/ 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

  • Any static web hosting with HTTPS (or HTTP). Opening index.html directly from the disk (file://) is not supported, because browsers block the sounds that way.
  • A current browser: Chrome, Edge, Firefox or Safari, on desktop or mobile. The ring follows the mouse or a finger.
  • About 11 MB of space on the server. The game makes no request to other websites.
  • Node.js is only needed to run the tests or to rebuild the game from source/ (see the development section).

4 How to play

Press DIG! to start a shift. Move the ring with the mouse or drag it with a finger: the pickaxes strike the pebbles inside it on their own. Broken pebbles give ores and coins; breaking many in a row fills the combo meter; a critical hit deals extra damage.

When the clock reaches zero (or with END SHIFT) the results card shows the coins, the ores, the XP and the goals. UPGRADES opens the hub; DIG AGAIN starts the next shift.

Keyboard: Esc or P pause, E end shift, Enter dig, U upgrades, 1 to 8 open the tabs, arrows and B choose and buy an upgrade.

Options (the gear button, or the pause panel during a shift): sound effects, music, Less motion, vibration, language, the story journal and the opening story again.

5 Screens

Title screen: start a shift, options, relic collection and language.
Title screen: start a shift, options, relic collection and language.

Marks on the screenshot

  1. DIG! button
  2. Options
  3. Relic collection
  4. Language
A shift: coins of this shift, combo meter, ores, clock, pause, goals, XP and END SHIFT.
A shift: coins of this shift, combo meter, ores, clock, pause, goals, XP and END SHIFT.

Marks on the screenshot

  1. Coins
  2. Combo meter
  3. Ores
  4. Clock
  5. Pause
  6. Goals
  7. Level and XP
  8. End the shift
Results card: ores mined, XP, then the hub or the next shift.
Results card: ores mined, XP, then the hub or the next shift.

Marks on the screenshot

  1. Ores
  2. Open the hub
  3. Next shift
Hub, Upgrades tab: the tabs, the honeycomb tree, the selected upgrade and its BUY button.
Hub, Upgrades tab: the tabs, the honeycomb tree, the selected upgrade and its BUY button.

Marks on the screenshot

  1. Hub tabs
  2. Upgrade tree
  3. Selected upgrade
  4. Buy
  5. DIG! button
Options: sound effects, music, Less motion, vibration and language.
Options: sound effects, music, Less motion, vibration and language.

Marks on the screenshot

  1. Sound effects
  2. Music
  3. Less motion
  4. Language
Portrait phone: the HUD moves to a top bar and the field takes the rest of the screen.
Portrait phone: the HUD moves to a top bar and the field takes the rest of the screen.

Marks on the screenshot

  1. Coins
  2. Pause
  3. Clock

6 Files and folders

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 English. Some file and folder names are in Portuguese; the list below says what each one is.

game/                        upload these contents to your web host
  index.html                 entry page (screens, HUD, hub, options)
  config.js                  every number of the game, the save key, host: true/false
  motor.js                   the rules: stats, prices, XP, ore spawn, save
  jogo.js                    screen code 1/4: settings, save, texts, camera, grid
  jogo-campo.js              screen code 2/4: the ring, strikes, combo, the shift
  jogo-telas.js              screen code 3/4: HUD, results, hub tabs
  jogo-menus.js              screen code 4/4: hub actions, pause, keyboard, title, boot
  opal.js, opal-guia.js      Opal: balloons, guided tips, story cards, journal
  opal-textos.js             texts of the tips (14 languages)
  idiomas.js, idiomas/       interface texts: en and pt, then one file per language
  historia.js, historia/     story texts: en and pt, then one file per language
  som.js                     sound effects and music
  molduras.js                paints the nine-slice frames of panels and buttons
  estilo.css ... estilo-6.css, opal.css   styles (keep the order of index.html)
  arte/                      pictures (WebP): ui, ores (pedras), pickaxes (picaretas), relics, lands, Opal
  audio/                     sound effects and music.mp3
  fontes/                    Fredoka font and OFL.txt
  DOCUMENTATION.txt          short note that points to this guide
source/                      the same editable files, plus:
  package.json, package-lock.json
  README.md
  tests/                     node --test tests (52)
  tools/build.mjs            copies the game into dist/
  tools/serve.mjs            local preview server (npm run dev)
  tools/check-node.mjs       checks the Node.js version before the commands
  tools/simula.mjs           pacing robot (npm run simulate)
documentation/index.html     this guide (offline, 14 languages)
documentation/customization.html   step-by-step customization guide
documentation/img/           the screenshots of the guides
DOCUMENTATION.html           shortcut to this guide
CUSTOMIZATION.html           shortcut to the customization guide
START-HERE.txt, CHANGELOG.txt
THIRD-PARTY-LICENSES/        font license
  • config.js: every number you may want to tune (ores, field, upgrades, lands, pickaxes, shop, rigs, relics, Bedrock, feel) and the save key saveKey. host: false switches Opal off.
  • motor.js: the rules without drawing (stats, prices, XP, ore spawn, save). jogo.js, jogo-campo.js, jogo-telas.js and jogo-menus.js: the screen code (grid and camera, the ring and the shift, the HUD and results, the hub, options and keyboard), four classic scripts loaded in this order.
  • idiomas.js (English and Portuguese) and idiomas/ (one file per language): the interface texts. historia.js and historia/: the story texts. opal-textos.js: the texts of Opal's tips.
  • opal.js and opal-guia.js: Opal, her balloons, the guided tips and the story cards. som.js: sounds and music. molduras.js: paints the frames of panels and buttons.
  • estilo.css to estilo-6.css and opal.css: the styles, linked in this order by index.html (keep the order).
  • arte/: every picture (WebP). audio/: sound effects and music.mp3. fontes/: the Fredoka font and its license OFL.txt.

7 Customizing

Note Not a programmer? The Customization Guide shows the most common changes step by step. 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)

Balance: edit config.js and reload the page. Every value has a comment. Examples: shiftSec (length of a shift), ores (value and hit points of each ore), upgrades (price and effect), lands, picks, shop, rigs, relics and bedrock.

Pictures: replace a file in arte/ with another WebP of the same name and a similar size. The logo is arte/ui/logo.webp; ores are in arte/pedras/, pickaxes in arte/picaretas/, relics in arte/reliquias/, Opal in arte/opal/.

Colours of the interface: the variables at the top of estilo.css. Panel and button frames are images in arte/ui/, painted by molduras.js.

Opal, the guided tips and the story: set host: false in config.js to switch off the character, her tips and the story cards together. Players can also turn the tips off in the game.

Sounds and music

Each sound effect is one MP3 in audio/ (for example break.mp3, crit.mp3, levelup.mp3). Replace a file keeping its name. The list of files is FILES at the top of som.js.

The music is audio/music.mp3. Replace it keeping the name, or delete it: the game stays silent where a sound file is missing.

Warning Save key: if you host more than one copy of the game on the same domain, give each one its own saveKey in config.js, otherwise they share the same progress.

8 Languages

The game has 14 languages: English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean and Chinese. The first visit uses the browser language; the player can change it on the title screen or in the options.

To change a text, edit the same key in idiomas.js (English, Portuguese) or idiomas/<code>.js. Names of ores, upgrades, lands and items in English come from config.js; the other languages translate them by id.

npm test checks that every language has every key and the same {n} markers as English. Russian, Japanese, Korean and Chinese use the fonts of the device.

9 Saving and resetting

  • The progress is saved automatically in the browser of each player (localStorage). Nothing is sent to a server.
  • Two keys are used: the progress and the mute choice. Change saveKey in config.js to give a copy its own progress.
  • To start over in a browser: open the game, open the developer tools (F12), go to Application, Local Storage, select the site and delete the keys below, then reload. Clearing the site data of the browser does the same.
crater-crush.template.save.v1
crater-crush.template.save.v1.mute

10 Development (optional)

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.0). 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.0 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 rules, the save, the pace of the first shifts and the 14 languages; stop and fix any error before going on.

npm ci
npm test

5. Preview: npm run dev starts a local server; open http://localhost:5260/ in your browser, play for a while, and stop the server with Ctrl+C.

npm run dev

6. Build: npm run build empties source/dist/ and copies index.html, the scripts, the style sheets, arte/, audio/ and fontes/ 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, or the Node.js message printed before npm test, 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)

On localhost or 127.0.0.1, adding ?devtest to the address exposes window.__cc for automated checks (state of the shift, end the shift, open a tab). On a public website it is ignored.

http://localhost:5260/?devtest

11 Updating and clearing the 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 Licences and credits

The game code, the artwork, the sound effects and the music were created for this project and are supplied under the license of the item you purchased.

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/fontes/OFL.txt. The game has no third-party code and no npm dependencies.

13 Common problems

  • Blank page or a game that never opens: the game was opened from the disk or a file is missing. Use a web host and keep every file and folder of game/ next to index.html.
  • A picture does not appear after you replace it: check the folder, the file name, the extension and the letter case against the original file.
  • No sound: browsers start audio only after the first click or tap. Check the sound effects and music options and the volume of the device.
  • The old version still appears after an update: clear the cache (see the section above).
  • Two copies of the game share their progress: give each copy its own saveKey in config.js.

14 FAQ

Does the game need a database or a server language?
No. It is a static website: HTML, CSS, JavaScript, pictures and sounds.
Can I remove Opal?
Yes. Set host: false in config.js: no character, no guided tips and no story cards.
Can I add a 15th language?
Yes. Copy idiomas/es.js and historia/es.js, translate them, add the code to LANGS, NAMES and LOCALE in idiomas.js, add the two script lines to index.html and the new texts to opal-textos.js. The tests expect 14 languages: update that number in tests/idiomas.test.mjs.
Does it work on phones?
Yes, in portrait and landscape, with its own phone layout. Tablets use a layout between phone and desktop.
Is there real money or advertising in the game?
No. Coins are only a game score. There are no ads, no purchases and no tracking.

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.