Bubble Words

1 Overview

Bubble Words is an HTML5 word game for kids. Words float on the screen inside soap bubbles. The player drags a bubble onto another bubble of the same theme (fruits, animals, colors, toys...) and the two join into a bigger bubble. When every word of a theme is together, its soap bottle at the bottom fills up and the name of the theme appears.

A level is won when every theme is complete. A wrong match costs one of the 5 breaths; with no breaths left the level is lost. A level without mistakes gives 3 stars and a helper power. There are 100 levels in 10 worlds with their own backgrounds; later worlds add bridge words that fit two themes, ice bubbles and ink bubbles. A daily challenge, an album with the 73 themes and an end screen after level 100 complete the game.

The game runs in any modern browser on phones, tablets and computers, in portrait and in landscape, with touch or mouse. It has 3 languages (English, Portuguese and Spanish, each with its own word lists), music, recorded sound effects and vibration on phones. There is no store, no account and no server: it is a set of static files.

2 Quick installation by FTP

Installing takes a few minutes if you have FTP access or a file manager in your hosting panel.

1. 1. Extract bubble-words-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/bubble-words/.
3. 3. Upload only the contents of the game/ folder, so that index.html sits directly inside the target folder.
4. 4. Keep assets/, src/ and the four style files (style.css, ui.css, ui-contraste.css, ui-arte2.css) beside index.html, with names and letter case exactly as extracted.
5. 5. Open https://your-domain.example/games/bubble-words/ in a modern browser.

3 Requirements and sound

