Contents
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. Extract
crater-crush-static-1.0.0.zipon 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/crater-crush/. -
3. Upload only the contents of the
game/folder, so thatindex.htmlsits directly inside the target folder. -
4. Keep
arte/,audio/,fontes/,idiomas/,historia/, the.jsfiles and the.cssfiles besideindex.html, with names and letter case exactly as extracted. -
5. Open
https://your-domain.example/games/crater-crush/in a modern browser.
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.htmldirectly 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
Marks on the screenshot
- DIG! button
- Options
- Relic collection
- Language
Marks on the screenshot
- Coins
- Combo meter
- Ores
- Clock
- Pause
- Goals
- Level and XP
- End the shift
Marks on the screenshot
- Ores
- Open the hub
- Next shift
Marks on the screenshot
- Hub tabs
- Upgrade tree
- Selected upgrade
- Buy
- DIG! button
Marks on the screenshot
- Sound effects
- Music
- Less motion
- Language
Marks on the screenshot
- Coins
- Pause
- 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 keysaveKey.host: falseswitches Opal off. -
motor.js: the rules without drawing (stats, prices, XP, ore spawn, save).jogo.js,jogo-campo.js,jogo-telas.jsandjogo-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) andidiomas/(one file per language): the interface texts.historia.jsandhistoria/: the story texts.opal-textos.js: the texts of Opal's tips. -
opal.jsandopal-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.csstoestilo-6.cssandopal.css: the styles, linked in this order byindex.html(keep the order). -
arte/: every picture (WebP).audio/: sound effects andmusic.mp3.fontes/: the Fredoka font and its licenseOFL.txt.
7 Customizing
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.
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
saveKeyinconfig.jsto 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).
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 toindex.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
saveKeyinconfig.js.
14 FAQ
Does the game need a database or a server language?
Can I remove Opal?
host: false in config.js: no character, no guided tips and no story
cards.
Can I add a 15th language?
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?
Is there real money or advertising in the game?
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.