Polar Games

Drop. Merge two twins. Grow to the Black Hole. · 1.0.0

Space Merge

A physics merge game set in space: drop cute planets into a glass capsule, merge two equal ones into the next size and climb from Stardust to the Black Hole. Plain HTML, CSS and JavaScript ES modules with no compile step, 14 interface languages and phone, tablet and desktop layouts. It runs with no account, server or database.

Version 1.0.0 Edition HTML5 static edition

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

Contents
  1. Overview
  2. Install the ready-to-play game
  3. Requirements
  4. How to play and controls
  5. Interface
  6. Settings and language
  7. File map
  8. Customize and reskin
  9. Languages
  10. Saved progress
  11. Install Node.js and edit the source
  12. Updates and cache
  13. Troubleshooting
  14. Frequently asked questions
  15. Support and licenses
  16. For AI assistants

1 Overview

Space Merge is a drop-and-merge physics game. The player aims a planet above a glass capsule and releases it; when two equal planets touch they merge into the next one of the 11 sizes: Stardust, Asteroid, Moon, Mercury, Mars, Earth, Neptune, Saturn, Jupiter, Star and Black Hole. Merging two Black Holes makes both vanish for a big bonus. The run ends with "Capsule Full!" when a planet stays above the line at the capsule mouth for 2 seconds.

This edition has no online ranking, ads, in-app purchases or "Continue" option. The best score, collection, missions, stars, capsule colours and settings are saved locally in the player's browser only. Reloading the page starts a new run.

The download includes the ready-to-host game, the complete editable source (the same files, readable and commented, with tests and a local server), this guide and the third-party license notices.

START-HERE.txt
DOCUMENTATION.html
CUSTOMIZATION.html
CHANGELOG.txt
documentation/index.html
documentation/customization.html
game/
source/
THIRD-PARTY-LICENSES/

2 Install the ready-to-play game

Only the game/ folder needs to be uploaded to play.

  1. Extract the whole ZIP on your computer.
  2. Upload the contents of game/ to a folder on static hosting, using FTP or your host's file manager. Keep the folder structure exactly as it is.
  3. Open that folder's address in a modern browser. All paths are relative, so the game also works in a subfolder.
  4. Tap or click the start screen once: browsers only play audio after a user gesture. Test on the phones, tablets and computers you plan to support.
