Shoalmates

1 Overview

Shoalmates is an HTML5 sorting puzzle game. Sea creatures wait inside bubbles; the player taps one and it swims to the top bubble that shows its kind. Three of a kind fill a top bubble and a new one arrives. A creature with no top bubble waits in the tray, which has only 5 spots. The game has 60 levels in 6 worlds (Coral Garden, Kelp Forest, Sunken Ship, Glow Cave, Ice Bay and Deep Blue) and 12 creatures to collect.

Around the levels there is a daily level made from the date, an album with a card for each of the 12 creatures, a reef on the home screen with 6 spots to decorate, 3 helpers paid with pearls, a guided tutorial with a pointing hand on levels 1 and 2, and narration in English, Portuguese and Spanish. The interface has 14 languages.

The game runs in any modern browser on phones, tablets and computers. It is drawn as a portrait column; on a wide screen the column stays in the middle and the sides show the same background, blurred. It uses plain HTML, CSS and JavaScript modules: no framework, no build step to play, no server code, no ads, no store, no ranking and no accounts.

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 shoalmates-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/shoalmates/.
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/, favicon.ico and the three style-*.css files beside index.html, with names and letter case exactly as extracted.
5. 5. Open https://your-domain.example/games/shoalmates/ 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 that way.
• A current browser: Chrome, Edge, Firefox or Safari, on desktop or mobile.
• Browsers start sound only after a user gesture. The game opens on a tap-to-start screen and only then plays music, effects and voice lines.
• When the page is hidden, the sound fades out over 30 seconds and everything pauses after 60 seconds; it comes back when the player returns.

4 Controls and how the game works

Tap or click a creature inside a bubble. If a top bubble shows its kind, it swims there; 3 of a kind fill the top bubble, which leaves and makes room for the next one. If no top bubble fits, the creature waits in the tray and leaves by itself when its bubble arrives. The level is lost when the 5 tray spots are full and nothing fits; a second chance (5 pearls, once per level) empties the tray and adds a spot. Holding a creature calls every creature of the same kind in that bubble at once. Undo takes back the last tap if it went to the tray.

Stars depend on how full the tray got: 3 stars if it never held more than 3 creatures, 2 stars with 4, and 1 star with 5 or after a second chance. Pearls are the only currency. The player starts with 6 and earns the stars of each win, plus 2 for a pearl oyster emptied in time, 1 for a family trio (three creatures from the same bubble), 1 for each Golden Fish and 5 for the daily level. Helpers cost pearls: Scoop (3) fills the fullest top bubble, Sweep (3) clears the tray and the creatures come back when their bubble opens, and Whirl (2) groups the creatures by kind. They unlock on levels 3, 5 and 7, and the first use of each one is free.

New pieces are introduced one at a time with a one-sentence card: kelp wrap (level 4), calling the shoal (6), clam lock and key (7), free top bubble (8), Golden Fish (9) and pearl oyster (11). Levels 1 and 2 are guided: a hand points at the creature to tap and a caption at the bottom explains the goal and the tray. Every level has a solution that needs no helper and gives 3 stars; npm test proves it by playing all 60 levels.

Settings (the gear) has volume sliders for music, effects and voice, vibration, reduced motion and the language list. During a level the same panel also offers Resume, Restart and Home.

5 Screens and controls explained

1

Marks on the screenshot

1. 1 Tap to start

1 2 3 4 5

Marks on the screenshot

1. 1 Play
2. 2 Pearls
3. 3 Settings
4. 4 Reef and decorations
5. 5 Album, Journey and Daily

1 2 3 4

Marks on the screenshot

1. 1 Current level
2. 2 World name
3. 3 Stars earned
4. 4 Back

1 2 3 4 5 6 7

Marks on the screenshot

1. 1 Level number
2. 2 Pearls
3. 3 Pause
4. 4 Top bubbles
5. 5 Bubbles with creatures
6. 6 Tray
7. 7 Helpers

1 2

Marks on the screenshot

1. 1 Guiding hand
2. 2 Tutorial caption

1 2 3

Marks on the screenshot

1. 1 Stars
2. 2 Pearls earned
3. 3 Next

1 2 3

Marks on the screenshot

1. 1 Creature found
2. 2 Not found yet
3. 3 Creatures found

1 2 3

Marks on the screenshot

1. 1 Volume sliders
2. 2 Vibration and reduced motion
3. 3 Language

