Capyroll · Customization Guide · version 1.0.0 · Main buyer guide

Customization Guide

Make Capyroll your own game: a new character, new backgrounds and marbles, 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 capyroll.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 "Marble 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 capybara, tub, marbles and track are one picture. When the player taps the button, the capybara dives: 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. Glass plate: pill-glass-*.webp. Up to 3 stars per level, 150 in all.
2 Settings button Icon: assets/art/i-gear.webp. Round glass: round-glass.webp.
3 World card Texts: keys world ("World 2") and w2 ("Sunny Shore"). 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 water water2.webp, the bank pieces b21.webp to b26.webp, the marbles and the capybara (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 capybara assets/art/capy-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. Glass 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 Marble: m0.webp to m5.webp, in turn. Stars: star.webp and star-off.webp.
7 Next level Always the green marble m3.webp, with the play icon i-play.webp.
8 Locked level Stone ball: assets/art/m-lock.webp; lock: i-lock.webp.
9 River of the levels Drawn by the game with the water water2.webp and the bank pieces b21.webp to b26.webp (shells in this world). Each world uses its own (recipe D).

A level (level 38, Frost Lake)

A level (level 38, Frost Lake), 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 Marble Six colors, three pictures each: m0.webp, m0-core.webp and m0-gloss.webp for red, up to m5 for orange (recipe F).
6 Special marble (bomb) An icon drawn over a normal marble: 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 marble The ice shell drawn over the marble: assets/art/ice.webp. How many per level: recipe G.
8 Water pipe Where the marbles come in: assets/art/spout.webp.
9 Tunnel Stone covers drawn one after another: assets/art/slab.webp. The marbles roll under them. Where tunnels are: recipe G.
10 Whirlpool assets/art/drain.webp. If the first marble reaches it, the level is lost.
11 River banks One set of six pieces per world, here b41.webp to b46.webp. The painted water is water4.webp; the river colors are in src/config.js (recipes D and J).
12 Capybara in the tub assets/art/capy4.webp and its seven poses: one set per world (recipe C).
13 Next marble Basket: assets/art/basket.webp. Tapping the capybara swaps the two marbles.
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: Frost Lake, world 4, on a wide screen (recipe D).

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.

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 capybara is capy-nap.webp.
Guided first level, real screenshot
Level 1 explains the game: keys tut1, tut2 (tut2pc on computers), tut3 and skip. Face: capy-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. Capybara: capy-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. Capybara: capy-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, capy-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 (Maple Woods) on a phone: the track crosses itself under bridge.webp; the floating leaves are fl31.webp, fl32.webp, maple-o.webp and maple-r.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, capy* capybara, m* marbles, p-* special marbles, h-* power-ups, i-* icons, pill-* buttons and plates, b* river banks, water* painted water, 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 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 capybara in the tub 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="Capyroll" too (screen readers read it).
  4. Subtitle under the logo: the words Marble 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 marble. 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 capybara

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

Picture When it shows
capy1.webp normal, waiting
capy1-aim.webp while the finger or mouse button is held down to aim
capy1-recoil.webp just after a shot
capy1-cheer.webp after a big chain and when the level is won
capy1-scared.webp when the marbles are close to the whirlpool and when the level is lost
capy1-ear.webp a quick ear twitch while waiting
capy1-yawn.webp sometimes, a yawn after 7 seconds without a shot
capy1-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 Yuzu Springs (key w1) 1 to 10 bg1-*.webp (5 files), badge1.webp, deco1.webp, water1.webp, b11.webp to b16.webp, capy1*.webp (8 files)
2 Sunny Shore (key w2) 11 to 20 bg2-*.webp (5 files), badge2.webp, deco2.webp, water2.webp, b21.webp to b26.webp, capy2*.webp (8 files)
3 Maple Woods (key w3) 21 to 30 bg3-*.webp (5 files), badge3.webp, deco3.webp, water3.webp, b31.webp to b36.webp, capy3*.webp (8 files)
4 Frost Lake (key w4) 31 to 40 bg4-*.webp (5 files), badge4.webp, deco4.webp, water4.webp, b41.webp to b46.webp, capy4*.webp (8 files)
5 Moonlit Garden (key w5) 41 to 50 bg5-*.webp (5 files), badge5.webp, deco5.webp, water5.webp, b51.webp to b56.webp, capy5*.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 river 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: 'Yuzu Springs',
  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 marbles

There are six marble colors. Each color has three pictures: the whole marble, the inside that turns as it rolls (-core) and the shine that stays still on top (-gloss). The track uses -core and -gloss; the whole marble is used on the levels screen, around the stars and when the other two are missing. Replace all three, or the track keeps the old marble.

# Color Pictures
0 red m0.webp, m0-core.webp, m0-gloss.webp
1 yellow m1.webp, m1-core.webp, m1-gloss.webp
2 blue m2.webp, m2-core.webp, m2-gloss.webp
3 green m3.webp, m3-core.webp, m3-gloss.webp
4 purple m4.webp, m4-core.webp, m4-gloss.webp
5 orange m5.webp, m5-core.webp, m5-gloss.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 marbles). On wide screens a zigzag is played as a bean.
2nd: special marbles 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 marbles How many marbles 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 marbles are swapped
clink a marble joins the line
clack two parts of the line bump together
bomb, slow, rev, bolt a special marble pops
freeze, rocket, hammer, wild a power-up is used
thaw ice breaks
heart, phew marbles near the whirlpool, 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 water sounds

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

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