Polar Games

A make-10 sliding block puzzle in space, with 50 levels · 1.0.0

Cosmo Ten

This guide explains how to install, customize and update the game. Pick your language at the top; screenshots stay in English.

Version 1.0.0 Edition Standalone buyer edition

This guide works without internet. Images, styles and scripts are already inside this file.

Contents
  1. Overview
  2. Quick installation by FTP
  3. Requirements and sound
  4. Controls and how the game works
  5. Screens and controls explained
  6. Map of the files
  7. Customizing levels, texts and sounds
  8. Languages
  9. Local saves
  10. Optional development
  11. Updating and cache
  12. Licenses
  13. Troubleshooting
  14. Frequently asked questions
  15. Support

1 Overview

Cosmo Ten is an HTML5 sliding block puzzle game with a toy space theme. The board holds numbered crystal blocks. The player drags a block into another one: if the two numbers add up to 10 they become a capsule, and the capsule has to leave the board through the portal of its own color. A level is won when the board is empty.

There are 50 handmade levels in 5 worlds of 10 (Moon Base, Asteroid Belt, Ice Planet, Crystal Nebula, Star Station). Each world adds something new: locked portals, asteroids, meteors, crystal blocks and surprise boxes, and the last level of each world is a challenge against the clock. Stars depend on the moves left, and every level has been solved by the game's own solver.

The game runs in any modern browser on phones, tablets and computers, in portrait, landscape and a desktop layout with keyboard shortcuts. It uses plain HTML, CSS and JavaScript modules, with no framework, no dependencies, no ads, no store, no accounts and no server code.

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 cosmo-ten-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/cosmo-ten/.
  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 three style sheets beside index.html, with names and letter case exactly as extracted.
  5. 5. Open https://your-domain.example/games/cosmo-ten/ in a modern browser.
Warning Do not upload the source/ folder, the documentation/ folder or the ZIP itself. Players need no Node.js, PHP, database or account.

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. Blocks are dragged with the mouse or a finger.
  • Browsers start sound only after a user gesture, so music and effects begin after the first tap or click.
  • 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

Drag a block with the mouse or a finger; it slides cell by cell and stops at walls and other blocks. Push it into another block: if the sum is 10 the two become a capsule with the color of the block you dragged; if the sum is smaller they join into one block with the sum; more than 10 does not fit. Push a capsule into the portal of its color (the glowing bar on the frame) to launch it.

Every drag uses one move. The counter at the top shows the moves left and the three stars: finishing with more moves to spare gives more stars. If the moves run out, the player can use Extra moves or try again. Levels 10, 20, 30, 40 and 50 also have a clock that starts on the first move.

The first levels show short tips, and a card explains each new obstacle the first time it appears: locked portal (level 8), asteroid (level 11), meteor (level 21), crystal block (level 31) and surprise box (level 41). Four power-ups sit under the board: Undo (3 free on every level), Brush (repaints a capsule), Shovel (launches a capsule at once or breaks an asteroid) and Extra moves (5 more moves). Finishing the 10 levels of a world opens its chest, with one Brush, one Shovel and one Extra moves.

On a computer the keyboard works too: Z Undo, B Brush, S Shovel, M Extra moves, R restart, Escape opens Settings or closes a window, Enter starts from the title screen. Settings (the gear) has vibration, reduced motion and the language list; the music button opens the volume sliders for music and effects.

5 Screens and controls explained

Title screen: Play starts the next level, Levels opens the world map.
Title screen: Play starts the next level, Levels opens the world map.

Marks on the screenshot

  1. Play the next level
  2. World map
  3. Music and effects volume
  4. Settings
World map: one page per world, with 10 level pads, the world chest and the gate to the next world.
World map: one page per world, with 10 level pads, the world chest and the gate to the next world.

Marks on the screenshot

  1. Stars earned out of all
  2. Settings
  3. Music and effects volume
  4. Current level
  5. Finished level with stars
  6. Locked level
  7. World chest
  8. Gate to the next world
  9. Play the current level
A level: the board with crystal blocks, a capsule and the portals, the moves left and stars, Nova the mascot and
the power-ups.
A level: the board with crystal blocks, a capsule and the portals, the moves left and stars, Nova the mascot and the power-ups.

Marks on the screenshot

  1. Moves left
  2. Stars you can still get
  3. Settings and home
  4. Nova, the mascot
  5. Number block
  6. Capsule (a 10)
  7. Portal of a color
  8. Power-ups
Win: the stars, the moves used, the total of stars and the buttons to go on.
Win: the stars, the moves used, the total of stars and the buttons to go on.

Marks on the screenshot

  1. Stars
  2. Moves used
  3. Total stars
  4. Play again
  5. Next level
Settings: vibration, reduced motion and the language list.
Settings: vibration, reduced motion and the language list.

Marks on the screenshot

  1. Vibration
  2. Reduced motion
  3. Language
  4. Close

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

