Sandy Puzzle · Customization Guide · version 1.0.0 · Main buyer guide

Customization Guide

Make Sandy 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:

Make a backup first. Copy the whole game/ folder (or source/) to a safe place before you change anything. If something breaks, put the backup back.

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

Title screen, real screenshot with numbered parts 1 2 3 4 5
# What you see File to change
1 Logo assets/art/logo.webp, a picture with a transparent background (recipe E).
2 Crab and sandcastle assets/art/title-hero.webp, a picture with a transparent background (recipe E).
3 Subtitle Text: key tagline in src/locales.js and src/locales-more.js (recipe F). Wooden sign: assets/art/wood-sign.webp.
4 Tap to start button Text: key tapToStart. Button picture: assets/art/btn-green-l.webp, btn-green-m.webp and btn-green-r.webp (recipe I).
5 Background assets/art/bg-landscape.webp on wide screens and assets/art/bg-portrait.webp on phones held upright (recipe D).

Home screen

Home screen, real screenshot with numbered parts 1 2 3 4 5 6 7 8 9 10 11
# What you see File to change
1 Stars earned Icon: assets/art/ic-star.webp; wooden sign: wood-sign.webp. The sum of the best stars of every level.
2 Hints left Icon: assets/art/ic-hint.webp. Starting number: START_HINTS in src/config.js (recipe G).
3 Chapter scene assets/art/chapter-c1.webp to chapter-c5.webp, one per chapter: the book line of the chapter in assets/levels.json (recipe B). It starts sand-coloured and the colour comes in from the left as the levels of the chapter are finished.
4 Row of shells One shell per level of the chapter: assets/art/shell-5.webp (not finished yet) and shell-1.webp to shell-4.webp (finished).
5 Sand frame assets/art/sand-frame.webp. The same picture frames the map and the board; the styles repeat its edges, so keep the corners in the corners.
6 Chapter name The name of the chapter in assets/levels.json (recipe B). "Chapter 1" is the key chapterN. Ribbon picture: assets/art/ribbon-l.webp, ribbon-m.webp, ribbon-r.webp.
7 Chapter progress Finished levels of the chapter out of all its levels. Counted by the game from the list of pictures.
8 Map button Icon: assets/art/ic-map.webp; round swim-ring button: btn-round.webp; text: key map.
9 Play button Texts: keys play and levelN. Button picture: assets/art/btn-green-l.webp, btn-green-m.webp, btn-green-r.webp.
10 Settings button Icon: assets/art/ic-gear.webp; text: key settings.
11 Background assets/art/bg-landscape.webp on wide screens and assets/art/bg-portrait.webp on phones held upright (recipe D).

Level map

Level map, real screenshot with numbered parts 1 2 3 4 5 6 7 8 9 10
# What you see File to change
1 Home button Icon: assets/art/ic-home.webp.
2 Stars out of all Stars earned out of 3 stars per level. Counted by the game from the list of pictures.
3 Chapter name The name of the chapter in assets/levels.json (recipe B).
4 Next / previous chapter Icon: assets/art/ic-back.webp (turned around for "next"). A side swipe on the map does the same.
5 Chapter pages One dot per chapter, drawn by the styles. It grows by itself when you add chapters.
6 Finished level The level picture as a small postcard with its stars and its number. Drawn by the styles from the level picture.
7 Current level The level picture cut into 3×3 shuffled squares by the code, with the level number.
8 Locked level Closed shell with a padlock: assets/art/shell-locked.webp.
9 Path between levels Dotted footprints drawn by the code (trail() in src/main.js): orange up to the current level, brown after it.
10 Background The same background as the home screen. A chapter can have its own: mapBackground (phones held upright) and mapBackgroundWide (wide screens) in assets/levels.json (recipe D).

A level

