Bubble Words · Customization Guide · version 1.0.0 · Main buyer guide

Customization Guide

Make Bubble Words your own game: your own words and themes (for example for a school subject), levels and worlds, difficulty and powers, pictures, logo, texts, colors and sounds. Every recipe below is a short list of steps and says exactly which file to open. You do not need to know how to program. All pictures on this page are real screenshots of the game in this package.

1. Before you start

Free tools you need:

Make a backup first. Copy the whole game/ folder (or source/) to a safe place before you change anything. If something breaks, put the backup back.

Which folder do I edit? The simplest way: edit the files inside game/ and upload that folder. If you use the developer tools, edit source/ instead and run npm run build, which copies everything to source/dist/ (the same as game/). Both folders have the same file names, so every recipe below works in either one. The tests are only in source/.

Test panel: on your own computer, add ?debug to the address (http://localhost:5196/?debug) to get buttons that win or lose a level, unlock every level and show the end screen; ?debug&fase=37 opens level 37. On a public address the panel never appears.

2. Where everything is

Each number on the screenshot matches a line of the table next to it, with the exact file to change. Interface texts are in src/i18n.js (English, Portuguese and Spanish); the table gives the key of each text. Pictures are in assets/ui/ and the world backgrounds in assets/art/.

Title screen

Title screen, real screenshot with numbered parts 1 2 3 4
# What you see File to change
1 Tap to start Text: key start in src/i18n.js. Green color: .btn.green in ui.css (recipe F).
2 Daily challenge Text: key daily in src/i18n.js. The level is built by makeDaily in src/levels.js.
3 Album Text: key album in src/i18n.js. Blue color: .btn.blue in ui-arte2.css.
4 Settings Icon: assets/ui/ico-config.webp. The window is #s-pause in index.html.

Levels

Levels, real screenshot with numbered parts 1 2 3 4 5 6
# What you see File to change
1 World and its name Names: list worlds in src/i18n.js (one per language). Background: assets/art/mundo-N-retrato.webp / mundo-N-paisagem.webp (recipe B).
2 Current level Golden ring: .lv.current in ui-arte2.css.
3 Finished level and its stars Stars: assets/ui/estrela-ouro.webp and estrela-vazia.webp. Star rule: win() in src/main.js (recipe C).
4 Next world Arrows: #world-prev / #world-next. The lock message is key worldLock in src/i18n.js.
5 Play the current level Text: key playLevel in src/i18n.js.
6 Back Text: key back in src/i18n.js.

A level

A level, real screenshot with numbered parts 1 2 3 4 5 6
# What you see File to change
1 Pause Icon: assets/ui/ico-pausa.webp.
2 Level number Text: key level in src/i18n.js.
3 Breaths How many: breaths in FEEL, src/config.js (recipe C).
4 Theme bottle Pictures: assets/ui/garrafa-N.webp (N = 0 to 5). Soap colors: THEME_COLORS in src/config.js.
5 Powers Icons: assets/ui/ico-lupa.webp, ico-letra.webp, ico-ima.webp, ico-sopro.webp. Levels where they open: POWERS in src/main.js.
6 Hint bar Shows the theme name; tutorial texts are keys tut1, tutGo, tutBridge... in src/i18n.js.
A level of the Beach world, real screenshot
On a wide screen the bottles stand on shelves on the left and the powers sit on the right. World 3 background: mundo-3-paisagem.webp.
A level with ice bubbles, real screenshot
From world 5 some bubbles are frozen: they melt when bubbles are joined next to them. How many per level: ice in recipe(i), src/levels.js.
A level with an ink bubble, real screenshot
From world 7 ink bubbles hide their word (a question mark) until another bubble touches them: ink in recipe(i).
The magnifier power, real screenshot
The Magnifier marks two bubbles of the same theme with a golden ring. Explanation text: key pw_lupa.
The win window, real screenshot
Win window: stars, time, mistakes, best streak, the bottles of the themes found, Levels and Next.
The album, real screenshot
Album: every theme of src/words/. Found themes show their bottle; tap one to see its words.

4. Recipe A: change the words and themes

Every theme lives in the word file of each language: src/words/en.js (English), src/words/pt.js (Portuguese) and src/words/es.js (Spanish). A theme looks like this:

  frutas: {
    name: 'FRUITS',
    f: 'fruta',
    words: ['BANANA', 'GRAPE', 'KIWI', 'APPLE', 'PEAR', 'WATERMELON', 'STRAWBERRY'],
  },

Steps to change words:

  1. Open src/words/en.js and find the theme (search for its name, for example 'FRUITS').
  2. Replace a word between the quotes, for example 'KIWI' by 'PLUM'. Keep the quotes and the commas.
  3. Do the same in pt.js and es.js if you want the change in those languages (the words there do not need to be translations).
  4. Run npm test in source/. If a word is now in two themes, or a theme has fewer than 6 words, the message says which one.

To add a new theme, copy a whole block (from the id to the closing },), give it a new id, name, family and 7 words, and add it with the same id and family to the three files. The levels pick themes by themselves; npm test checks that every theme appears somewhere in the 100 levels.

