Ghostpaw · Customization Guide · version 1.0.0 · Main buyer guide

Customization Guide

Make Ghostpaw your own game: a new character, new backgrounds and potions, 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:

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

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

Make a backup first. Copy the whole folder (or keep the ZIP you downloaded) before changing anything. If something breaks, you can always go back.

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

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.

On your own computer (addresses that start with localhost or 127.0.0.1) a few shortcuts help you check your work. Add them to the address, for example http://localhost:8080/?level=38&unlock: The other shortcuts do nothing on a published site.

Saved progress. The game saves stars and settings in the browser under names that start with ghostpaw.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

Title screen, real screenshot with numbered parts 1 2 3 4 5
# What you see File to change
1 Logo assets/art/logo.webp (recipe B). The logo appears only on this screen.
2 Subtitle The words "Potion Shooter Puzzle" are written in index.html (recipe B). Plate picture: assets/art/pill-glass-790.webp.
3 Title picture assets/art/title-hero.webp: the kitten, cauldron, potions, carpet and coffin are one picture. When the player taps the button, the kitten dives into the cauldron: dive.webp.
4 Tap to start button Text: key tapToStart in src/locales.js (recipe E). Button picture: assets/art/pill-green-rim-370.webp.
5 Background The title always shows the world 1 background: assets/art/bg1-land.webp on this wide screen (recipe D).

Home screen

Home screen, real screenshot with numbered parts 1 2 3 4 5 6 7 8 9
# What you see File to change
1 Stars earned Star: assets/art/star.webp. Plate: pill-glass-*.webp. Up to 3 stars per level, 150 in all.
2 Settings button Icon: assets/art/i-gear.webp. Round button: round-glass.webp.
3 World card Texts: keys world ("World 2") and w2 ("Haunted Library"). Card color: the .card rules in style.css (recipe J).
4 World progress Levels finished in this world, out of 10. Drawn by style.css, no picture.
5 Track preview Drawn by the game from the pieces of the world: the carpet water2.webp, the floor ornaments b21.webp to b26.webp, the potions and the kitten (recipes C, D and F).
6 Play button Texts: keys play and level. Button picture: assets/art/pill-green-rim-315.webp.
7 Levels button Text: key levels. Icon: i-grid.webp. Button picture: pill-teal-390.webp.
8 Waving kitten assets/art/cat-wave.webp (recipe C).
9 World background One set per world. Here assets/art/bg2-land.webp: the home screen shows the world of the next level to play (recipe D).

Levels screen

Levels screen, real screenshot with numbered parts 1 2 3 4 5 6 7 8 9
# What you see File to change
1 Back button Icon: assets/art/i-back.webp.
2 Screen title Text: key levels. Plate: pill-glass-*.webp.
3 Stars earned Star: assets/art/star.webp. Plate: pill-glass-*.webp. Up to 3 stars per level, 150 in all.
4 World badges assets/art/badge1.webp to badge5.webp, one per world. Lock: i-lock.webp.
5 World name Texts: keys world and w1 to w5. The ornaments on both sides: deco1.webp to deco5.webp, one per world.
6 Finished level Potion flask: t0.webp to t5.webp, in turn; the number is text. Stars: star.webp and star-off.webp.
7 Next level Always the green flask t3.webp, with the play icon i-play.webp.
8 Locked level Stone ball: assets/art/m-lock.webp; lock: i-lock.webp.
9 Carpet of the levels Drawn by the game with the carpet water2.webp and the floor ornaments b21.webp to b26.webp (books and scrolls in this world). Each world uses its own (recipe D).

A level (level 38, Frozen Crypt)

A level (level 38, Frozen Crypt), real screenshot with numbered parts 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
# What you see File to change
1 Level number Text: key level. Plate: pill-glass-*.webp.
2 Score and star bar Stars: star.webp and star-off.webp. The points needed for each star: recipe G.
3 World of this level Texts: keys world and w4. On level 1 it shows the key tutorial.
4 Pause button Icon: assets/art/i-gear.webp. It opens the pause window.
5 Potion Six colors, one picture each: m0.webp for red up to m5.webp for orange, each with its own symbol (recipe F).
6 Special potion (bomb) An icon drawn over a normal potion: assets/art/p-bomb.webp. The others are p-bomb, p-slow (snail), p-rev (rewind) and p-bolt (lightning). Recipes F and I.
7 Frozen potion The ice crust drawn over the potion: assets/art/ice.webp. How many per level: recipe G.
8 Stone gate Where the potions come in: assets/art/spout.webp.
9 Tunnel Roof pieces drawn one after another: assets/art/slab.webp. The potions roll under them. Where tunnels are: recipe G.
10 Coffin assets/art/drain.webp; when the potions get close it wakes up: drain-awake.webp. If the first potion reaches it, the level is lost.
11 Floor ornaments One set of six pieces per world, here b41.webp to b46.webp. The carpet is water4.webp; the colors of its border are in src/config.js (recipes D and J).
12 Kitten in the cauldron assets/art/cat4.webp and its seven poses: one set per world (recipe C).
13 Next potion Silver saucer: assets/art/basket.webp. Tapping the kitten swaps the two potions.
14 Power-ups Pictures: h-freeze.webp, h-rocket.webp, h-hammer.webp, h-rainbow.webp. Names: keys hFreeze, hRocket, hHammer, hRainbow. Recipe I.
15 World background assets/art/bg4-land.webp here: Frozen Crypt, world 4, on a wide screen (recipe D).

The windows share the same pieces: the window panel 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.

