Customization Guide

Make Glowpane Puzzle your own game: your own pictures and chapters, backgrounds, logo, texts, music, colors and difficulty. 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: Photopea (in the browser), GIMP or Krita. Level pictures can be JPG or WebP; interface pictures are WebP with a transparent background. You can save a PNG and convert it to WebP at squoosh.app.
• To see the game on your computer, a browser and one of these: the local server included in source/ (npm run serve, needs Node.js, see the main guide), or any local web server you already use (for example XAMPP, WAMP or MAMP). Opening index.html with a double click does not work: browsers block the game files when the page comes from the disk.

Which folder do I edit? The simplest way: edit the files inside game/ and upload that folder. If you also use the developer tools, edit source/ instead and run npm run build, which copies everything to source/dist/ (the same as game/). Both folders have the same file names, so every recipe below works in either one.

2. Where everything is

Each number on the screenshot matches a line of the table under it, with the exact file to change. Interface texts are in src/locales.js (English, Portuguese, Spanish) and src/locales-more.js (the other 11 languages); the table gives the key of each text.

Title screen

1 2 3 4

Home screen

1 2 3 4 5 6 7 8 9

Level map

1 2 3 4 5 6 7 8 9 10

A level

1 2 3 4 5 6 7 8 9 10

3. More screens of the game

4. Recipe A: replace a level picture

1. Prepare your picture. Square, 1024×1024 pixels or larger gives the best result. Any other size or shape also works: the game keeps the middle of the picture and cuts it to the grid of the level.
2. Choose pictures with detail everywhere. Big areas of one flat color (a clear sky, a white wall) make pieces that look the same, and the puzzle becomes frustrating.
3. Save it as JPG (quality about 85) or WebP, so the game stays light. Use only pictures you have the right to publish.
4. Give it exactly the same name as the picture you replace, for example assets/levels/ch1/01-fox.jpg, and copy it over the old file. Nothing else changes.
5. To use a different name, change the name in the images list of that chapter in assets/levels.json as well (recipe B).

5. Recipe B: add your own levels and chapters

All levels come from one file, assets/levels.json. One picture = one level. A chapter is a name, a folder of pictures and the list of those pictures in the order they are played:

{
  "chapters": [
    {
      "name": "Spring Meadow",
      "folder": "assets/levels/ch1",
      "images": ["01-fox.jpg", "02-owl.jpg", "03-hummingbird.jpg"],
      "mapBackground": "assets/art/bg-map.webp",
      "mapBackgroundWide": "assets/art/bg-landscape.webp"
    },
    {
      "name": "My Photos",
      "folder": "assets/levels/mine",
      "images": ["beach.jpg", "dog.jpg", "mountain.jpg"]
    }
  ]
}

1. Create a folder for the new chapter, for example assets/levels/mine/, and put your pictures in it.
2. Open assets/levels.json in the code editor. Copy a whole chapter block (from { to }), paste it after the last one and put a comma between the two blocks.
3. Change name (shown on the map and on the home screen), folder and the images list. File names are case sensitive: Dog.JPG is not dog.jpg.
4. mapBackground and mapBackgroundWide are optional (recipe D). Without them the chapter uses the default backgrounds.
5. To remove a level, delete its name from the list. To remove a chapter, delete its whole block and the comma before it. To change the order, move the names.
6. Save, reload the game and open the map: the new chapter appears after the previous one and opens when the previous chapter is finished.

The chapter name is shown as written, in every language. Players keep their stars by level number, so if you reorder levels in a game that is already online, the stars stay on the same numbers.

6. Recipe C: change the number of levels and the difficulty

• How many levels: as many as there are pictures in assets/levels.json. The game has 50 (5 chapters of 10). The map and the rose window are designed for 10 levels per chapter. Other counts work: a chapter of 3 or 7 shows fewer windows, and with more than 10 the map page scrolls and the rose window stays fully lit after 10.
• Grid size of each level: it depends on the chapter and on the position of the level inside the chapter. Open src/levels.js:
  • LADDER lists the grids from easy to hard: 2×2, 3×3, 3×4, 4×4, 4×5, 5×5, 5×6, 6×6.
  • The first level of the game is 2×2. Every chapter starts one step higher than the one before it.
  • BIG (positions 4 and 9, that is the 5th and 10th level of each chapter) marks the bigger windows, which jump further up the ladder.
  • ALT (positions 2, 6 and 8) marks the levels one step harder than the rest of the chapter.
