Polar Games

Fill lines. Charge the Star Gem. · 1.0.0

Jewel Block Puzzle

Drag glowing gem pieces onto the board of a torch-lit temple, clear rows and columns, and charge the Star Gem to clear a whole row and column at once. Endless play and a daily challenge, in 14 languages, for phones, tablets and computers.

Version 1.0.0 Edition HTML5 static edition

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

Contents
  1. Overview
  2. Install the ready-to-play game
  3. Requirements
  4. Controls and how the game works
  5. Interface
  6. Settings, sound and language
  7. File map
  8. Customize
  9. Languages
  10. Saved data
  11. Install Node.js, test and rebuild
  12. Updates and cache
  13. Troubleshooting
  14. Frequently asked questions
  15. Support and licenses
  16. For AI assistants

1 Overview

Jewel Block Puzzle is a block puzzle on an 8×8 board. Three pieces wait in the tray; drag each one onto the board, and every full row or column clears. When all three pieces are placed, three new ones arrive. Some blocks carry a star: clearing them fills the charge bar, and a full bar gives the special power (Star Gem), which clears a whole row and column at once. The game ends when no piece fits and no power is left.

This edition has no online leaderboard, accounts or in-app purchases. The best score, the daily streak and the settings are saved in the player's browser only.

This download includes the ready-to-host game, the full editable source, this guide, a customization guide and the third-party license notices.

START-HERE.txt
DOCUMENTATION.html
CUSTOMIZATION.html
CHANGELOG.txt
documentation/index.html
game/
source/
THIRD-PARTY-LICENSES/

2 Install the ready-to-play game

Only the game/ folder needs to be uploaded to play.

  1. Extract the whole ZIP on your computer.
  2. Upload the contents of game/ to a folder on static hosting, using FTP or your host's file manager.
  3. Open that folder's web address in a modern browser. All paths are relative, so the game also works inside a subfolder.
  4. Tap or click to start; browsers require a user gesture before playing audio. Test on the devices your players will use.
Warning Opening index.html straight from the disk does not work: browsers block JavaScript modules on file:// pages. Always open the game through a web address (your host, or npm run dev on your computer).

3 Requirements

  • Any static web host able to serve plain files over HTTPS.
  • A current desktop or mobile browser with JavaScript enabled.
  • Node.js 26.13 or newer, only if you want to run the tests or the local server, or rebuild game/ from the source.

No database, backend language or compile step is needed: the game is plain HTML, CSS and JavaScript modules.

The game fits phones, tablets and computers in portrait and landscape; the layout changes with the screen shape.

4 Controls and how the game works

Drag a piece from the tray and drop it on the board; a preview shows where it lands. A full row or column clears and scores. Clearing several lines at once scores more, and clearing again within 3 moves builds a combo that multiplies the points. Emptying the whole board gives a Perfect bonus of 3,000 points.

To use the special power, tap its button next to the charge bar, then tap any cell: its row and its column clear. Up to 3 powers can be stored, and the number on the button shows how many are ready. Each full charge bar has 6 segments.

Play starts a new game; reloading the page also starts a new one. The Daily challenge uses the same board for every player on the same day (UTC), with a score goal between 1,500 and 4,000 (weekends are 500 higher) and a streak for consecutive days. A short tutorial shows the first moves the first time.

5 Interface

Four real captures from the shipped build, with numbered marks for the elements mentioned in this guide.

Main menu
Main menu

Marks on the screenshot

  1. Play: starts a new game
  2. Daily challenge, with today's goal
  3. Best score
  4. Settings: vibration, less motion and language
  5. Sound: music and effects volumes
Gameplay: board, tray and charge bar
Gameplay: board, tray and charge bar

Marks on the screenshot

  1. Score, with the combo under it
  2. Best score
  3. Settings, sound and pause buttons
  4. Charge bar: cleared star blocks fill it
  5. Special power (Star Gem) and how many are ready
  6. Tray with the next three pieces
Settings panel
Settings panel

Marks on the screenshot

  1. Vibration (hidden on devices without it)
  2. Less motion: no screen shake and calmer effects
  3. Language: opens the list of 14 languages
Game over
Game over

Marks on the screenshot

  1. Final score and the best score
  2. Play again
  3. Back to the menu

6 Settings, sound and language

Settings has vibration, less motion and the language list; every change applies at once, without reloading. Less motion starts switched on when the device asks for reduced motion. The sound button opens separate volumes for music and effects; the narrator voice follows the effects volume. A fullscreen button appears where the browser supports it (not on iPhone).