• Any static web hosting with HTTPS (or HTTP). Opening index.html directly from the disk (file://) is not supported, because browsers block JavaScript modules there.
• A current browser: Chrome, Edge, Firefox or Safari, on desktop or mobile. Bubbles are dragged with a finger or the mouse.
• Browsers start sound only after a user gesture, so the music begins after the first tap or click.
• When the page is hidden (another tab, phone locked), the sound pauses and comes back when the player returns. Vibration works only on phones and tablets that support it.

4 Controls and how the game works

Drag a bubble with a finger or the mouse and drop it on another bubble of the same theme: they join and the group grows. A bubble that does not match bounces back with a short shake and costs one breath (the very first time a bridge word is tried, the game only explains it).

Each theme has a soap bottle at the bottom. Its dots show how many words are already together, the soap rises and the letters of the theme name appear one by one. Tapping a bottle shows its name in big letters in the hint bar. When the last word joins, the bottle is full and the theme is complete.

Bridge words fit two themes: count the dots of the bottles to decide where they go. Ice bubbles cannot be moved until bubbles are joined next to them. Ink bubbles hide their word until another bubble touches them.

Four powers sit on the right side: Magnifier (shows two bubbles of the same theme), Letter (reveals a letter of a theme name), Magnet (joins two bubbles of the same theme for you) and Extra breath (gives back a lost breath). They open at levels 5, 12, 25 and 8, and a level won without mistakes gives one more.

Stars: no mistakes gives 3 stars, one or two mistakes give 2, more give 1. Every 10 levels a new world opens with a party. The daily challenge on the title screen is a new level every day, and the album collects every theme found.

5 Screens and controls explained

1 2 3 4

Marks on the screenshot

1. 1 Open the levels
2. 2 Daily challenge
3. 3 Album of themes
4. 4 Settings

1 2 3 4 5 6

Marks on the screenshot

1. 1 World and its name
2. 2 Current level
3. 3 Finished level with its stars
4. 4 Next world (a locked world says so below the window)
5. 5 Play the current level
6. 6 Back to the title

1 2 3 4 5 6

Marks on the screenshot

1. 1 Pause and settings
2. 2 Level number
3. 3 Breaths: a wrong match costs one
4. 4 Theme bottle: dots, soap and letters fill up
5. 5 Powers
6. 6 Hint bar with the theme name

1 2 3 4 5

Marks on the screenshot

1. 1 Stars
2. 2 Time, mistakes and best streak
3. 3 Themes found in this level
4. 4 Next level
5. 5 Levels

1 2

Marks on the screenshot

1. 1 Themes that were missing
2. 2 Try again

1 2 3 4 5

Marks on the screenshot

1. 1 Back to the game
2. 2 Music volume
3. 3 Effects volume
4. 4 Vibration
5. 5 Less motion

1 2 3

Marks on the screenshot

1. 1 Themes found out of all
2. 2 A found theme (tap to see its words)
3. 3 A theme not found yet

1 2 3 4

Marks on the screenshot

1. 1 Total of stars
2. 2 Themes found
3. 3 Album of themes
4. 4 Levels

6 Map of the files

game/ is the ready-to-host game. source/ has the same editable files plus the tests, a local preview server and the build command. Both are plain HTML, CSS and JavaScript modules: there is nothing to compile.

game/                        upload these contents to your web host
  index.html                 every screen: title, levels, album, settings, win, lose, end, and the game HUD
  style.css, ui.css, ui-contraste.css, ui-arte2.css   the styles (loaded in this order)
  src/main.js                screens, rules of a level, bottles, powers, stars, daily challenge, album, saving
  src/bubbles.js             the bubbles: jelly physics, drawing, particles, drag and drop
  src/levels.js              the 100 levels, the 10 worlds and the daily challenge
  src/words/en.js, pt.js, es.js   the themes and their words in each language
  src/i18n.js                interface texts: English, Portuguese, Spanish
  src/config.js              feel numbers (speeds, springs, timings, breaths)
  src/audio.js               sound effects, music and vibration
  src/nine.js                stretched panel pictures without seams
  assets/art/                one background per world (portrait and landscape)
  assets/ui/                 logo, panel, bottles, stars, trophy, icons
  assets/sfx/, assets/music/ sound effects and music (MP3)
  assets/fonts/              Fredoka font and its license
  DOCUMENTATION.txt          short note that points to this guide
source/                      the same editable files, plus:
  package.json               npm test, npm run build, npm run serve
  package-lock.json
  README.md
  test/                      node --test tests (words, levels, save key, texts)
  tools/build.mjs            copies the game into dist/
  tools/serve.mjs            local preview server
documentation/index.html     this guide (offline, 3 languages)
documentation/customization.html   step-by-step customization guide
documentation/img/           the screenshots of both guides
DOCUMENTATION.html           shortcut to this guide
CUSTOMIZATION.html           shortcut to the customization guide
START-HERE.txt, CHANGELOG.txt
THIRD-PARTY-LICENSES/        font license

• src/levels.js: recipe(i) says how many themes, words per theme, bridge words, ice and ink bubbles each of the 100 levels has. WORLDS and PER_WORLD set the number of worlds and levels per world. makeDaily builds the daily challenge.
• src/words/en.js, pt.js and es.js: the themes (THEMES: name, family and 7 words each) and the bridge words (BRIDGES). The three files use the same theme ids.
• src/main.js: screens, rules of a level, bottles, powers (POWERS: the level where each one opens), stars, daily challenge, album, settings and saving. src/bubbles.js: the bubbles, their physics and drawing.
• src/i18n.js: every interface text in the three languages. src/config.js: feel numbers in one place (FEEL: breaths, speeds, springs, timings). src/audio.js: sound effects, music and vibration.
• assets/art/: the backgrounds of the 10 worlds, mundo-N-retrato.webp (portrait) and mundo-N-paisagem.webp (landscape). assets/ui/: logo, panel, bottles, stars, trophy and icons. assets/sfx/ and assets/music/: sounds in MP3.
• The code and its comments are in Portuguese. Common names: fase level, mundo world, tema theme, frasco or garrafa bottle, sopros breaths, ponte bridge word, gelo ice, tinta ink, lupa, letra, ima, sopro the four powers. source/README.md has the full table.

7 Customizing words, levels, art and sounds

Customization Guide (step by step, in English)

Words and themes: each language has its own file, src/words/en.js, src/words/pt.js and src/words/es.js. Each theme has a name, a family and 7 words of up to 12 letters; a word may belong to one theme only. Then run npm test: it checks every language and every level.

Levels and worlds: recipe(i) in src/levels.js sets the number of themes and words of each level; change WORLDS and PER_WORLD for more or fewer levels. World names are the worlds list in src/i18n.js, and each world needs its two backgrounds in assets/art/.

Difficulty: breaths in FEEL (src/config.js) is the number of breaths per level, and POWERS in src/main.js is the level where each power opens. Star rules are in win() in src/main.js.

Look: the logo is assets/ui/logo.webp, the trophy assets/ui/trofeu.webp, the bottles garrafa-N.webp and garrafa-cheia-N.webp, the power icons ico-*.webp. Replace a picture with another of the same size and format. Colors and sizes of buttons and panels are in the four style files.

Music and sound effects

Music: assets/music/menu.mp3 plays on the title and levels screens; jogo.mp3 and jogo-cheia.mp3 play together during a level (the second one rises with a streak), all in a loop. To change a track, replace the file with another MP3 of the same name.

Effects are MP3 files in assets/sfx/ (pop, match, win, star...). Replace a file to change a sound; if a file is missing the game plays a synthesized sound instead. The player sets the music and effects volumes in the settings.

8 Languages

The game has 3 languages: English, Português (Brasil) and Español. Each language has its own word lists, so the words are not literal translations. On the first visit the game follows the browser language (English when it is not one of the three); the player can change it in the settings of the title screen.

The interface texts are in src/i18n.js, the words in src/words/<lang>.js.

To add a language, copy one block of src/i18n.js and one file of src/words/, translate them keeping the same keys and theme ids, add the code to LANGS in src/i18n.js and a button to the language row in index.html, then run npm test.

9 Local saves

• Progress (levels reached, stars, powers, daily challenges, album) and the settings (volumes, vibration, language) are saved in the browser localStorage of each device.
• There are no accounts or cloud saves. Clearing site data resets the progress on that device.
• The key is shown below. It is KEY near the top of src/main.js.

bubble-words.template.save.v1

10 Optional development

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 dist/.

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.1). 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 or use your distribution's Node.js 26 package.

