Ocean Words — Buyer Guide

1 Overview and package contents

Ocean Words is a standalone HTML5 word search game. Players slide a finger or the mouse across a grid of letters to find the hidden words of a theme. Words hide across, down, backwards and on diagonals. Every find is celebrated with glowing marks, flying words, a combo and sound.

The game plays in ten languages (English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish and Indonesian), each with its own word lists written for that language. It has 35 themes of 30 words (more than 1000 words per language), a 15-level campaign, a daily puzzle with a day streak, scores, combos and stars. There are no ads, no accounts, no payments and no online service: everything is saved on the device that plays.

This guide describes version 1.0.0. Open documentation/index.html by double-clicking it: it needs no internet and no server.

2 Installing the game

The game is a set of static files. You do not install anything on the server: you upload the contents of the game/ folder.

1. Unzip the download on your computer.
2. Connect to your web hosting with FTP, SFTP or your host's file manager.
3. Create the folder where the game will live, for example public_html/words/ (or use the site's root folder).
4. Upload the CONTENTS of the game/ folder into it: index.html must end up directly inside that folder.
5. Open the address in a browser, for example https://your-site.com/words/. The game shows its start screen with "Tap to start".

public_html/words/
├── index.html
├── aurora.config.js
├── audio-idle.js
├── assets/
├── art/
├── audio/
├── data/
├── lib/
└── licenses/

3 Requirements

• Any static web hosting: Apache, Nginx, shared hosting, a CDN, Netlify, GitHub Pages, Amazon S3 and similar. No PHP, no database and no Node.js on the server.
• HTTPS is recommended. Sound, full screen and vibration work best on a secure address.
• Current Chrome, Edge, Firefox and Safari 16.4 or newer, on computer, phone and tablet. The game uses ES modules and an import map, which older browsers do not support.
• The server must send each file with its usual type: .js as JavaScript, .json as JSON, .webp as WebP, .mp3 as MP3 and .woff2 as a font. Normal hosting does this by default.

The game never contacts another website: there is no analytics, no font server, no ad network and no external script. The browser only reads the files you uploaded.

4 How to play

Each round has a theme (Ocean, Space, Kitchen and so on) and ten words, shown five at a time in grids. Find every word of a grid to move on to the next one. The round ends when all ten are found: the game never ends in failure, so there is always a way to finish.

Marking a word

• Mouse or finger: press the first letter of a word and slide to its last letter, then let go. Either end of the word works, and a slightly crooked slide snaps to the nearest straight line.
• Two taps: tap the first letter, then tap the last letter. This helps on small screens and with a trackpad.
• Keyboard: arrow keys move the cursor, Space or Enter marks the first letter and then the last, Esc cancels, and the ? key uses a hint.
• Tap a word in the list to aim the next hint at that word.

Hints and help

• Each round gives three hints. The first marks the first letter of a word, the second adds its second letter (which shows the direction) and the third traces the whole word.
• If a player is stuck for 45 seconds, or slides wrong three times in a row, the game points at the Hint button. A hint is always available when needed: no player is left unable to finish.
• A slide that starts a word correctly but stops too early is shown as "Almost!" and is not counted as a mistake.

Points, combo and stars

Ways to play

5 The screens

These are real screenshots of the game. The numbers on each picture match the list under it.

1 2 3 4 5 6 7 8 9

Marks on the screenshot

1. 1 Sound on or off.
2. 2 Full screen.
3. 3 How to play, with a tutorial.
4. 4 Settings.
5. 5 Quick Play: a random theme.
6. 6 Categories: pick a theme.
7. 7 Campaign: the 15 levels.
8. 8 Daily puzzle, with the day streak when there is one.
9. 9 Language chip: opens the list of languages.

1 2 3

Marks on the screenshot

1. 1 Back to the menu.
2. 2 Title; scroll down for the other themes.
3. 3 A theme: tap it to start a round.

1 2 3 4

Marks on the screenshot

1. 1 The selected level, its theme and what makes it harder.
2. 2 The level to play now, with the stars it has earned.
3. 3 A locked level: finish the previous one first.
4. 4 Play the selected level.

1 2 3 4 5 6 7 8

Marks on the screenshot

1. 1 Restart the round.
2. 2 Words found so far.
3. 3 Score.
4. 4 Progress through the grids, and the theme.
5. 5 The combo: its bar empties until the next find.
6. 6 The words to find; found words are struck through.
7. 7 The letter grid. Found words keep a glowing mark in their own colour.
8. 8 Hint, with the hints left.

1 2 3 4 5 6

Marks on the screenshot

1. 1 Result and theme.
2. 2 Stars for how cleanly the round was played.
3. 3 Score and best score.
4. 4 Time, best combo, hints used and misses.
5. 5 All the words found.
6. 6 Play again, or go back to the levels in the campaign.

1 2 3 4 5 6

Marks on the screenshot

1. 1 Music volume.
2. 2 Sound effects volume.
3. 3 Narrator voice volume.
4. 4 Calm mode: less motion.
5. 5 Language.
6. 6 Close.

1 2 3

Marks on the screenshot

1. 1 The language in use.
2. 2 Any other language: the whole game changes at once, including the word lists.
3. 3 Close.

6 What is in the package

Every script and stylesheet is readable: nothing is minified, and each file ends with a comment such as End of assets/rules.js.

7 The settings file

Open aurora.config.js in any text editor, change a value, save, and upload it again. No rebuild is needed. Every line is optional: delete a line to use its default. A mistake in the file never stops the game; the wrong value is ignored.

window.AURORA_CONFIG = {
  storagePrefix: 'oceanWords',
  language: 'auto',
  languages: ['en', 'pt', 'es', 'fr', 'de', 'it', 'nl', 'pl', 'tr', 'id'],
  dailyChallenge: true,
  comboSeconds: 8,
};

Players change the sound volumes, Calm mode and the language themselves in the Settings panel; those choices are saved on their device too.

8 Customizing the game

Words and themes

The word lists are plain JSON files in data/themes/, one per language. Open the file of the language you want to change in any text editor. You can do this in the uploaded game or in source/public/data/themes/.

{
  "wordsPerRound": 10,
  "themes": [
    {
      "id": "ocean",
      "name": "Ocean",
      "words": ["coral", "shark", "dolphin", "octopus", "seaweed"]
    }
  ]
}

• id: a short name made of lowercase letters, the same in every language file. It selects the theme's picture and keys its best scores.
• name: the title players see (up to 24 characters).
• words: at least wordsPerRound words. Each word has 3 to 10 letters once accents are removed (ÇÃO hides as CAO), and is a single word with no spaces or hyphens. Words that do not fit are skipped, so a typo never breaks the game.
• wordsPerRound is how many words a round uses, five per grid (10 means two grids).
• Optional emoji: shown instead of a picture for that theme.

To add a theme, add it to every language file you offer, with the same id. Its picture is the file art/categories/<id>.webp (a square image with a transparent background, about 1254 × 1254 pixels). Without a picture and without an emoji, the theme shows a small star.

Pictures and sound

• Logo: replace art/ocean-logo.webp with your own image of a similar shape (keep the file name).
• Backdrop: the two pictures in assets/ whose names start with ocean-scene and ocean-portrait are the background on wide and tall screens. Replace them with images of the same shape, keeping the file names.
• Music: replace audio/music/bubble-quest.mp3 with your own loop, keeping the name.
• Narrator: the recordings are in audio/narrator/en/, pt/ and es/, one file per line. A line without a file is simply not spoken and its caption is shown.

Colours and layout

The colours, sizes and animations are in source/src/styles.css, styles-more.css and base.css. The main colours are variables at the top of styles.css (the sections starting :root). After editing, rebuild the game as explained in the section "Building from the source".

Adding a language

1. Copy source/src/i18n/en.ts to <code>.ts, translate the texts and keep every {…} written in braces.
2. Copy source/public/data/themes/en.json to <code>.json and write native words for each of the 35 themes.
3. Register the code in source/src/i18n/index.ts (the lists LANGS, LANG_NAMES and DICTS), and in languages in aurora.config.js.
4. Add a list of words the random filler letters must never spell to source/src/i18n/blocked.ts.
5. Run node tools/check-lang.mjs <code> and npm test, then rebuild.

9 Languages

The interface and the word lists are available in English, Portuguese (Brazil), Spanish, French, German, Italian, Dutch, Polish, Turkish and Indonesian. The game starts in the language of the player's browser when it is one of these, and in English otherwise. Players change it with the language chip on the menu or in Settings, and the game remembers the choice.

The word lists are written natively for each language, not translated word by word, so every language has its own set of 35 themes with 30 words each. Words may use accents and special letters (such as ç, ñ, ü, ğ, ł); inside the grid they appear without them.

Narration is recorded in English, Portuguese and Spanish. The other languages hear the English narrator while the on-screen captions are in their own language. This guide itself is available in 14 languages from the menu at its top.

10 Saved progress

The game saves in the browser of the device that plays, using local storage. There is no account and nothing is sent to any server.

• Settings (volumes, Calm mode, language), the campaign stars and unlocked levels, the best scores and the daily streak are saved separately.
• Every saved name starts with the storagePrefix from the settings file, followed by a dot and a short word: .prefs.v1, .campaign.v1, .best.v1 and .daily.v1.
• Saves belong to one browser on one device. Another browser or device starts fresh, and so does a private window.
• To start over, clear the site's data in the browser, or use "Clear site data" in the developer tools for the game's address.

11 Building from the source (optional)

You do not need this to run the game. It is for people who want to change the code, the colours or the languages. The ready-to-play files in game/ were made from the source/ folder with the steps below.

Step by step for beginners

1. Install Node.js 22.12 or newer (the "LTS" version) from nodejs.org. On Windows and macOS use the installer; on Linux use your distribution's package or the installer from the site. npm comes with it.
2. Open a terminal: Windows Terminal or Command Prompt on Windows, Terminal on macOS or Linux.
3. Check the install by typing node -v and npm -v. Both should print a version number; node -v must show 22.12 or higher.
4. Go into the folder that contains package.json, which is the source/ folder of this download: cd path/to/source.
5. Install the tools exactly as locked: npm ci. This needs internet once and creates a node_modules folder.
6. Run the checks: npm test. All tests should pass.
7. Build the game: npm run build. The result is a folder called dist/.
8. Try it locally: npm run preview, then open the address it prints. For editing with instant reload use npm run dev.
9. Upload the CONTENTS of dist/ to your hosting, exactly as you would upload game/.

node -v
npm -v
npm ci
npm test
npm run build
npm run preview

If something goes wrong

12 Updating the game

1. Back up your current game/ folder, especially aurora.config.js and any word list or picture you changed.
2. Upload the new contents of game/ over the old files, keeping the same names.
3. Put your own settings back into the new aurora.config.js (keep your storagePrefix so saves are kept).
4. Reload the game. If the old version still appears, clear the cache as described below.

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.

13 Credits and licences

• Phaser 3.90.0 by Phaser Studio Inc., MIT licence. Used for the sparks, rings and confetti.
• Fredoka and Figtree fonts by their project authors, SIL Open Font License 1.1, bundled as local files.
• The music "Bubble Quest", the narrator's recordings, the logo, the backdrops, the theme pictures, the word lists and the interface texts were prepared by Polar Games for this item and are licensed to you with it.
• Sound effects are generated by the game in the browser and are not files.

The licence texts are in THIRD-PARTY-LICENSES/ and game/licenses/. Keep them when you publish the game. Your Envato Market licence (Regular or Extended) defines how you may use the item; read it on the item page.

14 Solving problems

15 Frequently asked questions

16 Support and version history

Support and custom work: willian@polargames.com.br. Include your purchase reference when you have it. This guide does not promise response times or a release schedule.

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.