Contents
- Overview
- Install the ready-to-play game
- Requirements
- How to play and controls
- Interface
- Settings and language
- File map
- Customize and reskin
- Languages
- Saved progress
- Install Node.js and edit the source
- Updates and cache
- Troubleshooting
- Frequently asked questions
- Support and licenses
- 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.
- Extract the whole ZIP on your computer.
- 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. - Open that folder's address in a modern browser. All paths are relative, so the game also works in a subfolder.
- 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.
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.
Marks on the screenshot
- Play: starts a new run
- Daily Challenge: the same planet sequence for everyone today
- Collection: planets created, missions and capsule colours
- Settings
- Language: switches the interface language instantly
Marks on the screenshot
- Evolution wheel: the 11 planets in merge order; the newest one lights up
- The planet being aimed, with the dotted drop line
- Score and best score
- Next planet
- WARP button and its gauge
- Sound, Settings and Pause buttons
Marks on the screenshot
- Meteor: pops the small planets around it
- Ice Comet coming next: slows time for 5 seconds
Marks on the screenshot
- Music and Effects volumes
- Vibration (phones that support it)
- Less Motion: calmer camera and fewer particles
- Interface language
Marks on the screenshot
- Final score and best score
- Run summary: biggest planet, best combo, merges, WARPs and time
- Play Again starts a new run at once
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/.
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.webpto10-blackhole.webp); square pictures with a transparent background work best. - Planet sizes, points and colours:
FRUITSinsource/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.webpandmenu-hero.webpinsource/assets/art/. If the capsule shape changes, adjustGLASSinconfig.js. - Buttons and panels:
source/assets/art/ui/andsource/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/andsource/assets/music/keeping the names, or change the list insource/assets/audio.json. - Difficulty:
RULES,DIFFICULTY,SPECIALandFRENZYinconfig.js; the mission list and the capsule colours are insource/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, ... };
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_PREFIXinsource/src/config.jsin 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.
- 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).
- Open a new terminal (Windows: PowerShell or Command Prompt; macOS: Terminal) and check the versions with the first two commands below.
- Go to the extracted
source/folder, for examplecd Downloads/space-merge-static-1.0.0/source. - Run
npm ci. The project has no npm dependencies, so this only checkspackage-lock.json, but it keeps the usual workflow. - Run
npm testfor the tests, andnpm run devto play the source athttp://localhost:5188/(stop it with Ctrl+C). - Run
npm run build. It deletes and writessource/dist/again; upload the contents ofdist/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 testand 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, includingsrc/,lib/andassets/. - It works on your host but not from the disk: browsers block ES modules on
file://addresses. Use a web address ornpm 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
.jsfiles as JavaScript (any normal host does). Do not rename the files.
14 Frequently asked questions
Do I need to build the game?
game/ to any static host. source/ is only for editing, testing and rebuilding.Does the game need a server or database?
Can I change the planets and the theme?
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?
Can I resell this template as-is?
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/(orsource/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. Runnpm testafter 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.