Customization Guide

Make Starfort your own game: new turrets, new enemies, a new mascot, your own sounds, texts and colors, and an easier or harder campaign. Every recipe is a short list of steps and names the exact 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: tools, backup and testing

Free tools that are enough for everything on this page:

• Text editor: Visual Studio Code (Windows, macOS, Linux) or Notepad++ (Windows). Never use Word or WordPad: they break code files.
• Pictures: Photopea (free, in the browser, opens and exports WebP and PNG), GIMP or Krita. To convert a PNG to WebP: Squoosh (choose "WebP", quality 80 to 90).
• Sounds: Audacity (cut, change volume, export MP3).

Make a backup first. Copy the whole source/ folder to source-backup/. If a change goes wrong, copy the original file back.

Which folder to edit: make your changes in source/. The game/ folder is the ready-to-upload copy of the same files. You can also edit game/ directly if you never plan to use the tools; the file names inside are the same.

See your change on your computer. The game needs a small local web server (opening index.html with a double click does not work, the browser blocks the modules). Pick one:

• With Node.js 26.13 or newer: open a terminal in source/ and run npm ci once, then npm run serve, and open http://localhost:5191/.
• With Visual Studio Code: install the free "Live Server" extension, open the source/ folder and click "Go Live".
• With Python installed: run python -m http.server 8000 inside source/ and open http://localhost:8000/.

2. Screenshot gallery

Every screen of the game, captured from this package. Click a picture to open it full size.

3. Where everything is

The numbers on each screenshot match the table below it, which names the file to change.

Title screen

1 2 3 4

Battle screen

1 2 3 4 5 6 7 8 9 10

Boss wave

1

4. Recipe A: replace any picture

1. Find the picture in assets/ (the tables on this page give the exact file). assets/ui/ holds buttons, icons and panels; assets/env/ the backgrounds; assets/plants/ the turrets; assets/pests/ the enemy ships; assets/fx/ small effects.
2. Open it in Photopea to see its exact size in pixels (Image > Image Size).
3. Make your new picture with the same width and height and a transparent background where the original has one.
4. Export it as WebP (Photopea: File > Export as > WEBP) or as PNG and convert it with Squoosh.
5. Save it with exactly the same file name over the old one (keep the backup). Reload the page.

5. Recipe B: logo, game name, icon and page title

1. Logo (title screen, loading screen and "rotate your phone" screen): assets/ui/logo.webp, 1536 x 1024 pixels with a transparent background.
2. Browser tab icon: assets/ui/favicon-starfort.png, 400 x 400 pixels. Keep the name, or change the name in index.html (line with rel="icon").
3. Page title (the text on the browser tab): the <title> line in index.html.
4. Game name inside the game: key title in src/i18n/starfort-theme.js. The file has one block per language (en:, pt:, es:...); change it in each block you use.
5. Save name: if you publish a renamed game on the same website as Starfort, change SAVE and SETTINGS at the top of src/main.js (for example mygame.save.v1) so the two games keep separate progress.

6. Recipe C: the robot captain (mascot)

The captain appears on the title screen, in the tutorial and on the victory and defeat cards. Each pose is one picture of 650 x 650 pixels with a transparent background, in assets/ui/:

Replace all poses in the same art style (recipe A). The names start with hazel- because the game engine is shared with other themes; the name does not matter to the player.

7. Recipe D: turrets (pictures, names, power)

1. Pictures: each of the 12 levels has four pictures of 300 x 300 pixels in assets/plants/: pN-0.webp resting, pN-1.webp blinking or happy, pN-2.webp aiming, pN-3.webp firing (N is the level, 1 to 12). Draw the turret centered, facing left, on a transparent background, and keep the four frames aligned.
2. Names: keys p1 to p12 in src/i18n/starfort-theme.js (English: Cadet Cannon, Twin Blaster, Burst Cannon, Turbo Gatling, Meteor Cannon, Solar Piercer, Cryo Guardian, Guided Swarm, Electric Arc, Plasma Orb, Lance Star, Vortex Core).
3. Power: the list PLANTS at the top of src/game/data.js, one line per level: dmg = damage per hit, rate = shots per second, range = how far it shoots. Change one number at a time, for example dmg: 10 to dmg: 12 makes level 1 hit 20% harder. Do not change lv, key or fire.

8. Recipe E: enemy ships and bosses

1. Pictures: each enemy is one strip of 8 frames in assets/pests/, 3360 x 330 pixels (8 cells of 420 x 330). Cell order: four flying frames, two attack frames, one "hit" frame and one "destroyed" frame. The ship flies to the right, toward the barrier. Keep the cell size; the list of frames is in assets/pests/pests.json.
2. Files: aphid.webp, hopper.webp, beetle.webp, snail.webp (with snail_cracked.webp after its shield breaks), slug.webp, stinkbug.webp, bombardier.webp, ladybug.webp (the rare golden bonus ship). Bosses: rhino.webp, wasp.webp, megasnail.webp plus a large picture each (rhino-space-hd.png, wasp-space-hd.png, megasnail-space-hd.png, 1680 x 1320).
3. Boss names: boss_rhino, boss_wasp, boss_megasnail and their one-line descriptions bossEpi_... in src/i18n/starfort-theme.js.
4. Strength: the list PESTS in src/game/data.js: hp = health, speed = how fast it flies, dmg = damage to the barrier, reward = coins when destroyed.