• To make the game easier, remove the last grids of LADDER (for example end it at [5, 5]); to make it harder, start the ladder higher. Grids bigger than 6×6 make very small pieces on phones.
• The par (fewest moves) of each level is calculated by the game from the shuffle; you do not set it by hand. The shuffle of each level comes from its level number, so it is the same on every visit.
• Run npm test in source/ after any change in src/levels.js. If you change LADDER, also update the expected grids at the top of test/levels.test.mjs (the first grid [2, 2] and the largest side, 6), which describe the ladder shipped with the game.

7. Recipe D: change the backgrounds

• Title and home screen: assets/art/bg-landscape.webp (wide screens, 16:9, at least 1600×900) and assets/art/bg-portrait.webp (phones held upright, 9:16, at least 940×1670). Replace them keeping the names.
• Map and levels of one chapter: set mapBackground (tall picture) and mapBackgroundWide (wide picture) in that chapter of assets/levels.json. The game includes bg-map.webp, bg-map-c2.webp … bg-map-c5.webp and bg-landscape.webp, bg-land-c2.webp … bg-land-c5.webp.
• Keep the middle of the background calm and a bit dark: the level windows and the board sit there.

8. Recipe E: change the logo and the game name

1. Logo: replace assets/art/logo.webp with your logo as WebP with a transparent background, about 1100 pixels wide. It is used on the title screen.
2. Name in the browser tab: open index.html and change the text inside <title>. The same file has the logo description in alt="Glowpane Puzzle".
3. The line under the logo is the key tagline (recipe F).
4. The browser tab icon is assets/art/ic-star.webp (the line with rel="icon" in index.html). Point it to another picture if you want a different icon.
5. The small version number on the title screen is the text v1.0 in index.html.

9. Recipe F: change texts and translations

1. Open src/locales.js. Each language is a list of key: 'text'. English is the block const en, Portuguese const pt, Spanish const es; the other 11 languages are in src/locales-more.js.
2. Change only the text between the quotes. Keep the key, the quotes and the comma. Keep words in braces such as {n}: the game puts a number there.
3. Change the same key in every language you use. A key missing in a language shows the English text.
4. Useful keys: tagline (line under the logo), tapToStart, restored (win title), chapterDone, allDone (shown after the last level), l_drag, l_merge and l_group (the captions of levels 1, 2 and 3).
5. Chapter names are not here: they are the name of each chapter in assets/levels.json.
6. Run npm test in source/: it checks that the 14 languages have the same keys and the same {n} marks.

10. Recipe G: change hints and stars

• Starting hints: START_HINTS in src/config.js (3).
• Hints earned: the player earns 1 hint the first time a level gets 3 stars. This is in recordWin in src/save.js.
• Stars: starsFor at the end of src/levels.js: 3 stars at or under par, 2 stars up to one and a half times the par (par * 1.5), 1 star above that. Change 1.5 to be more or less generous.
• Feel of the game (speed of the pieces, shake, sparks, vibration, the delay before an idle piece glows): the FEEL block in src/config.js. Each number has a short comment next to it.

11. Recipe H: replace or remove the music and sounds

• Music: assets/music/menu.mp3 plays on the menus and assets/music/play.mp3 during the levels, both in a loop. Replace a file with your MP3 keeping the name. A track that loops without a gap at its end sounds best.
• Remove the music: delete the two files. The game notices the missing file once and plays nothing. Players can also turn the music down in Settings.
• Sound effects (glass chimes, clicks, the win fanfare) are made by the code in src/sound.js, so there are no effect files to replace. The starting volumes are VOL in src/config.js (0 to 1).
• Use only music you have the right to publish.

12. Recipe I: change colors, buttons and the font

• Colors of the texts: at the top of style.css, --ink (light text), --gold (gold details) and --deep (dark violet).
• Buttons and ribbons are three-part pictures: the left end (-l), the middle that stretches (-m) and the right end (-r), for example btn-green-l.webp, btn-green-m.webp, btn-green-r.webp. Keep the same height in the three parts. The round buttons use btn-round.webp and the icons are the ic-*.webp files.
• Panels (settings, pause, win) use the frame assets/art/panel-glass.webp.
• Sizes in style.css are written in --u, which is 1% of the game column, so everything grows and shrinks together on every screen.
• Font: Fredoka, in assets/fonts/, declared by the four @font-face blocks at the top of style.css. To use another font, add its .woff2 files to assets/fonts/ and change the file names and the font-family there. Check that its license allows use in games.

13. 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 level list 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.

14. If something goes wrong

• The game stops on the first screen after you edit a file: a comma, quote or brace is missing in assets/levels.json or in a .js file. Press F12 and open the Console: it shows the file name and the line with the error. Compare that line with your backup.
• A level never finishes loading: the picture name in assets/levels.json is different from the real file (names are case sensitive), or the picture is in another folder.
• 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).