A physics merge game in a bamboo steamer · 1.0.0

Dim Sum Merge

This guide explains how to install, play, 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. Internal names in the code
  8. Customizing
  9. Languages
  10. Saving and resetting
  11. Development (optional)
  12. Updating and clearing the cache
  13. Licences and credits
  14. Common problems
  15. FAQ
  16. Support

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. 1. Extract dim-sum-merge-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/dim-sum-merge/.
  3. 3. Upload only the contents of the game/ folder, so that index.html sits directly inside the target folder.
  4. 4. Keep assets/, lib/, src/, style.css and manifest.webmanifest beside index.html, with names and letter case exactly as extracted.
  5. 5. Open https://your-domain.example/games/dim-sum-merge/ 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://) 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

Main menu: Play, the Daily Challenge, the collection, the settings and the language.
Main menu: Play, the Daily Challenge, the collection, the settings and the language.

Marks on the screenshot

  1. Play
  2. Daily Challenge
  3. Collection, missions and baskets
  4. Settings
  5. Language
A game: the evolution wheel of the 11 dim sum, the score and best score, the next item, the STEAM button,
sound, settings and pause.
A game: the evolution wheel of the 11 dim sum, the score and best score, the next item, the STEAM button, sound, settings and pause.

Marks on the screenshot

  1. Evolution wheel
  2. Score and best score
  3. Next item
  4. STEAM button and gauge
  5. Sound on and off
  6. Settings
  7. Pause
Settings: music and effects volume, vibration, Less Motion and the language.
Settings: music and effects volume, vibration, Less Motion and the language.

Marks on the screenshot

  1. Vibration
  2. Less Motion
  3. Language
  4. Back
Collection: the dim sum created so far, the 3 missions with their stars, and the 6 steamer baskets.
Collection: the dim sum created so far, the 3 missions with their stars, and the 6 steamer baskets.

Marks on the screenshot

  1. Dim sum created
  2. Missions
  3. Steamer baskets
Game over: the score, the best score, the biggest item, best combo, merges, steams and time.
Game over: the score, the best score, the biggest item, best combo, merges, steams and time.

Marks on the screenshot

  1. Highlights of the game
  2. Play again
  3. Back to the menu
Portrait phone: the HUD moves to the top and the basket takes the rest of the screen.
Portrait phone: the HUD moves to the top and the basket takes the rest of the screen.

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 prefix STORAGE_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) and meta.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/ and assets/music/: sound effects and the two music tracks, listed in assets/audio.json. assets/fonts/: the Fredoka font and its license OFL.txt. lib/planck/: the Planck.js physics library and its license.
  • style.css: the styles of the screens. index.html loads style.css and src/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 of src/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: cherry natural bamboo, mint walnut, sky red lacquer, lemon jade, grape plum, gold royal blue.
  • Sound files: plop.mp3 an item lands, squish.mp3 a merge, splash.mp3 an item falls into the steam, blender.mp3 the STEAM jet, crunch.mp3 a small item puffs away, slurp.mp3 the steam turns into points, guzheng-grave.mp3 and guzheng-agudo.mp3 the two strings of the merge notes.
  • src/audio/voice.js is 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

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)

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.

Warning Save prefix: if you host more than one copy of the game on the same domain, give each one its own 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). Change STORAGE_PREFIX in src/config.js to 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).

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.

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 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 (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_PREFIX in src/config.js.

15 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 change the dim sum into other items?
Yes. Replace the 11 pictures in 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?
Yes. Copy 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?
Yes, in portrait and landscape, with its own layout for each. The interface scales with the window, from small phones to large monitors.
Is there real money or advertising in the game?
No. Stars are earned with missions and only unlock steamer baskets. There are no purchases and no tracking.

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.