9. Recipe F: backgrounds and world names

World names: keys world0, world1, world2 in src/i18n/starfort-theme.js.

10. Recipe G: texts and translations

1. Theme words (game name, turret, enemy, boss, world and power names, tutorial lines) are in src/i18n/starfort-theme.js, one block per language. These win over everything else.
2. Interface texts (buttons, menus, cards) are in src/i18n/en.js, pt.js, es.js and the other 11 language files.
3. Open the file, search the text you see in the game (Ctrl+F), change only what is between the quotes, save.
4. Keep markers such as {n} exactly as they are: the game replaces them with numbers.
5. A quote inside a text needs a backslash: 'It\'s here'. If the game stops loading after an edit, a quote is missing; restore the backup or check the line in Visual Studio Code, which shows the error in red.
6. Missing texts fall back to English, so you can translate only some keys.

11. Recipe H: sounds and music

Sound effects are MP3 files in assets/sfx/espaco/. Each sound has two recorded variations (-1 and -2) that the game alternates. Replace both files, keeping the names. Keep sounds short (under one second for shots and hits) and normalize them in Audacity (Effect > Normalize) so the volume matches.

Music is in assets/music/: starfort-menu.mp3 (title screen), starfort-onda.mp3 (battles) and starfort-chefe.mp3 (boss waves). Replace them with loops of the same names. The list of variations is in src/sfx-selecao.js; volumes per sound are in LEVEL in src/audio.js.

12. Recipe I: difficulty and waves

All numbers are in src/game/data.js, in the block BAL and the list WAVES. Change a little at a time and play a few waves.

Waves: each entry of WAVES is one wave. A group reads ['aphid', 5, 2.4, 'spread', 0] = enemy, how many, seconds between them, formation (spread, center, cluster, edges), and the second of the wave when the group starts. Add or remove groups to change a wave. TOTAL_WAVES (30) is the campaign length; after it comes Endless mode.

Optional check with Node.js: run npm test in source/. One test plays the campaign with a simple bot and tells you if the balance became impossible.

13. Recipe J: prices, rewards and upgrades

Enemy rewards are the reward numbers in PESTS (recipe E).

14. Recipe K: colors, buttons and the font

1. Text colors: at the top of css/game.css, inside :root: --ink (dark text, #3a2416) and --cream (light text, #fff4dc). Change the color code; any color picker gives you one.
2. Buttons and panels are pictures, so their colors change with recipe A: assets/ui/btn-green.webp, btn-gold.webp, btn-orange.webp, btn-cream.webp, panel.webp, ribbon-win.webp, ribbon-lose.webp, ribbon-pause.webp. Overlay screen styles are in css/screens.css.
3. Font: the game uses Fredoka (SIL Open Font License), files in assets/fonts/. To use another font: download it as WOFF2 (for example from Google Fonts, then converted with a WOFF2 converter), put the files in assets/fonts/, change the four @font-face blocks at the top of css/game.css to the new file names and the new name, and change --font in :root. Keep the license file of the font you add.
4. Sizes: everything is measured in --u (1% of the game height), so the layout scales on every screen. To make one element a little bigger, find its rule in the CSS and raise the number before * var(--u) a little.

15. Internal names in the code

The game engine is shared with other templates of ours, so some names in the code are neutral keys that the player never sees. Only the texts in src/i18n/ reach the screen.

16. Check and publish your changes

1. Play at least one full wave on your computer: recruit, merge, hold the wave, and let the barrier fall once.
2. If you edited source/ and have Node.js: run npm test and then npm run build. The new game is written to source/dist/. Without Node.js, copy the files you changed from source/ into the same places in game/.
3. Upload the contents of dist/ (or game/) to your web hosting with any FTP program (for example the free FileZilla) or your host's file manager. Keep all folders next to index.html.
4. Open the address in a private window. If players still see the old version, clear your host or CDN cache; adding ?v=2 to the address helps check.
5. Never upload source/, node_modules/ or the ZIP to the public game folder.

17. If something goes wrong

• Black or empty page after an edit: press F12, open the Console tab and read the first red line; it names the file and line. Usually a missing quote or comma. Restore the file from your backup if needed.
• A picture is missing: the name or folder is different (names are case sensitive on most servers: Logo.webp is not logo.webp).
• A picture looks stretched: it does not have the original width and height (recipe A).
• No sound: browsers start sound only after the first tap or key press; check the in-game Sound menu.
• Progress reset: progress is kept per browser and per website address; a new address or a new save name (recipe B) starts fresh.

Need help or custom work? Write to willian@polargames.com.br with the version (1.0.1), your browser and a screenshot.