Contents
1 Overview
A magical bubble shooter: aim, match three of the same colour and free the kittens trapped at the top of each board. 100 painted levels across 10 worlds (the saga keeps going after level 100 with repeating art), a world chest at the end of every map page, a ten-kitten album, a daily challenge with a streak and an endless mode with a best score. Good shots fill a spell meter: tap it for Abracadabra and three comet shots. Bombs, rainbow bubbles and vortexes unlock at levels 4, 8 and 12. A guided tutorial on level 1 is narrated by the witch in English, Brazilian Portuguese and Spanish; the other 11 interface languages use the English voice.
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.
4 How to play
Drag anywhere to aim and let go to shoot; the dotted line shows the full path and where the bubble will land (switch to a shorter line in Settings). Tap the next bubble or the launcher to swap them. Three or more of the same colour pop, and bubbles left hanging fall. Free every kitten to win before you run out of shots or the ceiling comes down. Tap a booster under the launcher to arm it; tap the glowing spell meter when it is full. Settings (gear) holds language, vibration, Reduce effects and Full aim line; in a level the same panel pauses the round, its X resumes and its small key goes back to the map.
5 Interface guide
Marks on the screenshot
- Play
- Settings
Marks on the screenshot
- Play
Marks on the screenshot
- Bubble board
- Launcher and next bubble
Marks on the screenshot
- Language
6 Files and customization
Levels are generated from their number in src/levelgen.ts (shapeFor holds the difficulty curve; RESEED swaps unfair boards); levels 1 and 2 are hand-made in src/level.ts. Endless rules are in src/endless.ts, world art and node positions in src/worlds.ts, booster unlock levels in src/boosters.ts (UNLOCK_AT). Images are listed in public/theme/witch/theme.json; replace a file with the same name and size to reskin. Text lives in src/i18n/; keep the {n}-style placeholders. Voice lines are listed in each public/audio/voice-jessica-v4*/voices.json; a file named name--2.mp3 is played as a variation of name. ?debug=1 on localhost enables the + key (win the level / unlock the next one) for testing. Internal names such as worldProposal and rescue are kept on purpose.
game/ upload these contents
source/ editable developer edition
documentation/index.html offline illustrated guide
DOCUMENTATION.html guide shortcut
THIRD-PARTY-LICENSES/ complete notices
source/src/main.ts entry: canvas, input, loading screen
source/src/game.ts the board, shots, rules, spell, endless
source/src/game-draw.ts drawing of the board, launcher and characters
source/src/meta.ts title, map and panels (menu layer)
source/src/meta-map.ts the saga map, chests, page arrows
source/src/meta-panels.ts settings, album, chest and reward cards
source/src/levelgen.ts level generator and difficulty curve
source/src/worlds.ts ten world maps and level node positions
source/src/hud.ts, fx.ts, ui.ts HUD, effects and buttons
source/src/audio.ts music, sound effects and narration
source/src/i18n/ 14 interface dictionaries
source/public/theme/witch/ artwork (theme.json lists every image)
source/public/audio/ music, effects, voice packs en/pt/es
source/test/ regression tests
7 Languages
The game interface offers 14 languages, chosen in Settings. This offline buyer guide is in English, Brazilian Portuguese and Spanish; its dropdown detects the browser and remembers the selected guide language. Screenshots stay in English. Narration is recorded in English, Brazilian Portuguese and Spanish (public/audio/voice-jessica-v4, -pt, -es); the other 11 languages use the English voice, and any line missing from a language pack falls back to English. Edit the dictionaries without changing interpolation placeholders.
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.
bubble-spell.template.settings sound, language, vibration, effects, aim
bubble-spell.template.unlockedLevel progress on the saga map
bubble-spell.template.stars stars per level
bubble-spell.template.checkpoint.v1 the round in progress
bubble-spell.template.daily daily challenge streak
bubble-spell.template.bank boosters won from chests and dailies
bubble-spell.template.chests chests already opened
bubble-spell.template.collection kittens rescued per world
bubble-spell.template.endlessBest endless mode record
bubble-spell.template.tutorial tutorial seen
9 Development
The ready-to-host game needs no Node.js. The editable TypeScript source is optional and uses Vite 6.4.5 with Node.js 22.13 or newer. Follow the beginner steps below, then run the commands in source/. npm run build type-checks, builds and formats the readable output into dist/, which matches game/. No server, account, ranking, ads or payments are used.
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 22.13 or newer. 2) Close and reopen the terminal, then run node -v and npm -v to confirm both print a version. 3) Open the terminal inside the source/ folder (the one containing package.json). 4) Run npm ci to install the exact dependencies from package-lock.json. 5) Run npm test for the regression tests, then npm run build to type-check and write the game to dist/. 6) Test locally with npm run dev (http://localhost:5199/) or npm run preview, then upload the contents of dist/ like game/. Common errors: node or npm not found (reopen the terminal or fix PATH); on Windows PowerShell, npm.ps1 cannot be loaded (run npm.cmd ci or use Command Prompt); ENOENT package.json (you are not inside source/); EBADENGINE (Node.js is older than 22.13); network or proxy failures during install (check your connection and proxy); npm ci complaining about the lock file (do not edit package-lock.json; delete node_modules and retry).
cd source
npm ci
npm test
npm run build
npm run dev
# http://localhost:5199/
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
For support and customization contact willian@polargames.com.br. Include the product version, browser, device, hosting URL, reproduction steps and a screenshot. No backend, native app, ad SDK or real-money purchasing system is included.
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.