Settings window, real screenshot
Settings, opened from the home screen: music and effects volume, vibration, less motion, language, full screen and the tutorial. Icons: i-music, i-sfx, i-vib, i-motion, i-lang, i-full, i-help.
Pause window, real screenshot
Pause: keys paused, resume, restart, home. Icons i-play, i-replay, i-home; the sleeping kitten is cat-nap.webp.
Guided first level, real screenshot
Level 1 explains the game: keys tut1, tut2 (tut2pc on computers), tut3 and skip. Face: cat-face.webp; pointing hand: hand.webp. The first time a new piece appears, the same bubble shows one of the keys tipTunnel, tipBridge, tipDuo, tipIce, tipBomb, tipSlow, tipRev, tipBolt.
Level complete window, real screenshot
Level complete: keys levelComplete, score, bestChain, next. Kitten: cat-cheer.webp; stars star.webp; score plate pill-teal-360.webp; a new best score shows stamp-green.webp with the key newRecord.
Level lost window, real screenshot
Level lost: the title is the key oops, or soClose when at least 30% of the line was cleared. Also cleared and tryAgain. Kitten: cat-dizzy.webp; icons i-grid and i-home.
Journey Complete window, real screenshot
After level 50: keys journey, totalScore, collect3 (shown while some level has fewer than 3 stars) and menu. Pictures: badge1 to badge5, i-check, cat-journey.webp.
Home screen on a phone held upright, real screenshot
A phone held upright: the home screen uses bg2-port.webp.
A level on a phone held upright, real screenshot
Level 27 (Pumpkin Kitchen) on a phone: the carpet crosses itself under the stone bridge bridge.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, cat* kitten, m* potions, p-* special potions, h-* power-ups, i-* icons, pill-* buttons and plates, t* level flasks, b* floor ornaments, water* carpet, badge* and deco* world ornaments, drain* coffin. 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 609 x 140 pixels (4.35 times as wide as tall) and pill-glass-790.webp is 7.9 times as wide as tall. So:

Tip: if your new picture looks too big, too small or cut, its size is different from the old one. Make it exactly the same width and height.
  1. Logo: replace assets/art/logo.webp (1100 x 329 pixels, transparent background).
  2. Title picture: assets/art/title-hero.webp (900 x 894) is the kitten in the cauldron next to 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="Ghostpaw" too (screen readers read it).
  4. Subtitle under the logo: the words Potion 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 potion. 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 kitten

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

Picture When it shows
cat1.webp normal, waiting
cat1-aim.webp while the finger or mouse button is held down to aim
cat1-recoil.webp just after a shot
cat1-cheer.webp after a big chain and when the level is won
cat1-scared.webp when the potions are close to the coffin and when the level is lost
cat1-ear.webp a quick ear twitch while waiting
cat1-yawn.webp sometimes, a yawn after 7 seconds without a shot
cat1-peek.webp when the mouse moves (computers)

7. Recipe D: change the backgrounds and the worlds

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

# World Levels Its pictures
1 Great Hall (key w1) 1 to 10 bg1-*.webp (5 files), badge1.webp, deco1.webp, water1.webp, b11.webp to b16.webp, cat1*.webp (8 files)
2 Haunted Library (key w2) 11 to 20 bg2-*.webp (5 files), badge2.webp, deco2.webp, water2.webp, b21.webp to b26.webp, cat2*.webp (8 files)
3 Pumpkin Kitchen (key w3) 21 to 30 bg3-*.webp (5 files), badge3.webp, deco3.webp, water3.webp, b31.webp to b36.webp, cat3*.webp (8 files)
4 Frozen Crypt (key w4) 31 to 40 bg4-*.webp (5 files), badge4.webp, deco4.webp, water4.webp, b41.webp to b46.webp, cat4*.webp (8 files)
5 Moonlit Tower (key w5) 41 to 50 bg5-*.webp (5 files), badge5.webp, deco5.webp, water5.webp, b51.webp to b56.webp, cat5*.webp (8 files)

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:

File Size (pixels) Used on
bg1-land.webp 1600 x 900 Wide screens: computers and phones turned sideways
bg1-port.webp 900 x 1600 Phones held upright
bg1-l43.webp 1280 x 960 Tablets turned sideways (about 4:3)
bg1-p34.webp 960 x 1280 Tablets held upright (about 3:4)
bg1-sq.webp 1280 x 1280 Almost square windows
  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 carpet of each world is drawn by the game:

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: 'Great Hall',
  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 potions

There are six potion colors, one picture each. Every color also has its own symbol, so players who do not tell colors apart can still play; keep a different symbol on each one. The potions do not turn as they roll, so the symbol always stays upright.

# Color Symbol Picture
0 red star m0.webp
1 yellow crescent moon m1.webp
2 blue drop m2.webp
3 green leaf m3.webp
4 purple spiral m4.webp
5 orange flame m5.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],
Part of the line What it means
1st: the track shape 'oval', 'spiral', 'bean', 'serp' (zigzag), 'eight' (the track crosses itself over a bridge) or 'duo' (two tracks, two lines of potions). On wide screens a zigzag is played as a bean.
2nd: special potions How many of each: bomb, slow (snail), rev (rewind), bolt (lightning). {} or nothing means none.
3rd: tunnels 0 or nothing: none; 1: one short tunnel; 2: two tunnels. Where they are: TUNNELS, as parts of the track (0.42 is 42% of the way).
4th: frozen potions How many potions start frozen.
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.

Name in SYNTH When it plays
shot a shot
swap the two potions are swapped
clink a potion joins the line
clack two parts of the line bump together
bomb, slow, rev, bolt a special potion pops
freeze, rocket, hammer, wild a power-up is used
thaw ice breaks
heart, phew potions near the coffin, and safe again
win, star, cheer level won, each star, a big chain
lose, sink level lost
ui_click, ui_back, ui_no, stamp buttons and the "New record!" stamp
splash, fill splash and filling sounds: the dive on the title screen and the start of a level

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

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,

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

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

15. If something goes wrong