Customization Guide

Make Shoalmates your own game: new creatures, new backgrounds, your own logo, texts, music and sounds, and easier or harder levels. 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:

• A code text editor: Visual Studio Code (Windows, Mac, Linux) or Notepad++ (Windows). Do not use Word or WordPad: they break the files.
• An image editor that can export WebP with a transparent background: Photopea (in the browser), GIMP or Krita. You can also draw in any program, save as PNG and convert the PNG to WebP at squoosh.app.
• For music and sounds: Audacity (exports MP3).

Which folder to edit. The download has two copies of the game:

• game/ is the finished game. Simplest way: change files directly inside game/ and upload that folder. No other tools are needed.
• source/ is the same game with tests, a local server and a level generator. If you use it, edit source/ and run npm run build: it copies the game to source/dist/, and that folder is what you upload. Pick one way and keep to it.

The paths in this guide (for example assets/art/logo.webp) are the same inside both folders.

See your changes on your computer. The game must be opened from a web address, not by double-clicking index.html. Two easy ways:

• With Python (python.org): open a terminal in the game folder, run the command below and open http://localhost:8080.
• With Node.js: in source/, run npm run serve and open http://localhost:5195.

python -m http.server 8080

After each change, reload the page with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac) so the browser does not show the old file.

2. Where everything is

The numbers on each screenshot match the table below it. Texts are named by their key in src/locales.js (recipe E).

Title screen

1 2 3 4 5

Home screen (My Reef)

1 2 3 4 5 6 7

Journey map

1 2 3 4 5 6

A level

1 2 3 4 5 6 7 8

3. More screens of the game

Windows (pause, settings, win, lose) share the same pieces: the glass window is assets/art/glass-panel.webp, the title ribbons are ribbon-coral*.webp, ribbon-gold*.webp and ribbon-purple*.webp, the buttons are ui-btn-coral*.webp (red) and ui-btn-teal*.webp (green-blue).

4. Recipe A: replace a picture

All pictures are in assets/art/ in WebP format. The game finds each picture by its file name, so a new picture with the same name simply takes its place.

1. Find the file with the screens above or by its name: creature names (clown, puffer...), bg-* backgrounds, decor-* reef decorations, ui-btn-* buttons, ribbon-* and ui-ribbon-* ribbons, ui-plate* brown plates, glass-* glass pieces, ic-* icons.
2. Open the old picture in your image editor and note its width and height.
3. Make your new picture with the same width and height and a transparent background (except the bg-* backgrounds). Keep the drawing in the same position inside the picture.
4. Export as WebP with the exact same name, for example pearl.webp, and replace the old file.
5. Buttons, ribbons and plates come in four files: the whole piece and three slices that let it stretch, for example ui-btn-coral.webp, ui-btn-coral-l.webp (left end), ui-btn-coral-m.webp (middle) and ui-btn-coral-r.webp (right end). Replace all four, cutting your new picture at the same places.
6. Reload the game with Ctrl+F5.

5. Recipe B: change the logo and the game name

1. Logo: replace assets/art/logo.webp (recipe A). Keep the same width, height and transparent background.
2. Browser tab name: open index.html and change the text between <title> and </title>. On the line of the logo, a little below, change the name inside alt="SHOALMATES" too (screen readers read it).
3. Subtitle under the logo ("Bubble Fish Sort"): key tagline in src/locales.js (recipe E).
4. Tab icon: replace favicon.ico, next to index.html.

6. Recipe C: change the creatures

There are 12 creatures and the Golden Fish. Each one is a set of five pictures in assets/art/: the picture alone and four faces (-x0 normal, -blink eyes closed, -happy, -worry). Replace the whole set, drawing the same creature with the four faces, in the same size and position.

• The Golden Fish uses gold.webp and gold-x0, gold-blink, gold-happy, gold-worry.
• The pufferfish is also the mascot: puffer-front.webp (map), puffer-peek.webp (settings) and puffer-sad.webp (level lost).
• Names: the list NAMES near the top of src/locales.js, in the order of the table. Change only the words inside the quotes.
• Album sentences: keys f_0 to f_11 (same order) in each language.
• Spoken names: the album says the name with assets/voice/en/name_0.mp3 to name_11.mp3 (also in pt/ and es/). If you rename a creature, record the new name over the file with the same number.

7. Recipe D: change the backgrounds and the worlds

1. Backgrounds are in assets/art/: bg-home.webp (title and home) and one per world, in this order: bg-coral.webp (levels 1 to 10), bg-kelp.webp (11 to 20), bg-ship.webp (21 to 30), bg-glow.webp (31 to 40), bg-ice.webp (41 to 50), bg-deep.webp (51 to 60).
2. Replace a file with a picture of the same width and height (recipe A). Keep the middle calm, without strong details: the bubbles are drawn there. The sides are shown blurred on wide screens.
3. World names: keys w_coral, w_kelp, w_ship, w_glow, w_ice, w_deep in src/locales.js (recipe E). The file names stay the same even if your world has another theme; players never see them.

8. Recipe E: change texts and translations

All texts players read are in two files: src/locales.js (English, Portuguese, Spanish) and src/locales-more.js (French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean, Chinese). Each language is a block of lines like these:

  tapToStart: 'Tap to start',
  play: 'Play',
  levelN: 'Level {n}',
  soClose: 'So close!',

1. Find the text you want to change (Ctrl+F in your editor). The word before the colon is the key; never change it.
2. Change only the words inside the quotes. If your text has an apostrophe, like Let's, put double quotes around the text: "Let's go!".
3. Keep markers such as {n}: the game puts a number there.
4. Change the same key in the other languages you use.
5. If you use source/, run npm test: it checks that the 14 languages still have every key and every marker.

