Customization Guide

Make Gemburrow your own game: a new character, new backgrounds and gems, your own logo, texts, music and sounds, and easier or harder levels. 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 that can export WebP with a transparent background: Photopea (in the browser), GIMP or Krita. You can also draw in any program, save as PNG and convert the PNG to WebP at squoosh.app.
• For music and sounds: Audacity (exports MP3).

Which folder to edit. The download has two copies of the game:

• game/ is the finished game. Simplest way: change files directly inside game/ and upload that folder. No other tools are needed.
• source/ is the same game with tests and a local server. If you use it, edit source/ and run npm run build: it copies the game to source/dist/, and that folder is what you upload. Pick one way and keep to it.

The paths in this guide (for example assets/art/logo.webp) are the same inside both folders.

See your changes on your computer. The game must be opened from a web address, not by double-clicking index.html. Two easy ways:

• With Python (python.org): open a terminal in the game folder, run the command below and open http://localhost:8080.
• With Node.js: in source/, run npm run serve and open http://localhost:5345. It shows source/; npm run serve -- dist shows the built source/dist/ instead.

python -m http.server 8080

After each change, reload the page with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac) so the browser does not show the old file.

Saved progress. The game saves stars and settings in the browser under names that start with gemburrow.template.save.v1 (STORAGE_PREFIX in src/config.js). If you put two copies of the game on the same website, give each copy its own prefix so they do not share progress.

2. Where everything is

The numbers on each screenshot match the table below it. Texts are named by their key in src/locales.js (recipe E). All pictures are in assets/art/.

Title screen

1 2 3 4 5

Home screen

1 2 3 4 5 6 7 8 9

Levels screen

1 2 3 4 5 6 7 8 9

A level (level 38, Frost Cavern)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

3. More screens of the game

The windows share the same pieces: the window glass and its light border are drawn by style.css (recipe J), the titles sit on pill-glass-*.webp plates and the buttons are pill-green*, pill-amber*, pill-blue* and pill-teal* pictures (recipe A explains the numbers in these names). Round buttons in windows use round-solid.webp.

4. Recipe A: replace a picture

All pictures are in assets/art/ in WebP format. The game finds each picture by its file name, so a new picture with the same name simply takes its place.

1. Find the file with the screens above or by its name: bg* backgrounds, mole* mole, m* gems, p-* special gems, h-* power-ups, i-* icons, pill-* buttons and plates, b* trackside pieces, water* track bed textures, t* level buttons, badge* and deco* world ornaments. Effects: burst, shock, spark, puff1 to puff3, splash1 to splash4.
2. Open the old picture in your image editor and note its width and height.
3. Make your new picture with the same width and height and a transparent background (except the bg* backgrounds and the water* strips). Keep the drawing in the same position inside the picture.
4. Export as WebP with the exact same name, for example star.webp, and replace the old file.
5. Reload the game with Ctrl+F5.

Buttons and plates come in several shapes. They are never stretched out of shape: each button uses the picture made for its proportion. The number at the end of the name is the width divided by the height, times 100. For example pill-green-435.webp is 666 x 153 pixels (4.35 times as wide as tall) and pill-glass-790.webp is 7.9 times as wide as tall. So:

• To recolor or redraw a kind of button, change every file of that color: for the green buttons, pill-green.webp, pill-green-315.webp, pill-green-370.webp, pill-green-435.webp, pill-green-rim-315.webp and pill-green-rim-370.webp. Otherwise some buttons keep the old look.
• Keep each file's exact width and height. To see where a file is used, search style.css for its name.

5. Recipe B: change the logo and the game name

1. Logo: replace assets/art/logo.webp (1100 x 377 pixels, transparent background).
2. Title picture: assets/art/title-hero.webp (900 x 873) is the mole in its bucket with the track, under the logo.
3. Browser tab name: open index.html and change the text between <title> and </title>. A little below, change the name inside alt="Gemburrow" too (screen readers read it).
4. Subtitle under the logo: the words Gem Shooter Puzzle are written directly in index.html, on the line with class="plate sub". They are not translated: every language shows the same words.
5. Tab icon: the line <link rel="icon" href="./assets/art/m2.webp" /> in index.html uses the blue gem. To use your own icon, save it in assets/art/ (for example icon.png) and change the address on that line to ./assets/art/icon.png. Keep it inside assets/: npm run build copies only index.html, style.css, src/ and assets/.
6. Browser bar color on phones: the line theme-color in index.html.

6. Recipe C: change the mole

The mole in the bucket is drawn from above, and each world has its own set of eight pictures (here for world 1; world 2 uses mole2*.webp, and so on up to mole5*.webp):