A level, real screenshot with numbered parts 1 2 3 4 5 6 7 8 9 10
# What you see File to change
1 Pause button Icon: assets/art/ic-pause.webp. Opens the pause panel with the settings.
2 Level number Text: key levelN. Wooden sign: assets/art/wood-sign.webp.
3 Moves and par Text: key moves. The three small stars follow the rule of recipe G.
4 The pieces The level picture, cropped in the middle and cut into the grid of that level (recipes A, B and C).
5 Sand frame of the board assets/art/sand-frame.webp, the same picture used on the home screen and on the map.
6 Wooden panel assets/art/wood-panel.webp. On wide screens it holds the level number, the moves and the buttons; the same picture is the body of the settings, pause and win panels.
7 Hint button Icon: assets/art/ic-hint.webp; text: key hint. The number is the hints left (recipe G).
8 Progress bar How much of the picture is joined. Drawn by the styles (recipe I).
9 Peek button Icon: assets/art/ic-eye.webp; text: key peek. While it is held, the whole picture shows over the board.
10 Background of the level The same background as the map (mapBackgroundWide of the chapter on wide screens when it is set), recipe D.
A locked chapter on the map, real screenshot
A locked chapter can be viewed, not played. The message is the key chapterLocked.
The win panel, real screenshot
Win panel: stars, the crab (crab-cheer.webp), moves against the par, Next, Home and Replay. The red banner is ribbon-pink-l.webp, -m, -r.
Home screen on a phone, real screenshot
Home screen on a phone held upright (bg-portrait.webp).
A level on a phone, real screenshot
A level on a phone: the grid turns tall and the buttons go under the board.
Pause panel on a phone, real screenshot
Pause panel: Resume, Home, Restart and the settings. The crab on top is crab-peek.webp.

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-castle.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": "Sunny Beach",
      "folder": "assets/levels/ch1",
      "images": ["01-castle.jpg", "02-umbrella.jpg", "03-crab.jpg"],
      "book": "assets/art/chapter-c1.webp"
    },
    {
      "name": "My Photos",
      "folder": "assets/levels/mine",
      "images": ["garden.jpg", "dog.jpg", "mountain.jpg"],
      "book": "assets/art/my-scene.webp",
      "mapBackground": "assets/art/my-map-tall.webp",
      "mapBackgroundWide": "assets/art/my-map-wide.webp"
    }
  ]
}
  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. book is the chapter scene of the home screen: a WebP picture with a transparent background, about 900×655 pixels. It is optional: without it the game uses one of its own five scenes (chapter-c1.webp to chapter-c5.webp, in turn). The setting is called book only for technical reasons.
  5. mapBackground and mapBackgroundWide are optional (recipe D). Without them the chapter uses the default backgrounds. Delete the lines you do not use (and the comma before them).
  6. 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.
  7. Save, reload the game and open the map: the new chapter appears after the previous one and opens when the previous chapter is finished.
Check the file. A missing comma or quote stops the game on the first screen. Paste the text into any free online JSON validator to find the mistake, or run npm test in source/: it reads the file and checks that every listed picture exists.

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

7. Recipe D: change the backgrounds

  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. Mascot: the crab with the sandcastle on the title screen is assets/art/title-hero.webp (about 900×673), the crab of the win panel is crab-cheer.webp and the crab that looks over the settings and pause panels is crab-peek.webp. Replace them keeping the names and similar proportions.
  3. Name in the browser tab: open index.html and change the text inside <title>. The same file has the logo description in alt="Sandy Puzzle".
  4. The line under the logo is the key tagline (recipe F).
  5. 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.
  6. 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), bigWindow (the "Big picture!" notice), 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

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

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

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
  1. Upload everything inside game/ (or source/dist/, if you built it) to your web hosting, replacing the old files.
  2. 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

15. Names you will meet in the files

A few names inside index.html, style.css and the code are short technical names. You do not need them for the recipes above; this table is for people who read the code.

Name Where What it is on screen
book, .book assets/levels.json, home screen, chapter-finished panel The chapter scene that gains colour.
.flags home screen The row of shells, one per level.
.windows, .win level map The grid of level cards and each card (postcard, shuffled picture or closed shell).
bigWindow texts The "Big picture!" notice of the 5th and 10th level of a chapter.
.plate every screen The wooden sign behind counters and the level name.
.mat, .pin title screen, level map Two spare ornaments that are switched off in style.css.
shards, SPRAY src/board.js, src/main.js The little shells and drops that fly when pieces join and on the win panel.
snip() src/sound.js The short sound of the "Tap to start" button.