Bridge words are words that fit two themes (for example ORANGE, a fruit and a color). They are in the list BRIDGES at the end of each word file: { word: 'ORANGE', own: 'frutas2', alt: 'cores' } means ORANGE is a word of frutas2 that also fits cores. If you add a word that could belong to another theme of the file, add it to BRIDGES too, so the game counts it right.

5. Recipe B: levels, worlds, their names and backgrounds

The levels are built from a recipe, not typed one by one. recipe(i) in src/levels.js says, for level i (0 to 99), how many themes it has, how many words each theme brings, and how many bridge words, ice bubbles and ink bubbles appear. Each world uses one row of the lists inside it, so you can make a world easier or harder by changing its numbers.

World names are the list worlds in src/i18n.js, once per language (for example 'Porch', 'Garden', 'Beach'...). The end screen says how many worlds there are with the key endText: change it if you change WORLDS.

World backgrounds are two pictures per world in assets/art/: mundo-N-retrato.webp for phones held upright (1080 x 1919 pixels) and mundo-N-paisagem.webp for wide screens (1920 x 1081 pixels), where N is the world number (1 to 10). Keep the middle of the picture calm and colorful: the bubbles float there. If you add worlds, add their two pictures with the next numbers.

6. Recipe C: difficulty, breaths, stars and powers

7. Recipe D: replace pictures (logo, bottles, icons, trophy)

Make the new picture the same size (or the same proportions) as the old one, save it as WebP with a transparent background, and give it exactly the same name. Then reload the page.

Picture File in assets/ui/
Game logo (title screen) logo.webp
Theme bottles, empty and full (6 colors) garrafa-0.webp to garrafa-5.webp, garrafa-cheia-0.webp to garrafa-cheia-5.webp
Powers, pause and settings icons ico-lupa.webp, ico-letra.webp, ico-ima.webp, ico-sopro.webp, ico-pausa.webp, ico-config.webp
Stars (full and empty) estrela-ouro.webp, estrela-vazia.webp
Trophy of the end screen trofeu.webp
Window frame (bubble panel) painel-bolha.webp
Title ribbon faixa.webp
Cracked bubble of the lose window bolha-rachada.webp
Shelves on wide screens prateleira.webp
Browser tab icon favicon.png (64 x 64)

The bubbles themselves are drawn by code (src/bubbles.js), not pictures, so they always stay sharp.

8. Recipe E: change texts, the game name and translations

  1. Open src/i18n.js. It has three blocks: pt, en and es.
  2. Find the key of the text (the tables of section 2 give it), for example start: 'Tap to start', and change only the words between the quotes.
  3. Change the same key in the other two blocks if you want.

The game name appears in the browser tab: <title>Bubble Words</title> in index.html. On the title screen the name is the logo picture (recipe D). The three words that float on the title screen are titleWords in src/i18n.js.

The game opens in the language of the browser (English when it is not one of the three) and the player can change it in the settings of the title screen. The main guide explains how to add a fourth language.

9. Recipe F: change colors and the font

The four style files are loaded in this order: style.css, ui.css, ui-contraste.css, ui-arte2.css. When the same thing is set twice, the later file wins, so search the four files before you change a color.

10. Recipe G: replace the music and sounds

11. Check and publish your changes

  1. If you edited source/: run npm test, then npm run build, and use source/dist/.
  2. Play a few levels in the browser on your computer (the ?debug panel helps).
  3. Upload the contents of the folder (game/ or dist/) to your web host, keeping the folders. Then clear the browser cache (see the main guide) to see the new version.

12. If something goes wrong