Customization Guide

Make Lantern Bites your own game: your own numbers, dishes, stalls, districts, texts, music, logo and colors. 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: you change numbers, texts between quotes and picture files. All pictures on this page are real screenshots of the game in this package.

1. Before you start

Free tools you need:

• 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: Photopea (in the browser), GIMP or Krita. Dishes, stalls, customers and interface pictures are PNG with a transparent background; sceneries are JPG.
• To see the game on your computer, a browser and one of these: the local server included in source/ (npm run serve, needs Node.js, see the main guide), or any local web server you already use (for example XAMPP, WAMP or MAMP). Opening index.html with a double click does not work: browsers block the game files when the page comes from the disk.

Which folder do I edit? The simplest way: edit the files inside game/ and upload that folder. If you also use the developer tools, edit source/ instead and run npm run build, which copies everything to source/dist/ (the same as game/). Both folders have the same file names, so every recipe below works in either one.

Starting a new game while you test: the game saves progress in the browser. Open the pause menu and choose Start over to see a change from the first minute. On your own computer (address localhost) you can also open a district directly with ?debug&bairro=1 at the end of the address (0 is the first district); this shortcut does nothing on a public website.

2. Where everything is

Each number on the screenshot matches a line of the table under it, with the exact file to change. Interface texts are in src/locales.js (English and Portuguese) and in src/locales/ (one file for each of the other 12 languages); the table gives the key of each text. <chain> is one of the 7 foods (grill, steam, tea, sweet, sea, noodle, warm), <stall> uses the same 7 names, and <id> is a district (porto, lotus, neve).

Title screen

1 2 3

The counter

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

The street

1 2 3 4 5 6 7 8 9

A card (new level)

1 2 3 4 5 6

3. More screens of the game

4. Recipe A: change the numbers of the game

Every number is in one file, src/config.js. Open it in the code editor, change only the number, keep the commas and save. Each line has a short comment (in Portuguese) next to it.

• Texts that repeat a number. If you change rushPay, also change the text ui.rush ("Rush hour! Double coins"). If you change vipPay, change the texts ui.vip and tip.vip ("pays triple") and the seal content: '×3' in style-more.css (search for .who.vip::before).
• To switch something off: vipChance: 0 removes the special customer; a very large rushEvery (for example 999999) removes the rush hour. With vipChance: 0 the test of the source complains that the special customer never came (the line with vips in test/sim.test.mjs); the game is not affected.
• The robot test. If you use source/, npm test plays whole games with a robot and checks the pace of the game as shipped. When we tried these changes one at a time, the test still passed with a bigger tank (150), faster flames (1000), dearer lanterns (50 and 12), another prize of the night (900), another book prize, a shorter or more frequent rush hour and a special customer chance of 0.2. It failed, saying that level 5 came too early, with cheaper lanterns (20 and 5), pay: 3, vipPay: 5 and rushPay: 3. That is the test doing its job: if you make the game faster on purpose, the game itself still works, and the limits to adjust are near the end of test/sim.test.mjs (the lines with the minutes allowed to reach each level).

5. Recipe B: change the picture of a dish or a stall

1. Dishes and stalls are in assets/items/. A dish is <chain>-1.png to <chain>-8.png (for example tea-1.png … tea-8.png). A stall is gen-<stall>-1.png to gen-<stall>-5.png.
2. Draw your picture as a square PNG of 256×256 pixels with a transparent background, with the object filling most of the square. A bigger square also works (we tried 512×512: the game draws it in the same space), it only makes the download heavier.
3. Save it with exactly the same name as the picture you replace and copy it over the old file.
4. Change the name of the dish in the list item.<chain> (8 names, in order) and the name of the stall in gen.<stall>, in every language you use (recipe E). The name of the food on the recipe book is chain.<chain>.

6. Recipe C: change the scenery and the customers of a district

The first district (Lantern Market) keeps its pictures in assets/ui/. The others have one folder each: assets/bairros/porto/, assets/bairros/lotus/ and assets/bairros/neve/. Every district uses the same 13 file names:

1. Prepare your pictures in the same sizes and proportions.
2. Give them the same names and copy them over the old files of that district.
3. street.jpg and street-dark.jpg must be the same drawing, one lit and one dark.
4. The names of the district and of its places are texts: bairro.<id> and area.<place> (recipe E).

7. Recipe D: add a district

We tried this recipe with a fifth district called coral: the street, the map of the districts and the win card showed the 5 districts on a phone and on a wide screen.

1. Choose a short name with no spaces or accents, for example coral, and three names for its places, for example reef, cove and tide.
2. Open src/config.js, find DISTRICTS and add a line at the end of the list, before the ];:

   export const DISTRICTS = [
     { id: 'market', areas: ['gate', 'alley', 'plaza'] },
     { id: 'porto', areas: ['harbor', 'pier', 'lighthouse'] },
     { id: 'lotus', areas: ['roundgate', 'bridge', 'pavilion'] },
     { id: 'neve', areas: ['icegate', 'hotrow', 'icegarden'] },
     { id: 'coral', areas: ['reef', 'cove', 'tide'] },
   ];

3. Create the folder assets/bairros/coral/ with the 13 pictures of recipe C. To start, copy the folder of another district and replace the pictures one by one.
4. Add the music assets/music/coral.mp3 (recipe F). Without this file the district is silent.
5. Open src/locales.js and add the four texts to the English block, next to the other bairro. lines, and to the Portuguese block (the test of the source checks that Portuguese has every English text; the other languages show the English text until you translate it):

       'bairro.coral': 'Coral Bay',
       'area.reef': 'Reef Gate',
       'area.cove': 'Shell Cove',
       'area.tide': 'Tide Market',

6. Optional, the color of the counter: in style-more.css, copy the block body[data-bairro='porto'] (the last one in the file with that name), change porto to coral and choose the two colors. Without it the district uses the color of the first one.
7. Save, start the game and, on your computer, open ?debug&bairro=4 to see the new district (the count starts at 0).

8. Recipe E: change texts and languages

1. English and Portuguese are in src/locales.js (the blocks en: and pt:, and a few more lines added below them). Each of the other 12 languages has its own file in src/locales/: es.js, fr.js, de.js, it.js, nl.js, pl.js, tr.js, ru.js, id.js, ja.js, ko.js, zh.js.
2. Each line is 'key': 'text',. Change only the text between the quotes. Keep the key, the quotes and the comma. Keep words in braces such as {n} and {x}: the game puts a number or a name there. If your text has an apostrophe, write the text between double quotes, as in "Let's go!".
3. Useful keys: ui.play (title button), tut.0 to tut.8 (the tutorial), tip.gift, tip.shelf, tip.swap, tip.book, tip.vip (tips), bairro.* and area.* (districts and places), item.* (lists of 8 dish names), gen.* (stalls), chain.* (foods), ui.rush, ui.vip, ui.win and ui.winSub (win card).
4. A key missing in a language shows the English text.
5. To add a language (tried with a 15th language): copy a file of src/locales/, for example es.js to ca.js, and translate it. In src/locales-more.js add the line import ca from './locales/ca.js'; and add ca to the list in the last line (export const MORE = { … zh, ca };). In src/locales.js add ['ca', 'Català'], to LANGS. The language then appears in the pause menu and ?lang=ca works.
6. If you use source/, run npm test: it checks keys and braces in every language. After adding a language, change the number in the line assert.equal(LANGS.length, 14); of test/locales.test.mjs to the new count, or that test fails.

The bundled font has Latin letters only: Russian, Japanese, Korean and Chinese texts are drawn with a font of the player's device (recipe H).

9. Recipe F: replace or remove the music

• There are 4 MP3 files in assets/music/, one per district, played in a loop: feira.mp3 (Lantern Market), porto.mp3 (Harbor of Boats), lotus.mp3 (Lotus Garden) and neve.mp3 (Snow Festival).
• Replace: copy your MP3 over a file, keeping the name. A track that loops without a gap at its end sounds best. The shipped tracks have about the same loudness; a much louder file will sound louder than the effects.
• Remove: delete a file (or the four). The game stays silent in that district and everything else works; the browser only notes the missing file in its console.
• The music starts after the first touch (browsers require it) and players set its volume in the pause menu. The volumes a new player starts with are volume: 0.7, music: 0.4 near the top of src/game.js (0 to 1).
• Sound effects (pops, chimes, fanfares) are made by the code in src/fx.js, so there are no effect files to replace.
• Use only music you have the right to publish.