1 2

Marks on the screenshot

1. 1 Today
2. 2 Play today

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, the level generator and the build command. Code comments are in Portuguese.

game/                        upload these contents to your web host
  index.html                 entry page
  favicon.ico                browser tab icon
  style-1-base.css           styles, loaded in this order
  style-2-glass-panels.css
  style-3-polish.css
  src/main.js                start-up, resize, frame loop, test shortcuts
  src/ui.js                  screens and panels (DOM)
  src/game.js                one match: touch -> rules -> drawing -> sound
  src/sim/                   rules, simulated players, level builder
  src/levels.js              the 60-level curve and the daily level
  src/level-seeds.js         one seed per level (written by npm run levels)
  src/render/                canvas drawing, art loading, effects
  src/reef.js                home reef and decorations
  src/audio/sound.js         music, sound effects, narration
  src/locales.js             texts: English, Portuguese, Spanish
  src/locales-more.js        texts: the other 11 languages
  src/config.js              feel numbers, volumes, decorations, save key
  src/save.js, storage.js, i18n.js, viewport.js, fullscreen.js
  assets/art/                images (WebP)
  assets/fonts/              Fredoka font and its license
  assets/music/              reef.mp3, play-a.mp3, play-b.mp3
  assets/sfx/                11 recorded effects (MP3)
  assets/voice/en|pt|es/     narration, 19 files per language (MP3)
  DOCUMENTATION.txt          short note that points to this guide
source/                      the same editable files, plus:
  package.json               npm test, npm run build, serve, levels
  package-lock.json
  README.md, LEVELS.md
  test/                      node --test tests
  tools/build.mjs            copies the game into dist/
  tools/serve.mjs            local preview server
  tools/gen-levels.mjs       level generator
