Customization Guide

Make Dragon Roost your own game: new dragons, new enemies, your own logo, sounds, texts and colors, an easier or harder campaign and other prices. Every recipe below is a short list of steps and names the exact file to open. You do not need to know how to program. Every picture on this page is a real screenshot of the game in this download.

1. Before you start

Free tools:

• 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 exports WebP and PNG: Photopea (free, in the browser), GIMP or Krita. You can also save a PNG and convert it to WebP at squoosh.app.
• For sounds: Audacity (free, 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 tools. If you use it, edit source/ and run npm run build, then upload the new source/dist/ folder (see Check and publish). Pick one way and keep to it.

The paths in this guide (for example assets/ui/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 inside the game folder, run the command below and open http://localhost:8080.
• With Node.js 26.13 or newer: in source/, run npm run serve and open http://localhost:5191.

python -m http.server 8080

After each change, reload with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac) so the browser does not show the old file. On your own computer you can add ?debug=1 to the address (for example http://localhost:8080/?debug=1) to open a testing panel with extra coins, "win this wave" and "go to wave" buttons. The panel never appears on a public website.

2. Screenshot gallery

Real screenshots of this version: 1280 x 720 on a computer, plus a phone in both positions. The game is played in landscape; on a phone held upright it shows a "turn your phone" screen.

3. Where everything is

The numbers on each screenshot match the table below it. Text keys such as play are explained in recipe F.

Title screen

1 2 3 4

Battle (World 1, Golden Skies)

1 2 3 4 5 6 7 8 9 10

Royal Aerie (dragon levels and upgrades)

1 2 3 4 5 6 7

Wave held (reward card)

1 2 3

Pause menu

1 2 3 4 5 6

The wall fell (defeat)

1 2 3 4

4. Recipe A: replace a picture

All pictures are WebP files (a few PNG) inside assets/. 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 numbered screens or by its name in the folders above.
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 sky backgrounds). Keep the subject in the same place inside the picture.
4. Export as WebP with the exact same name, for example assets/ui/btn-play.webp, and replace the old file.
5. Reload the game with Ctrl+F5.

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

1. Logo: replace assets/ui/logo.webp (1536 x 1024, transparent background). It is used on the title, loading and "turn your phone" screens.
2. Browser tab name and description: open index.html, change the text between <title> and </title>, the content of the description line and the alt texts of the two logo images.
3. Tab icon: replace assets/ui/favicon-dragon.png (a square PNG, for example 64 x 64).
4. Browser bar color on phones: the theme-color line in index.html.
5. Name inside the game: key title in src/i18n/dragon-theme.js (one line per language, recipe F), and the alt text of the logo in src/app/hud.js (search for Dragon Roost).

6. Recipe C: change the dragons

There are 12 dragon levels. Two dragons of the same level merge into the next level. Each level has five pictures:

• assets/plants/p1-0.webp, p1-1.webp, p1-2.webp, p1-3.webp: four small frames, 300 x 300, used in the Royal Aerie cards, the tutorial and the bottom bar. Make all four the same drawing (or a tiny wing movement).
• assets/plants/p1-hd.webp: the same dragon at 600 x 600, drawn in battle so it stays sharp on phones and large screens.

1. Draw your level 1 creature on a transparent 600 x 600 canvas, facing left (the enemies come from the left), standing on the bottom middle.
2. Export it as p1-hd.webp. Resize a copy to 300 x 300 and export it four times as p1-0.webp ... p1-3.webp.
3. Repeat for p2 ... p12, from smallest to strongest.
4. Names: keys p1 ... p12 in src/i18n/dragon-theme.js (Fire Hatchling, Twin Whelp ... Elder Dragon).
5. Where the fire comes out: the mouth and eye points of each level are in src/art/anchors.js, in pixels of the 300 x 300 frame (boca = mouth, olhos = eyes, pupila = pupil). Open your 300 x 300 picture in Photopea, point at the mouth, read the x and y in the Info panel and type them there.
6. Strength: PLANTS at the top of src/game/data.js, one line per level: dmg (damage per hit), rate (shots per second) and range. Keep fire as it is: it chooses the attack animation.

{ lv: 1, key: 'seed', fire: 'single', range: 540, rate: 2.0, dmg: 10 },   // dmg: 12 makes level 1 stronger

7. Recipe D: change the enemies, bosses and backgrounds

• Enemies are picture strips in assets/pests/: aphid.webp (Goblin Balloon), hopper.webp, beetle.webp, snail.webp (and snail_cracked.webp, its broken armor), slug.webp, stinkbug.webp, bombardier.webp and ladybug.webp (the golden treasure balloon). Each strip has 8 frames side by side, each 420 x 330 (3360 x 330 in total). Their order and the point where each enemy "touches" the lane are listed in assets/pests/pests.json. Keep the same size and order and the new strip simply replaces the old one.
• Bosses: rhino.webp (Ram Zeppelin), wasp.webp (Goblin Queen) and megasnail.webp (Shell Fortress), plus one large picture each, rhino-space-hd.png, wasp-space-hd.png and megasnail-space-hd.png, drawn in battle for sharpness. Replace both. Boss names: keys boss_rhino, boss_wasp, boss_megasnail in src/i18n/dragon-theme.js.
• Burners and propellers drawn on top of the balloons are positioned in src/art/anchors.js (queimadores = burners, helices = propellers), in fractions of the frame. If your enemy has no propeller, leave the list empty: helices: [].
• Sky backgrounds: assets/env/bg1.webp (World 1, Golden Skies), bg2.webp (World 2, Storm Canyon), bg3.webp (World 3, Aurora Night), each with a -wide version for wide screens. World names: keys world0, world1, world2.
• Title background: assets/env/title-wide.webp. Castle wall: assets/env/fence.webp. Nest board: assets/env/planter.webp (the 15 nests are measured on it in PLANTER, src/render/scene-art.js; keep the same layout).
• Mascot (the dragon keeper who guides the player): assets/ui/hazel-wave.webp, hazel-point.webp, hazel-cheer.webp, hazel-sit.webp, hazel-worried.webp and the tutorial bust assets/ui/tut-bust.webp.

8. Recipe E: replace sounds, music and narration

Sound effects are short MP3 files in assets/sfx/dragao/. Every effect has two recorded variations (-1.mp3 and -2.mp3) and the game alternates between them. Replace both with your sound, keeping the names.

• Volume of one effect: LEVEL near the top of src/audio.js, for example shot: 0.35 (effects not listed there play at 0.75). The list of files per effect is in src/sfx-selecao.js.
• Music (assets/music/): dragon-menu.mp3 (title and menus), dragon-onda.mp3 (waves) and dragon-chefe.mp3 (boss waves). Loops work best when the end flows into the start.
• Narration (assets/voice/, English): the mascot's short lines, for example wave-1.mp3, boss-1.mp3, newdragon-1.mp3, victory-1.mp3. Replace them with your own recordings, or make a 1-second silent MP3 with the same name to mute a line.
• Players set effects, voice and music volume in the pause menu. On phones, sound starts after the first touch (a browser rule).

9. Recipe F: change texts and translations

All the names of this theme (dragons, powers, bosses, worlds, the Royal Aerie) are in src/i18n/dragon-theme.js, one block per language. Other interface texts are in one file per language: src/i18n/en.js, pt.js, es.js, fr.js, de.js, it.js, nl.js, pl.js, tr.js, ru.js, id.js, ja.js, ko.js and zh.js. When a key exists in both, dragon-theme.js wins.

    plant: 'Recruit',
    bees: 'Wyverns',
    fenceFell: 'The wall fell!',
    p1: 'Fire Hatchling',

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 it: "Let's go".
3. Keep markers such as {n}: the game puts a number there.
4. Change the same key in the other languages you use. A missing translation falls back to English.
5. Short names fit the buttons better: check the bottom bar on a phone after a change.

Remove a language: in src/i18n/i18n.js, delete it from LANGS and LANG_NAMES (and its import line). Add one: copy en.js to a new file, translate it, import it there and add it to both lists.

10. Recipe G: make the campaign easier or harder

Every balance number is in src/game/data.js. Change one number at a time, play a few waves and keep a copy of the old value.

  W([
    ['aphid', 5, 2.4, 'spread', 0],   // wave 1: 5 goblin balloons, one every 2.4 s
    ['aphid', 3, 0.9, 'center', 13],  // then 3 more at 13 s
  ]),

Keep the commas, brackets and quotes exactly where they are. With Node.js, run npm test in source/ after a change: one test plays the campaign with a simple robot player and warns if the game became impossible.

11. Recipe H: change prices and rewards

Prices are in in-game coins only (there are no real-money purchases). All in BAL, src/game/data.js:

  plantPrice: 12,     // change to 10 for cheaper dragons
  priceGrowth: 1.95,

12. Recipe I: change colors and the font

• Text and outline color (dark brown): --ink: #3a2416; at the top of css/game.css. The cream color of light texts is --cream on the next line. The page color behind the game is the background of html, body a few lines below (#7d6bb5).
• Buttons, pills, ribbons and windows are pictures in assets/ui/: btn-gold (Recruit, upgrade prices), btn-green (resume), btn-orange (try again, collect), btn-cream (powers), btn-play, ribbon-win, ribbon-lose, ribbon-pause, panel. Recolor them in your image editor (Image > Adjustments > Hue/Saturation in Photopea) and save with the same names.
• Font: Fredoka (SIL Open Font License), files in assets/fonts/, declared with four @font-face blocks at the top of css/game.css. To use another font, put its .woff2 files in assets/fonts/, change the file names in those blocks and the first name in --font. Choose a font whose license allows use in games (Google Fonts are a good source).
• Screen shake, flashes and particle amounts: src/render/feel.js (smaller numbers = calmer game).

13. Internal names used in the code

The engine is shared with an earlier garden-themed game, so some file and code names are neutral leftovers. Players never see them; the names they see come from src/i18n/dragon-theme.js.

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 phone size (in Chrome or Edge press F12, then Ctrl+Shift+M).
2. If you edited source/: in a terminal inside source/, run the commands below. The first checks the rules, the second writes the finished game to source/dist/.

npm test
npm run build

3. Upload everything inside game/ (or source/dist/) to your web hosting, replacing the old files and keeping the folders.
4. Open your game address and press Ctrl+F5. If you still see the old version, read "Updating and cache" in the main buyer guide.
5. Saved progress belongs to each website address. If you host two copies on the same domain, give each its own save name: SAVE and SETTINGS at the top of src/main.js.

15. If something goes wrong

• Blank or frozen screen after editing a .js file: a comma, quote or bracket 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 or looks broken: the file name is different (names are case sensitive: Logo.webp is not logo.webp), or the file is not really WebP.
• 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).