• All eight are 800 x 800 pixels: the bucket is a circle with a radius of 150 pixels in the middle, and the launcher points to the right. The game turns the picture to aim. Keep the bucket and the launcher in the same place in every pose.
• The game knows where the mouth of the launcher is in each world: tip in src/launcher-art.js, the distance from the middle of the bucket to the gem in the launcher, in bucket radii (1.327 means 1.327 x 150 = 199 pixels). If your launcher is longer or shorter, change that number for the world.
• The other mole pictures: mole-wave.webp (home), mole-face.webp (tips and the tutorial), mole-cheer.webp (level complete), mole-dizzy.webp (level lost), mole-nap.webp (pause), mole-journey.webp (Journey Complete), title-hero.webp and dive.webp (title screen).

7. Recipe D: change the backgrounds and the worlds

There are 5 worlds of 10 levels. Each world has its own pictures:

World names are the keys w1 to w5 in src/locales.js (recipe E). The file names stay the same even if your world has another theme; players never see them.

Each background comes in five shapes, so it is never cut badly on any screen. The game picks the file that matches the shape of the screen. For world 1:

1. Replace all five files of a world, each with the same width and height. If you change only one, the old background still shows on other screens.
2. Keep the middle calm, without strong details: the track and the buttons are drawn there. Put the details near the corners.
3. The title screen always uses the world 1 background. The home and levels screens use the world of the next level (or the world chosen on the levels screen).

The rail track of each world is drawn by the game:

• water1.webp to water5.webp (1200 x 166) are the texture strips of the track bed (gravel and wooden sleepers), laid along the track. The left and right ends must join without a seam. The name water comes from the engine and is kept in the code.
• b11.webp to b16.webp (world 1) up to b51.webp to b56.webp are the small pieces beside the track: rocks, ore, crystals, mushrooms, snow, gold and so on.
• The specks that drift over the screen in each world (glow.webp, spark.webp, snow.webp) are the list ambient in FEEL, in src/config.js.
• The engine can also carry small pieces along the track (fl11.webp to fl52.webp, leaf.webp, petal.webp). This game does not use them: the list is left empty in floatInit, in src/game.js. The files are still loaded, so keep them in place.
• The colors of the rails and the track bed (rim, shallow, band, deep, shine) are in WORLDS in src/config.js, one line per world.

8. Recipe E: change texts and translations

All texts players read are in two files: src/locales.js (English, Portuguese, Spanish) and src/locales-more.js (French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean, Chinese). Each language is a block of lines like these:

  tapToStart: 'Tap to start',
  play: 'Play',
  level: 'Level {n}',
  w1: 'Copper Tunnel',

1. Find the text you want to change (Ctrl+F in your editor). The word before the colon is the key; never change it.
2. Change only the words inside the quotes. If your text has an apostrophe, like Let's, put double quotes around the text: "Let's go!".
3. Keep markers such as {n} and {name}: the game puts a number or a name there.
4. Change the same key in the other languages you use. A key missing from a language shows the English text.
5. If you use source/, run npm test: it checks that the 14 languages still have every key and every marker.

Two texts are not in these files: the subtitle under the logo and the browser tab name (recipe B).

9. Recipe F: change the gems

There are six gem colors. Each color has one gem picture, used on the track, and one gem setting picture, used for the level buttons of the levels screen. Each gem also has its own cut (the shape in the middle), so players who cannot tell the colors apart can still tell the gems apart: keep that idea in your own pieces.

• Keep them round, the same size as the old pictures (gems about 128 x 128 pixels, level buttons 198 x 200), with a transparent background.
• m-wild.webp is the rainbow gem (recipe I) and m-lock.webp the locked level.
• MARBLE and MARBLE_DARK in src/config.js are the same six colors, in the same order, for the sparks, the flying points and the plain pieces the game draws if a picture is missing (in the code the gems are called marbles). If you change a gem's color, change its line there too.
• Special gems are an icon drawn over a normal gem: p-bomb.webp, p-slow.webp, p-rev.webp and p-bolt.webp. Frozen gems get the shell ice.webp.

10. Recipe G: make the levels easier or harder

The 50 levels are not drawn by hand. Each one is a line of a table in src/levels.js, and the game builds the track for the screen it is playing on. The table is called PLAN: one block per world, one line per level. These are the last lines of world 2:

    ['spiral', { bomb: 2 }, 1],
    ['bean', { slow: 1, bomb: 1 }],
    ['spiral', { slow: 1, bomb: 2 }, 2],