documentation/index.html     this guide (offline, 14 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/config.js: game feel numbers in one place (FEEL: flight time, springs, shake, particles, hint delay, vibration), default volumes, decorations, lesson cards and the save key.
• src/locales.js and src/locales-more.js: every interface text in the 14 languages; src/i18n.js picks the language.
• src/sim/: the rules with no drawing (sim.js), the simulated players (bots.js) and the level builder (levelgen.js). src/levels.js holds the curve of the 60 levels and src/level-seeds.js holds one seed per level.
• src/game.js runs a match, src/render/ draws it on the canvas (view.js, art.js, fx.js), src/reef.js draws the home reef, src/ui.js builds the screens and panels, and src/main.js starts everything.
• style-1-base.css, style-2-glass-panels.css and style-3-polish.css: the styles, loaded in this order. A rule in a later file overrides the same rule in an earlier one, so edit the last file that sets it.
• assets/: images (art/, WebP), the font (fonts/), music (music/), sound effects (sfx/) and narration (voice/en, voice/pt, voice/es), all MP3.

7 Customizing texts, images and sounds

Customization Guide (step by step, in English)

Texts: open src/locales.js (English, Portuguese and Spanish) or src/locales-more.js (the other 11 languages) and change the text after each key. Keep the keys and placeholders such as {n} unchanged; npm test checks that all 14 languages still have the same keys. The names of the 12 creatures are in NAMES, in src/locales.js.

Images: replace a file in assets/art/ with another WebP of the same name and similar proportions. Each creature has five files, for example clown.webp, clown-x0.webp, clown-blink.webp, clown-happy.webp and clown-worry.webp. Backgrounds are bg-home.webp and one per world (bg-coral.webp, bg-kelp.webp, bg-ship.webp, bg-glow.webp, bg-ice.webp, bg-deep.webp); decorations are decor-*.webp; the logo is logo.webp and the browser tab icon is favicon.ico.

Levels: params(n) in src/levels.js sets how many creatures, kinds, bubbles and obstacles level n has. After changing it, run npm run levels to choose new seeds (it rewrites src/level-seeds.js and LEVELS.md) and npm test to confirm that every level can still be won. Helper prices are COST in src/sim/sim.js; the starting pearls, the levels that unlock helpers, the lesson cards and the decorations are in src/config.js.

Colors and sizes of the interface are in the three style-*.css files, measured in --u (1% of the width of the game column). The game title is in index.html and in assets/art/logo.webp; the line under the logo is the tagline text.

Music, sound effects and narration

Music: assets/music/reef.mp3 plays on the menus, play-a.mp3 in worlds 1 to 3 and play-b.mp3 in worlds 4 to 6. To change a track, replace the MP3 keeping the name. The game starts the next loop a few seconds before the end of the file, so that it blends with the fade-out; set those seconds per track in MUSIC_TAIL, in src/audio/sound.js. To remove the music, delete the files in assets/music/: the game notices the missing file once and stays silent. To avoid that request altogether, pass an empty name to the two startMusic(...) calls, in src/main.js and src/ui.js.

Sound effects: the short sounds of play (tap, tray, pop, buttons, the rising notes) are synthesized by the SYNTH table in src/audio/sound.js, so they have no file. The 11 recorded effects are the MP3 files in assets/sfx/ (win, fail, star, unlock, gold, scoop, sweep, whirl, oyster, chance, pearl), with their levels in the GAIN table. Replace a file keeping the name, or delete it and remove its entry from GAIN to silence that effect.

Narration: assets/voice/en/, assets/voice/pt/ and assets/voice/es/ each hold 19 MP3 files: intro (the welcome on level 1), g1a, g1b, g1c, g2a, g2b, g2c (the tutorial captions) and name_0 to name_11 (the album cards, in the order of NAMES). The other 11 languages show only the caption. To re-record a line, replace the file. To add narration for a language, record the 19 files in assets/voice/<code>/ and add the code to VOICE_LANGS in src/audio/sound.js. To remove narration, empty VOICE_LANGS (or remove one code) and delete the folders; the speaker button of the album card disappears by itself.

Players control the three volumes in Settings; the starting values are VOL in src/config.js. If you change the tutorial captions or the creature names, re-record or remove the matching narration files, because the voice says the original sentences.

8 Languages

The game has 14 languages: English, Português (Brasil), Español, Français, Deutsch, Italiano, Nederlands, Polski, Türkçe, Русский, Bahasa Indonesia, 日本語, 한국어 and 简体中文. It follows the browser language on the first visit and the player can change it in Settings. Narration exists in English, Portuguese and Spanish. English, Portuguese and Spanish are the reference texts; the other 11 languages were not reviewed by native speakers, so a native review is recommended before a launch in those markets. The bundled font covers Latin letters; Russian, Japanese, Korean and Chinese use a font of the device.

To force a language, add ?lang=pt (or another code) to the game address.

To add a language, copy one of the blocks in src/locales-more.js, translate it, add it to MORE at the end of that file, and add its code and name to LANGS, HTML_LANG and NUMBER_LOCALE in src/locales.js. The language test in test/i18n.test.mjs expects 14 languages, so update that number too.

9 Local saves

• Progress (level reached, stars, pearls, album, lesson cards already seen, decorations, daily results and settings) is 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 two keys are shown below. Their prefix is STORAGE_PREFIX in src/config.js.

shoalmates.template.save.v1.progress
shoalmates.template.save.v1.lang

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 source/dist/, which is identical to game/.

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). 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 for your distribution, including npm.

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

4. Run the commands below one by one. npm ci checks the lock file (nothing is downloaded, the project has no dependencies). npm test plays all 60 levels with a simulated player and checks the rules, the 14 languages and the save key; stop and fix any error before going on.

npm ci
npm test

5. Preview: npm run serve starts a local server; open http://localhost:5195/ 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, favicon.ico, the three style-*.css 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 to see the new version (see below).

Test shortcuts (local addresses only)

The shortcuts below work only when the page address is localhost, 127.x or a private network address (192.168.x). On any public address they are ignored, so players cannot use them. ?lang=pt (or another language code) is not a test shortcut and works on any address.

• ?level=12 opens level 12 directly.
• ?unlock unlocks all 60 levels.
• ?screen=journey opens a screen directly (home, journey, album or daily).
• ?reduced forces reduced motion.
• ?qa adds a simulated player for automated tests: run __shoalmates.auto(999, 350, 'good') in the browser console. The window.__shoalmates object (the running game) also exists only on local addresses.

http://localhost:5195/?level=12&lang=es

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 and artwork are supplied under the license of the item you purchased. The music, sound effects and narration used by the game are included in the package and can be replaced or removed (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 three style-*.css files next to index.html.
• No sound: tap the screen once; check the device is not silent and the volume sliders are up.
• Old version after an update: clear the browser cache (see below).
• Images missing after replacing art: check the file name, extension and letter case.
• An address such as ?level=5 does nothing on your website: test shortcuts only work 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.