Contents
1 Overview
Dim Sum Merge is an HTML5 physics merge puzzle game. The player drops dim sum into a tall bamboo steamer basket; two equal ones that touch merge into the next, bigger one. The ladder has 11 dim sum, from the tiny Tangyuan to the Golden Bun. The game ends when the basket is full: an item stays above the top line for 2 seconds.
Merges fill the STEAM gauge; the STEAM button shakes the basket with a jet of steam and puffs away up to 7 of the two smallest dim sum (Tangyuan and Mochi), turning them into points. Dropping an item right on its twin is a Bullseye, and Bullseyes in a row multiply the points (x1.5 up to x3). Four special items appear a few times per game (Ice cube, Chili, Rainbow dumpling, Burnt bun), and big combos start the Steam Frenzy.
Around the basket: a Daily Challenge with a goal and a streak of days, 3 missions at a time that give stars, a collection of the dim sum created, and 6 steamer baskets unlocked with stars. 14 languages, desktop, tablet and phone (portrait and landscape), mouse, touch and keyboard. Everything is plain HTML, CSS and JavaScript: no account, no server, no external services.
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
dim-sum-merge-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/dim-sum-merge/. -
3. Upload only the contents of the
game/folder, so thatindex.htmlsits directly inside the target folder. -
4. Keep
assets/,lib/,src/,style.cssandmanifest.webmanifestbesideindex.html, with names and letter case exactly as extracted. -
5. Open
https://your-domain.example/games/dim-sum-merge/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://) does not work, because browsers do not load JavaScript modules that way. - A current browser: Chrome, Edge, Firefox, Safari or Opera, on desktop or mobile.
- About 6 MB of space on the server. The game makes no request to other websites: the physics library and the fonts are inside the package.
-
Node.js is only needed to run the tests or to rebuild the game from
source/(see the development section).
4 How to play
Move the dim sum at the top of the basket with the mouse or a finger and release to drop it. The Next bubble shows the item that comes after it. Only the 5 smallest dim sum drop from the top; the bigger ones are made by merging, and the first 10 drops of a game are the 3 smallest.
Two equal dim sum that touch merge into the next one, with points for every new item. Merges one right after the other make a combo. Creating the Golden Bun gives a bonus of 600 points. When the STEAM gauge is full, press STEAM: each use costs a little more (100, then 125, 150 and so on up to 250).
Special items: the Ice cube nearly stops time for 5 seconds (drop as many as you want, merges are worth more); the Chili pops the small dim sum around it; the Rainbow dumpling merges with any dim sum it touches; the Burnt bun never merges, so STEAM it, pop it with a Chili or merge something big next to it. The Steam Frenzy starts after 4 Bullseyes in a row or a huge combo: for 6 seconds small dim sum rain down and merges are worth double.
Keyboard: Left and Right arrows (or A and D) aim, Space, Enter or Down arrow drop, B presses STEAM, Esc or P pause. The first game shows a short tutorial with a hand.
5 Screens
Marks on the screenshot
- Play
- Daily Challenge
- Collection, missions and baskets
- Settings
- Language
Marks on the screenshot
- Evolution wheel
- Score and best score
- Next item
- STEAM button and gauge
- Sound on and off
- Settings
- Pause
Marks on the screenshot
- Vibration
- Less Motion
- Language
- Back
Marks on the screenshot
- Dim sum created
- Missions
- Steamer baskets
Marks on the screenshot
- Highlights of the game
- Play again
- Back to the menu
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. The code is plain JavaScript ES modules with comments
in Portuguese; the list below says what each part is.
game/ upload these contents to your web host
index.html the page: loads style.css and src/main.js
style.css styles of the screens (colours at the top, in :root)
manifest.webmanifest name and icons when the game is added to a home screen
src/main.js starts everything: states, input, game loop, saving
src/config.js every rule and number of the game, STORAGE_PREFIX
src/game/ logic: physics world, rules, spawner, missions and Daily Challenge (meta.js)
src/render/ canvas drawing: basket, dim sum and faces, steam, effects, HUD layout
src/ui/ HTML screens (menu, settings, languages, pause, game over, collection), tutorial
src/audio/ sound engine, sound effects, music player
src/lib/locales/ interface texts, one file per language
src/dev/mock.js preview states for screenshots (only with ?test on localhost)
lib/planck/ Planck.js 1.5.0 physics library (MIT) and its license
assets/art/ pictures (WebP): items, specials, faces, ui, icons, basket, logo, backgrounds
assets/sfx/, assets/music/ sound effects and the two music tracks (listed in assets/audio.json)
assets/fonts/ Fredoka font and OFL.txt
assets/icons/ app icons
DOCUMENTATION.txt short note that points to this guide
source/ the same editable files, plus:
package.json, package-lock.json
README.md
test/ node --test test/ (28 checks)
tools/build.mjs copies the game into dist/
tools/serve.mjs local preview server (npm run dev, npm run preview)
tools/check-node.mjs checks the Node.js version before the commands
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/ Planck.js and Fredoka licenses
-
src/config.js: every rule and number of the game (the 11 dim sum with their size and points, the STEAM gauge, physics, combo, Bullseye, special items, Steam Frenzy, difficulty over time) and the save prefixSTORAGE_PREFIX. -
src/game/: the logic without drawing:world.js(physics with Planck.js),rules.js(score, combo, gauge, game over),spawner.js(which item comes next),game.js(the game itself) andmeta.js(missions, Daily Challenge, collection and steamer baskets). -
src/render/: the canvas drawing (basket, dim sum and their faces, steam, effects, background, HUD layout).src/ui/: the screens in HTML (menu, settings, languages, pause, game over, collection) and the tutorial.src/juice.js: the feel of the game (shakes, words, sounds at each event). -
src/lib/locales/: one file per language with the interface texts.src/audio/: the sound engine, the sound effects and the music player. -
assets/art/: every picture (WebP).assets/sfx/andassets/music/: sound effects and the two music tracks, listed inassets/audio.json.assets/fonts/: the Fredoka font and its licenseOFL.txt.lib/planck/: the Planck.js physics library and its license. -
style.css: the styles of the screens.index.htmlloadsstyle.cssandsrc/main.js, which starts everything.
7 Internal names in the code
The game engine started as a fruit merge game, so a few names in the code still use those words. They are only names: nothing of them appears on the screen.
-
FRUITS,fruit,fruits.js: the 11 dim sum of the ladder (in the order ofsrc/config.js).blender.js,blend,BLEND: the steamer basket and the STEAM action.liquid.js: the steam mist at the bottom of the basket. -
frenzy: the Steam Frenzy.pepper: the Chili.rotten: the Burnt bun.golden: the Golden Bun.juice: the visual and sound feedback of each event. -
Steamer basket ids in
src/game/meta.js:cherrynatural bamboo,mintwalnut,skyred lacquer,lemonjade,grapeplum,goldroyal blue. -
Sound files:
plop.mp3an item lands,squish.mp3a merge,splash.mp3an item falls into the steam,blender.mp3the STEAM jet,crunch.mp3a small item puffs away,slurp.mp3the steam turns into points,guzheng-grave.mp3andguzheng-agudo.mp3the two strings of the merge notes. -
src/audio/voice.jsis an optional narrator: this edition has no voice files, so it stays silent.game.revive()is a second-chance helper that this edition does not show.
8 Customizing
CUSTOMIZATION.html in the main folder of the download, or
documentation/customization.html.
Customization Guide (step by step, in English)
Rules and balance: edit src/config.js and reload the page. Examples: FRUITS (size
r, points pts and how often each small item drops w),
RULES (gauge, combo, Golden Bun bonus, Bullseye), SPECIAL (when special items
appear and what they do), FRENZY and DIFFICULTY.
Pictures: replace a file in assets/art/ with another WebP of the same name and a similar size.
The dim sum are assets/art/items/00-tangyuan.webp to 10-golden.webp; the faces are
drawn on top from assets/art/faces/. The basket is basket.webp and
lid.webp, the logo logo.webp, the backgrounds bg-portrait.webp and
bg-landscape.webp, buttons and panels are in assets/art/ui/.
Colours of the interface: the variables at the top of style.css, for example
--gold and --red. Steamer baskets: their tint colours and prices in stars are
SKINS in src/game/meta.js; missions are the POOL list in the same
file, and the Daily Challenge goal is DAILY_GOAL.
Names of the dim sum on screen: the keys tangyuan to golden_bun in each language
file of src/lib/locales/.
Sounds and music
Each recorded sound effect is one MP3 in assets/sfx/ (see the names above). Replace a file
keeping its name. The list of loaded files is assets/audio.json.
The music is assets/music/menu.mp3 (menu) and assets/music/main.mp3 (game), played
in a loop. Replace them keeping the names. If a recorded file is missing, the game uses its synthesized
sound or stays silent.
STORAGE_PREFIX in src/config.js, otherwise they share records, missions and
settings.
9 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 in the menu or in the settings. ?lang=pt in the address forces a language.
To change a text, edit the same key in src/lib/locales/<code>.js. English is the base: a
key missing in another language falls back to English. Long texts shrink to fit their button and never break
into two lines.
npm test checks that every language has every key and the same markers as English. Russian,
Japanese, Korean and Chinese use the bold font of the device, because Fredoka has no Cyrillic or CJK
letters.
10 Saving and resetting
- Records, settings, language, missions, stars, the collection, the chosen basket and the Daily Challenge streak are saved automatically in the browser of each player (localStorage). Nothing is sent to a server. A game in progress is not saved: reloading the page starts a new game.
-
Every key starts with the prefix below (for example the best score is
dim-sum-merge.template.save.v1.best2). ChangeSTORAGE_PREFIXinsrc/config.jsto give a copy its own saves. - 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 that start with this prefix, then reload. Clearing the site data of the browser does the same.
dim-sum-merge.template.save.v1.
11 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 runs 28 checks: rules, physics, special items, the Steam
Frenzy, the 14 languages and the standalone edition; stop and fix any error before going on.
npm ci
npm test
5. Preview: npm run dev starts a local server; open http://localhost:5180/ 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,
manifest.webmanifest, style.css, src/, lib/ and
assets/ into it. dist/ is what you publish; while the source is unchanged it
matches game/ file by file. npm run preview serves dist/ at
http://localhost:5181/.
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.
Preview states (local addresses only)
On localhost or 127.0.0.1, adding ?test to the address loads
src/dev/mock.js: type __mock.menu(), __mock.game(),
__mock.settings(), __mock.over() or __mock.collection() in the
browser console to open a screen in a ready state, for screenshots and layout checks. On a public website
the parameter is ignored.
http://localhost:5180/?test
12 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.
13 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.
Third-party parts, with their complete license texts in THIRD-PARTY-LICENSES/: the Planck.js
1.5.0 physics library (MIT license, lib/planck/LICENSE.txt) and the Fredoka font (SIL Open Font
License 1.1, assets/fonts/OFL.txt). There are no npm dependencies.
14 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 (the TOUCH TO START screen does this). Check the music and effects volume in the settings 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 records: give each copy its own
STORAGE_PREFIXinsrc/config.js.
15 FAQ
Does the game need a database or a server language?
Can I change the dim sum into other items?
assets/art/items/ keeping the names, change their names in
the language files and, if the new items have another size, the r values in
FRUITS in src/config.js. The physics uses circles.
Can I add a 15th language?
src/lib/locales/en.js to a new file, translate it, import it in
src/lib/locales.js and add its code to LANGS and LANG_NAMES. The
language screen shows it automatically; check the layout with long words.
Does it work on phones?
Is there real money or advertising in the game?
16 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.