Warning Do not open index.html straight from the disk (a file:// address): browsers block ES modules and sounds there. Use a web host, or the local server described in "Install Node.js and edit the source".

3 Requirements

  • Any static web host able to serve plain files over HTTP or HTTPS (HTTPS recommended).
  • A current desktop or mobile browser with JavaScript enabled.
  • Node.js 26.13 or newer (current LTS line), only if you want to run the tests, the local server or the build command.

No database, PHP, backend, account or internet service is needed. The game, the physics library, the fonts, the art and the sounds are all inside game/.

4 How to play and controls

Move the planet that hangs above the capsule and release it. A dotted line shows where it will fall.

  • Touch screens: drag to aim and lift the finger to drop.
  • Mouse: move to aim and click to drop.
  • Keyboard: Left and Right arrows (or A and D) aim; Space, Enter or Down arrow drop; B uses WARP; Esc or P pauses and resumes.
  • The round buttons at the top switch the sound on or off, open Settings and pause the game.

Only the 5 smallest planets are dropped, and the first 10 drops use only the 3 smallest. The "Next" panel shows the planet that comes after the current one. Dropping a planet right on its twin is a Bullseye: Bullseyes in a row multiply the merge points up to x3, and quick merges chain into combos.

WARP: every merge fills the gauge around the WARP button on the capsule base. When it is full, WARP spins everything in the capsule and crushes up to 7 of the smallest planets (Stardust and Asteroid) for points. The first WARP needs a gauge of 100 and each later one needs 25 more, up to 250.

Special planets: the first appears after about 50 seconds of play and the next ones every 80 to 120 seconds. A one-line tip explains each special the first time it shows up.

  • Ice Comet: slows time for 5 seconds, so many planets can be dropped quickly; merges score more while it lasts.
  • Meteor: bursts half a second after landing and pops the small planets around it (up to Mercury).
  • Prism Star: merges with any planet it touches.
  • Space Junk: arrives later in a run and never merges. WARP crushes it, a Meteor pops it, and a merge of Earth or bigger next to it destroys it.

Star Frenzy: 4 Bullseyes in a row (or a combo of 9) start a 6-second frenzy in which small planets rain onto their twins and merges score double.

Between runs: the Collection shows the planets already created, 3 missions are always open (each one completed gives a star), stars unlock 6 capsule colours, and the Daily Challenge gives everyone the same sequence of planets for the day, with a goal of 7,000 points and a streak counter.

5 Interface

Real captures of the shipped build at 1280 x 720 and on a phone, with numbered marks for the elements described in this guide.

Main menu (landscape)
Main menu (landscape)

Marks on the screenshot

  1. Play: starts a new run
  2. Daily Challenge: the same planet sequence for everyone today
  3. Collection: planets created, missions and capsule colours
  4. Settings
  5. Language: switches the interface language instantly
A run in progress
A run in progress

Marks on the screenshot

  1. Evolution wheel: the 11 planets in merge order; the newest one lights up
  2. The planet being aimed, with the dotted drop line
  3. Score and best score
  4. Next planet
  5. WARP button and its gauge
  6. Sound, Settings and Pause buttons
Special planets: a Meteor in hand, a Prism Star merging and an Ice Comet as the next planet
Special planets: a Meteor in hand, a Prism Star merging and an Ice Comet as the next planet

Marks on the screenshot

  1. Meteor: pops the small planets around it
  2. Ice Comet coming next: slows time for 5 seconds
Settings, opened during a run
Settings, opened during a run

Marks on the screenshot

  1. Music and Effects volumes
  2. Vibration (phones that support it)
  3. Less Motion: calmer camera and fewer particles
  4. Interface language
"Capsule Full!": the end of a run, here with a new record
"Capsule Full!": the end of a run, here with a new record

Marks on the screenshot

  1. Final score and best score
  2. Run summary: biggest planet, best combo, merges, WARPs and time
  3. Play Again starts a new run at once
Collection on a phone: planets created, the 3 open missions and the 6 capsule colours
Collection on a phone: planets created, the 3 open missions and the 6 capsule colours
The portrait phone layout
The portrait phone layout

6 Settings and language

Settings opens from the gear on the menu and in the game. It has Music and Effects volumes, Vibration, Less Motion and Language. The run is paused while Settings is open and continues when it closes. Every choice is saved in the browser.

On the first visit the game uses the browser language when it is one of the 14 supported, otherwise English. A language picked by the player is remembered. For testing you can also add ?lang=pt (or another code) to the address.

7 File map

game/ and source/ contain the same game files: game/ is what you upload, and source/ is the project you edit, with tests and tools. Run npm run build in source/ to copy your changes into source/dist/, which is identical to game/.

Path What it is
game/ The ready-to-host game. Upload its contents.
source/index.html Entry page: the canvas, the interface layer and the module that starts the game.
source/src/config.js Every number of the game in one commented file: planets (size, points, colours), drop odds, rules, WARP, specials, Star Frenzy, physics, feel and layout. Also the version and the save prefix.
source/src/main.js Connects everything: game states, input, saving, pause and the main loop.
source/src/game/ Rules without drawing: physics world (Planck.js), merges, score and combos, the planet sequence, missions, collection and Daily Challenge.
source/src/render/ Canvas drawing: capsule, planets and faces, background, particles, camera shake and the HUD layout.
source/src/ui/ Screens in HTML on top of the canvas (start screen, menu, settings, language, pause, collection, game over), the HUD and the tutorial.
source/src/audio/ Sound engine, sound effects, music and the optional narrator hook.
source/src/lib/locales/ Interface texts, one file per language.
source/style.css Styles of every screen. The look scales with the screen size through the --px unit.
source/assets/ Art (WebP), icons, music and sounds (MP3), fonts and audio.json, the list of sound files.
source/lib/planck/ Planck.js 1.5.0 physics library (MIT license), readable version.
source/test/ Tests run by npm test: rules, physics, specials, saves and the 14 languages.
source/tools/ build.mjs (copy to dist/), serve.mjs (local server) and check-node.mjs (Node.js version check).
source/src/dev/demo-states.js Ready-made screens for screenshots and checks. It only loads on a local address with ?test.

Internal names

The game engine is shared with other merge themes, so some names in the code differ from what the player sees. They are kept stable so saves stay compatible. Rename them only if you also update every use.

In the code In the game
fruit, FRUITS Planets (the 11 merge sizes)
glass, basket, lid The glass capsule and its lid
blend, blender, steam WARP and its gauge
frenzy Star Frenzy
ice Ice Comet
pepper Meteor
rainbow Prism Star
rotten Space Junk
golden Two Black Holes merging (the big bonus)
juice, liquid Particle colours and the stardust haze at the capsule bottom
cherry, mint, sky, lemon, grape, gold The 6 capsule colours (skin ids)

8 Customize and reskin

Everything can be changed in source/ with any text editor. Work on a copy, change one thing at a time, test with npm run dev, then run npm run build and upload the new dist/.

Tip Step-by-step recipes for people who do not program (replace a planet, change a text, a sound, colours, difficulty, publish) are in CUSTOMIZATION.html, in the root of the download (in English).
  • Planet art: replace the files in source/assets/art/items/ keeping the names (00-stardust.webp to 10-blackhole.webp); square pictures with a transparent background work best.
  • Planet sizes, points and colours: FRUITS in source/src/config.js (the names shown on screen are in the language files).
  • Capsule, background, logo and menu art: basket.webp, lid.webp, bg-landscape.webp, bg-portrait.webp, logo.webp and menu-hero.webp in source/assets/art/. If the capsule shape changes, adjust GLASS in config.js.
  • Buttons and panels: source/assets/art/ui/ and source/style.css.
  • Texts: source/src/lib/locales/, one file per language. Keep the { n } and { fruit } markers.
  • Sounds and music: replace the MP3 files in source/assets/sfx/ and source/assets/music/ keeping the names, or change the list in source/assets/audio.json.
  • Difficulty: RULES, DIFFICULTY, SPECIAL and FRENZY in config.js; the mission list and the capsule colours are in source/src/game/meta.js.
// source/src/config.js (excerpt)
export const FRUITS = [
  { key: 'stardust', r: 0.04, pts: 1, w: 30, color: '#c9a8ff', ... },
  // ... one entry per planet, smallest to biggest
];
export const RULES = { dropCooldown: 0.45, dangerTime: 2.0, meterMax: 100, ... };
Tip After changing numbers, run npm test: the tests check that the rules, the physics and every language still work.

9 Languages

The interface ships in 14 languages: English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean and Chinese (Simplified).

Each language is a file in source/src/lib/locales/ with the same keys as en.js; a key missing in a language falls back to English. The list of languages is in source/src/lib/locales.js. npm test checks that every language has the same keys and markers as English.

10 Saved progress

Best score, collection, missions, stars, capsule colour, settings and the first-run tips are saved automatically in the browser's local storage, under keys that start with space-merge.template.save.v1.. The current run itself is not saved.

  • Clearing the site data for the game's address deletes this save.
  • There is no cloud save or account: progress stays in that browser on that device.
  • To host two copies of the game on the same domain, change STORAGE_PREFIX in source/src/config.js in one of them.

11 Install Node.js and edit the source

Node.js is only needed for the optional tools: the tests, the local server and the build command. The game itself is plain files and needs nothing installed.

  1. Download the LTS version of Node.js (26.13 or newer) from nodejs.org and install it with the default options (Windows and macOS installers; on Linux use the package from nodejs.org or your distribution).
  2. Open a new terminal (Windows: PowerShell or Command Prompt; macOS: Terminal) and check the versions with the first two commands below.
  3. Go to the extracted source/ folder, for example cd Downloads/space-merge-static-1.0.0/source.
  4. Run npm ci. The project has no npm dependencies, so this only checks package-lock.json, but it keeps the usual workflow.
  5. Run npm test for the tests, and npm run dev to play the source at http://localhost:5188/ (stop it with Ctrl+C).
  6. Run npm run build. It deletes and writes source/dist/ again; upload the contents of dist/ to your host.
node --version
npm --version
npm ci
npm test
npm run dev
npm run build

Common problems:

  • "node" or "npm" is not recognized: Node.js is not in the PATH yet. Close the terminal and open a new one, or reinstall Node.js.
  • Windows PowerShell says running scripts is disabled for npm.ps1: use Command Prompt, or type npm.cmd ci, npm.cmd test and so on.
  • ENOENT or "Could not read package.json": the terminal is not inside the source/ folder.
  • EBADENGINE or "needs Node.js 26.13.0 or newer": install the current LTS version of Node.js.

Port 5188 is busy: choose another port first (PowerShell: $env:PORT=8090; macOS and Linux: PORT=8090 npm run dev).

12 Updates and cache

To publish a new version, upload the full contents of the new game/ (or dist/) over the old files, overwriting them. Saved progress is kept.

If players still see the old version after an update, it is almost always the browser or host cache, not a failed upload.

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.

13 Troubleshooting

  • Blank page: open the browser console (F12) and look for a file that failed to load; confirm every file of game/ was uploaded, including src/, lib/ and assets/.
  • It works on your host but not from the disk: browsers block ES modules on file:// addresses. Use a web address or npm run dev.
  • No sound: audio starts after the first tap, click or key press, by browser rule. Check that Music and Effects in Settings are not at 0% and that the sound button is on.
  • Scripts served with the wrong type: the host must send .js files as JavaScript (any normal host does). Do not rename the files.

14 Frequently asked questions

Do I need to build the game?
No. Upload the contents of game/ to any static host. source/ is only for editing, testing and rebuilding.
Does the game need a server or database?
No. It is static files; progress is saved in the player's browser.
Can I change the planets and the theme?
Yes. Replace the art in source/assets/art/, the sounds in source/assets/sfx/ and source/assets/music/, the texts in the language files and the numbers in source/src/config.js, then run npm run build.
Does it work without internet?
Once uploaded, the game makes no requests outside its own folder: there is no CDN, analytics or ad service. It needs a web address only because browsers require one for ES modules.
Can I resell this template as-is?
Check the license terms of the item page where you bought it before reselling, redistributing or reusing it in another product.

15 Support and licenses

The game uses the Planck.js physics library (MIT license) and the Fredoka font (SIL Open Font License 1.1). Their notices are in THIRD-PARTY-LICENSES/, game/lib/planck/LICENSE.txt and game/assets/fonts/OFL.txt; keep them with your product.

For product support or custom development, write to the address below.

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.

For AI assistants

  • Read the File map and Customize sections first. Upload only game/ (or source/dist/); source/ is the editable project.
  • Keep the save prefix, the relative paths, the internal names listed in the File map and the { n } and { fruit } markers unless the buyer asks for a change. Run npm test after every change.
  • Do not assume an account, a server, ads, payments or an online ranking: this edition has none, and the code is the source of truth.