2. Check the installation. Run node --version and npm --version separately. Both must print a version number, and Node.js must be 26.13.1 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.

4. Run the commands below one by one. npm ci checks the lock file (nothing is downloaded, the project has no dependencies). npm test checks the words and the 100 levels in the three languages, the save key and the interface texts.

npm ci
npm test

5. Preview: npm run serve starts a local server; open http://localhost:5196/ in your browser, play a level, and stop the server with Ctrl+C.

npm run serve

6. Build: npm run build empties source/dist/ and copies index.html, the four style files, src/ and assets/ into it. dist/ is what you publish; while the source is unchanged it matches game/ file by file.

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 afterwards (see Updating and cache).

Test panel (local addresses only)

The test tools below work only when the page address is localhost, 127.x or a private network address (10.x, 192.168.x). On any public address they are ignored, so players never see them.

• ?debug shows a small panel in the corner: win with 3 stars or 1 star, lose, end screen, unlock all levels, reset the progress and go to a level.
• ?debug&fase=12 opens level 12 directly.
• With ?debug the running game is also available as window.__bw for automated tests in the browser console.

http://localhost:5196/?debug&fase=12

11 Updating and 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.

12 Licenses

The game code, the words, the levels and the artwork are supplied under the license of the item you purchased. The music and sound effects used by the game are included in the package and can be replaced (see the customizing section).

The Fredoka font is used under the SIL Open Font License 1.1; its complete license text is in THIRD-PARTY-LICENSES/ and in game/assets/fonts/LICENSE-Fredoka-OFL.txt. The game has no third-party code and no npm dependencies.

13 Troubleshooting

• Blank page: the game was opened from the disk or a file is missing. Use a web host and keep assets/, src/ and the four style files next to index.html.
• npm test fails after you edited the words: read the message; it names the word, the theme or the level that broke a rule (for example a word in two themes or a theme with fewer than 6 words).
• No sound: tap the screen once; check that the device is not silent and that the volumes in the settings are up.
• Old version after an update: clear the browser cache (see below).
• ?debug does nothing on your website: the test panel only works on local addresses (see the development section).

14 Frequently asked questions

15 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.