game/                        upload these contents to your web host
  index.html                 entry page: title, map, level and the windows
  style.css                  base styles (screens, layouts, windows)
  style-details.css          fine tuning of the same screens
  style-theme.css            the space theme (antennas, capsules, asteroids)
  src/main.js                start-up, screens, mascot, power-ups, windows
  src/rules.js               the rules (slide, join, capsules, portals) and the solver
  src/game.js                the board on screen: drag and animations
  src/levels.js              the 50 levels (5 worlds of 10)
  src/map.js                 the world map
  src/fx.js, nine.js         particles and stretchable panels
  src/audio/sound.js         synthesized effects and music
  src/locales.js             texts: English, Portuguese, Spanish
  src/locales-more.js        texts: the other 11 languages
  src/config.js              feel numbers, colors, power-ups, moves, save key
  src/save.js, storage.js, i18n.js, viewport.js
  assets/art/                interface images, Nova and backgrounds (WebP)
  assets/music/              menu.mp3, map.mp3, play.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
  tools/build.mjs            copies the game into dist/
  tools/serve.mjs            local preview server
  tools/gen-levels.mjs       random level generator (checked by the solver)
documentation/               this guide and the customization guide
THIRD-PARTY-LICENSES/        Fredoka (SIL OFL 1.1)
DOCUMENTATION.html           opens this guide
CUSTOMIZATION.html           opens the customization guide
START-HERE.txt, CHANGELOG.txt
  • src/levels.js: the 50 levels, 10 per world. Each level lists its board size, blocks, portals, meteors and par (the fewest moves).
  • src/rules.js: the rules with no drawing (slide, join, capsules, portals, locks, asteroids, boxes) and the solver. src/game.js: the board on screen (drag, animations).
  • src/main.js: screens, mascot, power-ups, tips, win and lose windows, settings and keyboard. src/map.js: the world map. src/config.js: feel numbers (FEEL), block colors, power-ups and moves (RULES_UI) 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/audio/sound.js: the synthesized effects and the music.
  • style.css, style-details.css and style-theme.css: the styles, loaded in this order (a rule lower down wins). The last one holds the space theme.
  • assets/: interface images and backgrounds (art/, WebP), music (music/, MP3) and the font (fonts/).

7 Customizing levels, texts and sounds

Note Not a programmer? The Customization Guide shows every change step by step, with numbered screenshots of the game. It is in English. Open CUSTOMIZATION.html in the main folder of the download, or documentation/customization.html.

Customization Guide (step by step, in English)

Levels: each level in src/levels.js is a short list: board size, blocks (position, size, number, color and an optional kind), portals (side, start, length, color and an optional lock) and par. After a change run npm test: it solves every level and fails if a level has no solution or its par is wrong.

New levels: tools/gen-levels.mjs creates random levels with the size, shapes, colors and obstacles you ask for and keeps only those the solver can finish. Paste the result into a world in src/levels.js.

Difficulty: RULES_UI in src/config.js sets the move limit and the stars from the par of each level, the level where each power-up appears, the free Undo per level and the power-ups a new player starts with.

Look: the logo is assets/art/logo.webp, Nova the fox is fox-*.webp, the worlds use bg-*, map-* and w2- to w5- backgrounds, and the blocks, capsules, buttons and panels are the other files of assets/art/. Replace a file keeping its name and shape. World names are the texts w1 to w5.

Music and sound effects

Music: assets/music/menu.mp3 plays on the title screen, assets/music/map.mp3 on the world map and assets/music/play.mp3 during the levels, in a loop. To change a track, replace the MP3 keeping the name. To remove the music, delete the files: the game stays silent where a track is missing.

Sound effects: all effects are synthesized in src/audio/sound.js (object SYNTH, one short function per effect), so there are no effect files. Change the numbers of an effect to change its pitch, length or volume.

Warning Keep the save key unchanged on a live site. A different key makes the game ignore existing progress and start a new save.

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. 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. World names are the texts w1 to w5 of each language.

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/locales.test.mjs expects 14 languages, so update that number too.

9 Local saves

  • Progress (level reached, stars of each level, power-ups, chests, tips already seen) and the settings 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 two keys are shown below. Their prefix is STORAGE_PREFIX in src/config.js.
cosmo-ten.template.save.v1.progress
cosmo-ten.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.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 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.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 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 checks the rules, solves the 50 levels, checks 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: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 style sheets, 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).

Note Troubleshooting: ENOENT or a missing package.json means the terminal is in the wrong folder. EBADENGINE means Node.js is too old. If PowerShell blocks npm.ps1, use Command Prompt instead; do not change security settings.

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, 10.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; ?screen=map opens the world map.
  • ?unlock opens every level, ?reset erases the progress of this browser, ?notutorial hides the tips and ?allpowers unlocks the power-ups.
  • ?qa exposes the running game as window.__cosmoten for automated tests in the browser console.
http://localhost:5196/?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 the artwork are supplied under the license of the item you purchased. The music used by the game is 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 style sheets next to index.html.
  • npm test fails after you edit a level: the message names the level. Either it has no solution or its par is not the number of moves the solver finds; write the number the test prints.
  • No sound: tap the screen once; check that the device is not silent and the volume sliders are up.
  • Old version after an update: clear the browser cache (see below).
  • 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

Does the game work without internet?
The game calls no external services. It is not an installable offline app, so players need to reach your web address to load it.
Can I add ads, a store, cloud saves or a ranking?
Not in this edition. It has no ad, payment, sync or ranking code. Adding them is developer work that needs your own accounts.
Can I publish it on game portals or app stores?
Yes, within the terms of the license you purchased. Wrapping it as an app needs your own developer accounts and tools.
Can I make my own levels?
Yes. Edit src/levels.js or generate levels with tools/gen-levels.mjs, then run npm test to confirm every level can be solved. The Customization Guide has the step-by-step recipe.
How do I reset the progress while testing?
Clear the site data for the game address in the browser, or run localStorage.clear() in the browser console. On a local address, ?reset does the same.

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.