The sentences of the guided first levels are the keys g1a, g1b, g1c, g2a, g2b, g2c, and the one-sentence cards of new pieces start with l_. The guided sentences are also spoken: see recipe H.

9. Recipe F: make the levels easier or harder

The 60 levels are not drawn by hand: src/levels.js has the numbers of each level and the game builds the bubbles from them. The first world (levels 1 to 10) is three plain lists, one number per level:

const W1 = {
  fish: [12, 18, 24, 30, 36, 42, 48, 54, 60, 72],
  sp: [2, 3, 4, 4, 5, 5, 6, 6, 6, 7],
  slots: [4, 5, 6, 6, 7, 7, 8, 8, 8, 8],
};

• Levels 11 to 60 use the formulas a few lines below, inside params(n): w is the world (2 to 6) and k the position in the world (0 to 9). To make all of them easier, lower the first number of the fish line (60) or the numbers of the hard line.
• The tray has 5 spots: TRAY at the top of src/sim/sim.js. A bigger tray makes every level much easier.
• After changing level numbers, open a terminal in source/ and run the two commands below. The first one finds a new solvable layout for each level and rewrites src/level-seeds.js; the second plays the 60 levels with a simulated player and fails if a level cannot be won.

npm run levels
npm test

These two commands need Node.js; the main buyer guide explains how to install it, step by step.

10. Recipe G: change pearls and helper prices

• Helper prices, in pearls: COST at the top of src/sim/sim.js. chance is the price of the second chance on the lose window.

export const COST = { scoop: 3, sweep: 3, whirl: 2, chance: 5 };

• Pearls a new player starts with: START_PEARLS in src/config.js (6).
• Level that unlocks each helper: HELPER_AT in src/config.js (Scoop at level 3, Sweep at 5, Whirl at 7).

Change only the numbers. Keep the commas, braces and names exactly where they are. Pearls are earned by playing; the game has no store and no real-money purchases.

11. Recipe H: replace music, sounds and voice

Save your audio as MP3 with the same file name and replace the old file.

• Music (assets/music/): reef.mp3 plays on the menus, play-a.mp3 in levels 1 to 30 and play-b.mp3 in levels 31 to 60. Each track repeats; a track that ends softly loops best.

• If a new sound is too loud or too quiet, change its number in GAIN at the top of src/audio/sound.js (1 is full volume, 0.5 is half).
• The short sounds of play (tap, tray, pop, buttons, the rising notes of a full bubble) are not files: the game makes them with the numbers in SYNTH, in the same file. f is the pitch in Hz, dur the length in seconds, g the volume.
• Voice (assets/voice/en/, pt/, es/): intro.mp3 (welcome), g1a to g2c (the guided first levels) and name_0 to name_11 (creature names). If you change one of those texts, record the new sentence over the file with the same name.
• To remove the voice, delete the files or the whole assets/voice/ folder: the game keeps working and shows only the written captions. The same is true for the music and the recorded sounds.
• Players set the Music, Effects and Voice volumes in Settings; the starting values are VOL in src/config.js. On phones, sound starts after the first touch (a browser rule).

12. Recipe I: change the reef decorations

The home screen has 6 decoration spots. Open src/config.js and find PEDESTALS, one line per spot:

{ at: 5, x: 0.15, y: 0.62, opts: ['lighthouse', 'castle', 'tiki'] },

• at: the level that opens the spot (5, 10, 20, 30, 40, 50).
• opts: the three decorations the player can choose there. Each name is a picture assets/art/decor-<name>.webp: amphora, anchor, arch, boat, castle, chest, helmet, lighthouse, tiki.
• x and y: where the spot is on the reef, from 0 (left, top) to 1 (right, bottom).
• To change a decoration, replace its picture (recipe A). To add one, save decor-yourname.webp and write 'yourname' in an opts list.

13. Recipe J: change colors, buttons and the font

• Main colors: the block :root near the top of style-1-base.css: --ink (dark brown text), --coral and --coral-d (red), --teal and --teal-d (green-blue), --gold and --gold-d, --cream. Change the value after the colon, for example --gold: #ffc64d;.
• Browser bar color on phones: the line theme-color in index.html.
• Buttons, ribbons and plates are pictures: recolor them in your image editor (Hue/Saturation) and save with the same names (recipe A, step 5).
• Font: Fredoka, in assets/fonts/, declared by the four @font-face blocks at the top of style-1-base.css. To use another font, add its .woff2 files to assets/fonts/ and change the file names in those blocks. Check that its license allows use in games.

14. Check and publish your changes

1. Play the parts you changed on your computer (see Before you start), in a wide window and in a narrow one (F12, then Ctrl+Shift+M shows phone sizes).
2. If you edited source/: in a terminal inside source/, run the commands below. The first checks the rules, the levels and the texts; the second copies the game to source/dist/.

npm test
npm run build

3. Upload everything inside game/ (or source/dist/, if you built it) to your web hosting, replacing the old files.
4. Open your game address and press Ctrl+F5. If you still see the old version, read the section about updates and cache in the main buyer guide.

15. If something goes wrong

• The game stops on the first screen after you edit a .js file: a comma, quote or brace is missing. Press F12 and open the Console: it shows the file name and the line with the error. Compare that line with your backup.
• A picture is missing: the file name is different (names are case sensitive: Logo.webp is not logo.webp), or the file is not WebP.
• Nothing changed: the browser is showing the old file. Press Ctrl+F5, or open the game in a private window.
• Still stuck? Restore your backup and change one thing at a time. Support: willian@polargames.com.br (include the game version, what you changed and a screenshot).