Contents
1 Overview
60 levels across 4 worlds (Spring Garden, Sunny Pond, Autumn Orchard, Snowy Garden), each with its own scenery, 12 tile pictures and a mole mascot with a matching outfit. Tap free tiles to send them to a 7-slot tray: three alike disappear. Undo, hint and shuffle helpers, coins, stars, a guided tutorial on level 1, a level map for every world, weather effects and animated screen transitions. 14 interface languages, no ads and no online services.
2 Installation
Extract the ZIP. Open DOCUMENTATION.html for this guide. Upload only the contents of game/
to your static HTTP(S) hosting, keeping all folders beside index.html. Open that address in a browser. No database, PHP, account or Node.js runtime is needed to play. Keep source/ and the full ZIP outside your public website.
3 Requirements and sound
Use a current browser with JavaScript, Canvas 2D, Web Audio and local storage enabled. Mouse and touch are supported. The first click, tap or key press unlocks sound; check browser autoplay settings and the in-game sound controls. Files are bundled locally; normal play makes no request to Polar ranking, advertising or payment services. Host the complete folder; opening game HTML through file:// is not the supported installation method.
Works in all current browsers on desktop and mobile: Chrome, Edge, Firefox, Safari (macOS, iPhone and iPad), Opera, Brave, Samsung Internet and other modern browsers. Minimum versions: Chrome, Edge and other Chromium-based browsers 105 or newer, Firefox 121 or newer, Safari 16 or newer (iOS and iPadOS 16 or newer). The game relies on ES modules, Canvas 2D, Web Audio, CSS container query units and the :has() selector, which these versions support. It was tested automatically in the Chromium, Firefox and WebKit (Safari) engines; as with any web game, test on the devices you target before publishing. On iPhone and iPad the first tap unlocks the sound, which is why the game starts with a "Tap to start" screen.
4 How to play
Tap a tile that is not covered by another tile; it flies to the tray. Three equal tiles in the tray disappear. If the tray fills up (7 tiles) without a match, you lose the level. Use Undo to take back a move, Hint to see a matching trio, and Shuffle to rearrange the tiles that are left. Level 1 teaches this step by step. Stars depend on how many helpers you used.
5 Interface guide
Marks on the screenshot
- Play button
- Sound and settings
Marks on the screenshot
- Level map
Marks on the screenshot
- Undo, Hint, Shuffle
- Tray (7 slots)
Marks on the screenshot
- Language selector
6 Files and customization
Gameplay numbers and the world list are in src/config.js; the rules are in src/game/rules.js and the 60 levels (tile counts per level) in src/game/levels.js; texts and the 14 languages in src/i18n.js; screens and systems in src/app/ (one small file per subject); artwork, sounds and music in assets/. The stylesheets are layered: the four files in css/ load in order and a later file can override an earlier one, so to change a rule edit the LAST file that sets it. Some internal names are in Portuguese (for example toupeira is the mole mascot, regador the watering can tile) and are kept as they are.
game/ upload these contents
source/ editable project (plain JavaScript, no dependencies)
index.html the page; loads the 4 style files and src/main.js
css/ 4 layered stylesheets (the last one that sets a rule wins)
src/main.js entry point
src/app/ screens and systems, one small file per subject
src/game/ rules.js and the 60 levels in levels.js
src/config.js world list, helpers, coins, feel numbers
src/i18n.js interface texts, 14 languages
src/audio/sfx.js sound effects and music
assets/ artwork, sounds, music and the font
test/ rule and language tests
tools/ local server and the build (copy) script
documentation/index.html this offline illustrated guide
DOCUMENTATION.html opens the guide
THIRD-PARTY-LICENSES/ font license
7 Languages
The game interface offers 14 languages: English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Russian, Turkish, Japanese, Korean, Chinese and Indonesian. The game starts in the language of the device (English if it is not on the list) and the player can change it in Settings. This offline buyer guide is in English, Brazilian Portuguese and Spanish; its dropdown detects the browser and remembers the selected guide language. To add a language, add a table to src/i18n.js, add its name to LANGS and run npm test: the language test checks that every text key is present. A link such as ?lang=de opens the game in a language.
8 Local saves
Progress belongs to this browser and origin. This buyer edition uses its own storage namespace, separate from the Polar website game. Clearing site data, using another browser or changing the hosting origin does not transfer progress. Private browsing and blocked storage may prevent persistence. There is no account, online ranking or cloud synchronization.
mahjong-garden.template.save.v1
9 Development
The ready-to-host game needs no Node.js. The editable project in source/ is plain JavaScript modules with no dependencies and no build step: Node.js 26.13 or newer (the current LTS) is only used to run the tests, serve the game locally and copy the files to game/. Follow the beginner steps below.
New to Node.js? 1) Install the LTS version from nodejs.org (Windows or macOS installer) or with your package manager on Linux; it must be 26.13 or newer. 2) Close and reopen the terminal, then type node -v to check. 3) Open a terminal inside the source folder (on Windows: open the folder, click the address bar, type cmd, press Enter). 4) Run the commands below one at a time. npm ci installs nothing because the project has no dependencies; it only checks the lock file. npm run serve opens the game at http://localhost:8080/ (press Ctrl+C to stop). npm run build copies the finished files to the game folder next to source.
cd source
npm ci
npm test
npm run serve
# http://localhost:8080/
npm run build
# copies index.html, css/, src/ and assets/ to ../game
10 Updating and cache
Keep a backup of your edited files before replacing a release. Upload all updated assets together and keep the public URL unchanged to preserve the browser save. Clear hosting or CDN caches when applicable. Test a private window after deployment; adding ?v=2 to the entry URL can help diagnose stale HTML but does not replace updating all assets.
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.
11 Licenses
The game artwork, audio and editable game code are supplied under the purchased item license. Included fonts retain their complete SIL Open Font License notices in game/licenses/ and THIRD-PARTY-LICENSES/. Developer dependencies retain their own upstream licenses. Original production PNG masters and artwork-generation tools are not included.
12 Troubleshooting
If the page is blank, check that every folder was uploaded, the URL is served over HTTP(S), and the browser console and Network panel have no missing files. Module builds need correct JavaScript MIME types. If sound is silent, interact once and inspect browser and game volume. If progress resets, inspect storage permissions and origin changes. The guide itself also opens offline through file://.
13 Support
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.