Scarab Sands — customization guide

How to use this guide

Step-by-step recipes for people who do not program. Every part of the screen has a number on the real screenshots below and the exact file that controls it. Work in the source/ folder of the download, then run npm run build (or copy the changed files) and upload. You can also edit the files inside game/ directly: they are the same files.

1. Make a backup: copy the whole extracted folder (or keep the original ZIP) before you change anything.
2. Open the source/ folder in your editor (VS Code: File > Open Folder).
3. Change a picture, a sound or a text using the recipes below.
4. See the result on your computer: in source/, run npm run dev and open http://localhost:5190/ (the game does not run from a double-clicked index.html). Without Node.js you can use the free "Live Server" extension of VS Code. Press Ctrl+F5 after each change.
5. Publish: run npm run build and upload the contents of dist/ (or upload only the files you changed, at the same paths, into your game folder on the host).

Free tools

Which file controls each part of the screen

Texts are in src/locales/<language>.js (shown here for English, src/locales/en.js). Pictures are WebP files in assets/art/; replace them keeping the same name and size.

Main menu

12345678

A level (desktop layout)

123456789

Victory card

1234567

Defeat card

1234

Shop (skins and cannon upgrades)

123

Settings

12345

Level map

123

Main pictures

Sounds and music

Every sound the game plays is listed in assets/audio-manifest.json. Replace a file keeping its name; the description says what the original sounds like.

Recipes, step by step

Change a picture (blocks, bosses, buttons, backgrounds)

1. Find the picture in the tables above or open assets/art/ and look at the thumbnails.
2. Make a copy of the original first (for example crate-original.webp, outside the game folder).
3. Open it in Photopea (free, in the browser) or GIMP and draw over it, or prepare your own picture with the same width and height and a transparent background.
4. Export as WebP with the same file name (Photopea: File > Export as > WEBP; or export PNG and convert it with Squoosh).
5. Replace the file in source/assets/art/ (and in game/assets/art/ if you upload directly), then reload with Ctrl+F5.

Change the mascot (the kitten)

1. Replace the five assets/art/parrot*.webp pictures keeping their sizes (each pose has its own file: happy, sad, cheer, scared, perched).
2. The game also has a narrator that cheers the player ("Great pharaohs!", "Try again, explorer!"): the narration files are in assets/voice/en/, assets/voice/pt/ and assets/voice/es/ (one MP3 per line; what each line says is listed in assets/audio-manifest.json). Replace them keeping the names, or set the narration volume to 0 by default in src/main.js.
3. The kitten has no sound effect of its own: the cheering lines are the narration above.
4. Change the app icon too: replace assets/icons/*.png and favicon.ico (the current ones are the game's own icon: the pharaoh kitten holding a turquoise orb in front of the pyramids).

Change a block

1. Pictures: assets/art/crate.webp (low hit points), assets/art/barrel.webp, assets/art/chest.webp and their -d1 / -d2 cracked versions; assets/art/keg.webp for the fire urn.
2. Which picture a block uses (and the tint per chapter) is chosen in src/render/sprites.js and src/render/palette.js.
3. The hit sounds are hit_glass, hit_heavy, break_glass and break_heavy in assets/sfx/.

Change a boss

1. Pictures: assets/art/kraken.webp (chapter 1, the Giant Scarab) and assets/art/boss2.webp ... assets/art/boss10.webp, each with a -hurt version.
2. Name: the texts boss1 ... boss10 in src/locales/en.js (and in the other languages).
3. Health and escort: bossHp, ESCORT and RAGE in src/modes.js; run node tools/check-modes.mjs after changing them.
4. Boss music: assets/music/cove-kraken.mp3; roar and hit sounds: boss_roar, boss_hit in assets/sfx/.

Change a sound effect

1. Open assets/audio-manifest.json: under sfx each sound has a name, its file in assets/sfx/ and a short description.
2. Edit or record the new sound in Audacity (free), keep it short (most effects are under 1 second) and export as MP3.
3. Replace the file keeping the same name. No code change is needed.

Change the music

1. The four tracks are assets/music/cove-menu.mp3 (menus), assets/music/cove-game-a.mp3 and assets/music/cove-game-b.mp3 (levels, alternating) and assets/music/cove-kraken.mp3 (bosses and the last level).
2. Replace them with MP3 files of the same names; loops sound best when the end flows into the start.
3. If the new track has a different length, update its dur (seconds) in the music list of assets/audio-manifest.json.

Change a text or a translation

1. Open src/locales/en.js (English) in VS Code or Notepad++. Each line is key: 'text'.
2. Change only the text between the quotes. Keep {n} and similar markers. Save as UTF-8.
3. Do the same in the other languages (src/locales/pt.js, src/locales/es.js ...). A key missing in a language shows the English text.
4. The page title and description are in index.html (<title>, <meta name="description">) and manifest.webmanifest.

Change colours

1. Interface colours are CSS variables at the top of style.css and scarab.css (for example --gold, --cream, --brown, --amber, --danger). Change the hex value, save, reload.
2. The arena colours of each chapter (background, glow, rails) are the THEMES in src/render/palette.js; block tints and stone orb skins are in the same file.
3. Most of the look comes from the pictures: to change the sandstone or papyrus, edit assets/art/wood.webp (sandstone texture), assets/art/panel-tall.webp, assets/art/card-parchment.webp and the button plates.

Change the font

1. Put the new font file (WOFF2) in assets/fonts/ together with its licence.
2. Change the @font-face rule at the top of scarab.css (titles, Fraunces) or style.css (numbers, Chakra Petch) and the --font variable.
3. The canvas texts use FONT in src/render/view-shared.js: put the same family name first.

Make the game easier or harder

1. Stone orbs per volley: BALLS in src/sim/config.js (10).
2. Stars: par of each level in src/levels.js (volleys allowed for 3 stars).
3. Block health: the numbers in the level maps of src/levels.js; boss health: bossHp in src/modes.js.
4. After changing levels, run node tools/validate.mjs --solve <n> (see "Editing levels" in the main guide) and npm test.

Change prices and rewards

1. All of them are at the bottom of src/modes.js: START_COINS, RESCUE_COST, winCoins, BOSS_COINS, DAILY_COINS, STAR_MILESTONES, UPGRADES (prices per level), MISSIONS (goals and rewards), skinPrice.
2. Stars needed for each skin: stars in SKINS of src/render/palette.js.
3. Run npm test afterwards.

Turn ads, the "Tap to start" screen or the full-screen button on and off

1. Open scarab-sands.config.js, change provider, tapToStart or fullscreen as explained in its comments, save and reload. See "Settings file and optional ads" in the main guide.

Publish your changes

1. In source/, run npm test (if you changed code, levels or prices) and npm run build.
2. Upload the contents of dist/ to your game folder on the host (FileZilla or the host file manager), replacing the old files. Keep the same web address so players keep their progress.
3. Open the game in a private window or press Ctrl+F5 (Cmd+Shift+R on a Mac): browsers and CDNs keep old files for a while. Do not clear "site data", it deletes the save.
4. If something breaks, put back the file from your backup and compare.

Internal names in the code

Some code names come from the first version of the engine. The player never sees them: all visible names come from src/locales/.

Help

Main guide: documentation/index.html (installation, settings, levels, economy, languages, troubleshooting). Questions and custom work: willian@polargames.com.br.