10. Recipe G: change the logo, the title screen and the icon

1. Logo: replace assets/ui/logo.png (900×388 pixels, transparent background). It is shown on the title screen.
2. Title background: assets/ui/splash.jpg (phones held upright, 941×1672) and assets/ui/splash-land.jpg (wide screens, 1672×941). Leave room for the logo at the top and for the Play button.
3. Name in the browser tab: open index.html and change the text inside <title>. The same file has the logo description in alt="Lantern Bites".
4. Name of the installed web app: name and short_name in manifest.webmanifest.
5. Icons: favicon.ico (browser tab), assets/icon-180.png (180×180), assets/icon-192.png (192×192) and assets/icon-512.png (512×512), square, without transparency. Replace them keeping the names.
6. The girl of the tutorial is assets/ui/guide.png (268×300, transparent) and the pointing hand is assets/ui/hand.png.

11. Recipe H: change colors and the font

• Main colors: the first lines of style.css: --gold (gold details), --ink (light text) and --brown (text on the cream panels).
• Color of the counter in each district: the blocks body[data-bairro='porto'], 'lotus' and 'neve' in style-more.css, with two colors each (--tA and --tB, the two squares of the checkerboard). When a name appears twice in the file, the last block is the one that counts.
• Color of the browser bar on phones: theme-color in index.html and theme_color / background_color in manifest.webmanifest.
• Buttons: the gold button is made of three pictures, the left end (btn-gold-l.png), the middle that stretches (btn-gold-m.png) and the right end (btn-gold-r.png). Keep the same height in the three. Panels use panel-plain.png and the number plates pill.png.
• Sizes in the style sheets are written with --u, the size of one pixel of the original drawing on the player's screen, so everything grows and shrinks together.
• Font: Fredoka, in assets/fonts/ (four .woff2 files and the license), declared by the four @font-face blocks at the top of style.css. It has Latin and Latin Extended letters; Russian, Japanese, Korean and Chinese use a font of the device, listed after Fredoka in the font-family line of body. To use another font, add its .woff2 files to assets/fonts/, change the file names in the @font-face blocks and the name Fredoka there and in body. Check that its license allows use in games and keep the license file with it.

12. What needs a programmer

These parts are built into the code and the layout. Changing only a number or a file is not enough:

• A new food chain or a new stall. Besides CHAINS and GENS, 13 pictures and the texts, the recipe book tabs in src/game.js and the robot test need changes.
• The size of the counter (COLS, ROWS, UNLOCK) and the number of shelf places (SHELF): the screens are drawn for 7×9 squares and 6 places.
• More or fewer than 3 places per district or 6 lanterns per place (AREAS, STEPS): the street is drawn for 3 cards of 6 lanterns.
• More than 3 customers at the same time, or more than 6 customer pictures per district.
• More than 8 dishes per food or 5 levels per stall (MAX_LV, GEN_MAX).
• The steps of the tutorial (their texts can be changed, their order and what they point at cannot) and the sound effects, which are made by code.
• Ads, a store, accounts, cloud saves or a ranking: this edition has none of them.

For custom work, write to willian@polargames.com.br.

13. 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 pace and the texts; the second copies the game to source/dist/.

npm test
npm run build

3. Upload everything inside game/ (or source/dist/, if you built it) to your web hosting, replacing the old files.
4. 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.

14. If something goes wrong

• The game does not open after you edit a file: a comma, quote or brace is missing in a .js file. 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 does not appear: the file name is different from the original (names are case sensitive: Tea-1.PNG is not tea-1.png), or the picture is in another folder.
• Nothing changed: the browser is showing the old file. Press Ctrl+F5, or open the game in a private window.
• The numbers did not change in a game already started: prices and orders already on the screen were made with the old numbers. Choose Start over in the pause menu.
• 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).