The interface ships in 14 languages: English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean and Chinese. The first visit picks the browser language; the choice in Settings is remembered.

7 File map

Path What it is
game/ Ready-to-host game; upload its contents to your server.
source/index.html The page and the screens (title, pause, game over, settings, sound and languages).
source/style.css Look of every screen, button and panel.
source/src/config.js Rules and numbers: board size, pieces in the tray, star chance, charge, points and colors.
source/src/shapes.js Piece shapes.
source/src/locales.js Interface texts in 14 languages.
source/src/scene.js Board, pieces, effects and the in-game HUD drawing.
source/assets/ Art (WebP), sound effects, narrator lines and music (MP3), fonts.
source/src/platform.js Portal hooks: empty in this edition, ready for a portal SDK.
source/test/, source/tools/ Tests, local server and the build that writes dist/.

8 Customize

Rules and numbers live in source/src/config.js: board size, tray size, the chance of a star block, the charge needed for one power, the maximum stored powers, the combo window, the points table and the Perfect bonus. Piece shapes are in source/src/shapes.js. Art is in source/assets/skin/ (the eight block colors are gem-0.webp to gem-7.webp), sounds in source/assets/sfx/, narrator lines in source/assets/voice/ and the music in source/assets/music.mp3. Replace a file with another of the same name and size ratio to reskin the game.

// source/src/config.js (excerpt)
export const GRID = 8;
export const HAND_SIZE = 3;
export const SPARK_CHANCE = 0.34;
export const CHARGE_PER_ZAP = 6;
export const MAX_ZAPS = 3;
export const PERFECT_BONUS = 3000;

After editing, run npm test and npm run build, then upload the new dist/ contents. CUSTOMIZATION.html, in the root of the download, walks through the most common changes step by step.

9 Languages

The interface ships in 14 languages: English, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean and Chinese. The first visit picks the browser language; the choice in Settings is remembered.

All interface texts are in source/src/locales.js, one block per language with the same keys. To change a word, edit it in every language block. The narrator lines are in English in every language.

10 Saved data

The best score, the daily challenge progress, the settings, the language and the tutorial flag are saved automatically in the browser's local storage, under keys that start with jewel-block-puzzle.template.save.v1. The game in progress is not saved: reloading starts a new game.

  • Clearing the browser's site data for the game's address deletes this save.
  • There is no cloud save or account; data does not move between devices or browsers.

Uploading a new build over an existing install keeps the saved data, as long as the save key stays the same.

11 Install Node.js, test and rebuild

Only needed to run the tests, play on your computer or rebuild game/ after editing.

Install Node.js LTS 26.13 or newer from nodejs.org, then open a terminal in the extracted source/ folder and run the commands below in order. npm run dev starts a local server at http://localhost:5260/.

npm ci
npm test
npm run build
npm run dev

12 Updates and cache

Uploading a new build over an existing install keeps the saved data, as long as the save key stays the same.

Re-upload the full contents of game/ (or your new dist/), overwriting the previous files.

An old version shown in a browser tab after updating is almost always a caching issue, not a failed upload.

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 Troubleshooting

  • Blank page: check the browser console for a failed file, and confirm every file from game/ was uploaded, including game/src/ and game/assets/.
  • Blank page on your computer: the page was opened from the disk; start npm run dev and use the address it shows.
  • No sound: audio starts only after a tap or click, by browser policy; check the volumes in the sound panel.

Audio needs at least one user gesture (tap, click or key press) before it can play; this is a browser rule, not a bug in the game.

14 Frequently asked questions

Can I resell this template as-is?
Check the item's license terms on its CodeCanyon page before reselling, redistributing or reusing it in another product.
Does the game need a server or database?
No. The game/ folder is static files; saved data stays in the player's browser.
Can I put it on a game portal?
Yes. The game calls simple hooks in source/src/platform.js (loading done, gameplay start and stop, mute, ad pause). They do nothing in this edition; call the portal SDK inside them, then rebuild.

15 Support and licenses

The Baloo 2 font is under the SIL Open Font License; its license is in THIRD-PARTY-LICENSES/ and in source/assets/fonts/.

For product support, write to the address below.

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.

For AI assistants

  • Read the installation and customize sections before changing anything. Upload only game/ (or dist/) to a host; source/ is the editable project.
  • Keep the save key prefix jewel-block-puzzle.template.save.v1, the relative paths and every language block unless the buyer asks for a change.
  • Do not assume an account system, a server or payments. This edition has none, and the code is the source of truth.