• Colors per level: COLORS, one line per world: the number of colors for levels 1 to 5 and for levels 6 to 10 of that world (3 to 6). Fewer colors is easier.
• Length, speed and how mixed the colors are rise smoothly from level 1 to 50. They are the lines of getLevel(n) in the same file: count (how many gems), speed (how fast the line rolls, from 0.36 to 0.8), rollTo (how far the line rushes in at the start) and clump (from 0.56 to 0.24: lower values mix the colors more). To make every level slower, lower the two numbers in lerp(0.36, 0.8, t), for example to lerp(0.3, 0.6, t).
• Stars: finishing a level gives 1 star. 2 and 3 stars need points: star2 and star3 in RULES_UI, in src/config.js. Lower numbers give stars more easily.
• Special gems and the danger zone: RULES at the top of src/chain.js: slowS (seconds the snail slows the line, 8), slowMul (how slow, 0.4), revS (seconds the line rolls back, 3), bombReach (blast size, 3.5 gems), freezeS (seconds of the freeze power-up, 6), dangerFrom (0.85: the last 15% of the track, where the line slows down).
• After changing levels, open a terminal in source/ and run npm test. It builds the track of all 50 levels on seven screen sizes and fails if one cannot be built (for example, a line too long for its shape). The eight shape is made for about 47 to 55 gems. The test also checks that level 50 stays much harder than level 2: more than twice the gems, more than 1.8 times the speed and more colors. A flatter curve (for example the same number of colors in every world) makes that check fail.

npm test

This command needs Node.js; the main buyer guide explains how to install it, step by step.

11. Recipe H: replace music and sounds

Save your audio as MP3 with the same file name and replace the old file.

• Music (assets/music/): menu.mp3 plays on the home and levels screens and play.mp3 in the levels. The title screen is silent. Each track repeats: 2.5 seconds before the end, the next round starts and the two blend, so let your track fade out softly over its last 2 or 3 seconds. The blend time is MUSIC_TAIL at the top of src/audio/sound.js.
• Recorded sounds (assets/sfx/): plop1.mp3 to plop5.mp3, the pop of the gems. The game plays a different one each time. Their volume is GAIN at the top of src/audio/sound.js (0.55; 1 is full volume).
• All the other sounds are not files: the game makes them with the numbers in SYNTH, in the same file (f is the pitch in Hz, dur the length in seconds, g the volume).

• To remove the music or the pops, delete the files: the game keeps working, silent where a file is missing (without the pop files it uses its own pop sound).
• Players set the Music and Sound effects volumes in Settings; the starting values are VOL in src/config.js. On phones, sound starts after the first touch (a browser rule).

12. Recipe I: change the power-ups and the special gems

The four power-ups are on the side of the level (pictures h-freeze, h-rocket, h-hammer, h-rainbow; names: keys hFreeze, hRocket, hHammer, hRainbow). Their numbers are in RULES_UI, in src/config.js:

  startHelps: 3,
  rockets: 5,
  hammerReach: 2.3,

• startHelps: how many of each power-up a new player has (3). The first time a level is finished with 3 stars, the player gets one more power-up, in turn.
• rockets: how many gems the rockets hit (5). hammerReach: the size of the hammer blow, in gems (2.3). The hammer shows the key hammerHint.
• Freeze stops every line for freezeS seconds (in RULES, src/chain.js). The rainbow gem (m-wild.webp) matches any color.
• Special gems work when they pop: the bomb clears the gems near it, the snail slows the line, rewind rolls the line back and lightning clears every gem of its color. Their numbers are in recipe G; their pictures in recipe F.
• The words that pop up during play are keys too: nice, amazing, gap, freeze, slow, rev.

Change only the numbers. Keep the commas, braces and names exactly where they are. Power-ups are earned by playing; the game has no store and no real-money purchases.

13. Recipe J: change colors, buttons and the font

• Text colors: the block :root near the top of style.css: --ink (the white text), --shade (the soft shadow under it) and --rim (the light border of the windows). Change the value after the colon, for example --ink: #fff;.
• Window glass: the rule .panel with linear-gradient(...) near the end of style.css; the home card is the rule .card a little further down. The two colors are the top and the bottom of the glass.
• Behind the game while it loads: the background of html, body near the top of style.css. Browser bar color on phones: theme-color in index.html.
• Buttons, plates and round buttons are pictures: recolor them in your image editor (Hue/Saturation) and save with the same names, every size of a color (recipe A).
• Track and gem colors: WORLDS and MARBLE in src/config.js (recipes D and F).
• 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 in those blocks (and in the preload line of index.html). Check that its license allows use in games.

14. 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 levels 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.

15. If something goes wrong

• The game stops on the first screen after you edit a .js file: a comma, quote or brace is missing. Press F12 and open the Console: it shows the file name and the line with the error. Compare that line with your backup.
• A picture is missing: the file name is different (names are case sensitive: Logo.webp is not logo.webp), or the file is not WebP.
• A background or button still shows the old picture on some screens: it has other files for other screen shapes (recipes A and D).
• 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).