Customize Mahjong Cosmic Quest without programming

Step-by-step recipes: pictures, robot, tiles, logo, texts, difficulty, helpers and coins, sounds, colors, font. Works offline, no JavaScript needed.

1 2 3 4 5 6 7 8 9 10

1. Before you start

This guide is for people who do not program. Every change is made in the source/ folder and then copied to game/ with one command (or by copying the files yourself). Keep the folder structure and the file names.

Português: este é o guia de personalização passo a passo (em inglês). Cada receita diz o arquivo exato e o tamanho da imagem. O guia completo em português está em pt.html. Español: esta es la guía de personalización paso a paso (en inglés); la guía completa en español está en es.html.

Free tools

• VS Code (code.visualstudio.com) or Notepad++ (Windows) to edit .js, .css and .html files. Do not use Word or WordPad.
• Photopea (photopea.com, in the browser) to edit PNG pictures with transparency, like Photoshop.
• Squoosh (squoosh.app) to make pictures smaller without changing their size in pixels.
• Audacity (audacityteam.org) to cut sounds and export them as MP3.
• Node.js 26.13 LTS (nodejs.org), only if you want to use the commands npm run serve and npm run build.

Make a backup first

1. Copy the whole downloaded folder (or keep the ZIP) before you change anything.
2. Change one thing at a time and check the game after each change.

See your changes on your computer

1. Open a terminal inside source/ (see DOCUMENTATION.html, Editable project).
2. Run npm run serve and open http://localhost:8080/ in the browser.
3. After each change, reload the page with Ctrl+F5 (Cmd+Shift+R on macOS).
4. Without Node.js you can use any local web server; double-clicking index.html does not work (browsers block it).

2. Where everything is

Each row is a part of the screen and the file that draws it. Pictures are PNG files with transparency where noted. Keep the same size in pixels (or the same proportions) so the layout stays right.

Menu (start screen)

Level maps (one per world)

Level screen (gameplay)

Windows (pause, settings, win, lose)

3. Recipe A: replace a picture (any background, button or decoration)

1. Find the part of the screen in the table above and note the file name, for example assets/cosmic/partida-nebulosa.png.
2. Open that file in Photopea (File > Open). Paint over it or paste your own picture into the same canvas, so the size in pixels stays the same.
3. Keep the transparent areas transparent (buttons, robot, tiles, tray). Backgrounds have no transparency.
4. Export as PNG with exactly the same file name (File > Export as > PNG) and save it over the old file in source/assets/cosmic/.
5. Optional: make the file smaller with Squoosh (OxiPNG), keeping the same size in pixels.
6. Reload the game (Ctrl+F5). Check the landscape and the portrait version of the screen (resize the browser window or use the phone mode of the browser, F12).

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

1. Logo picture: replace assets/cosmic/logo.png (1752 x 897, transparent) as in Recipe A. It appears on the menu, on the map and on some windows.
2. Name in the browser tab: open source/index.html and change the text inside <title> and the content of <meta name="description">.
3. Name read by screen readers and in the language texts: open source/src/i18n.js, search for title: and change it in every language you use.
4. Change the save prefix if you publish a different game based on this one: STORAGE_PREFIX in source/src/config.js.

5. Recipe C: change the robot mascot

1. The robot has 4 poses: robo-feliz.png (happy: menu, map and level screen), robo-aponta.png (pointing: tutorial), robo-vitoria.png (victory jump) and robo-triste.png (sad: tray almost full and lose window). All are in assets/cosmic/.
2. Replace each one as in Recipe A, keeping the size and a transparent background. Keep the character in the same place inside the picture, with the feet near the bottom, so it stands on the platform.
3. Which game situation uses which pose is set in source/src/app/worlds.js (catPoses): the left side is the situation, the right side is the file name after robo-.
4. The platform under the robot on the map is assets/cosmic/plataforma-mascote.png.

6. Recipe D: change the tile pictures

Each world has one tile sheet: assets/cosmic/tiles-0.png (world 1) to tiles-3.png (world 4). A sheet is 1448 x 1086 pixels with 4 columns x 3 rows of 362 x 362 cells, transparent background. The game cuts the cells and centers the visible drawing in each tile.

1. Open the sheet in Photopea. Turn on View > Show > Grid or draw guides every 362 pixels.
2. Paint one picture per cell, leaving a small transparent margin. Each of the 12 pictures must be clearly different from the others: the player matches them by sight.
3. Export as PNG with the same name.
4. Optional: the names of the 12 pictures (used only inside the code) are in source/src/config.js, WORLDS[n].icons, in the same order as the cells: left to right, top to bottom.
5. The burst colors when a trio disappears are ICON_COLORS in source/src/config.js (one color per cell).

7. Recipe E: change texts and translations

1. Open source/src/i18n.js. Each language has a block (en: {, pt: {, es: {...). Each line is key: 'text',.
2. Change only the text between the quotes. Keep the key on the left and placeholders such as {n} (the game puts a number there).
3. To remove a language from the selector, delete its entry in LANGS at the end of the file (you may keep its block).
4. Run npm test: the language test tells you if a key is missing in any language.

8. Recipe F: make the levels easier or harder

The number of tiles of each level is in source/src/game/levels.js, in the table TARGET: one row per world, 15 numbers per row (levels 1 to 15 of that world). More tiles = longer and harder level.

1. Change a number. It must be a multiple of 3 (tiles disappear in trios), for example 33, 36, 39. Keep it at 90 or less: more tiles become too small on phones.
2. Save and run npm test. The test plays every level with its stored solution and fails if a level cannot be won.
3. The shape of the board in each world is SHAPES in the same file (diamond, cloud, pyramid).
4. The tray has 7 slots (TRAY in source/src/game/rules.js). Fewer slots make the game much harder; the tray artwork is drawn for 7.

9. Recipe G: change helpers, coins and stars

1. Helpers per level: HELPERS = { undo: 3, hint: 3, shuffle: 2 } in source/src/config.js.
2. Coins: COINS = { match: 1, win: 10 } in the same file (coins for each trio and for each win).
3. Stars: in source/src/app/screen-modals.js, the line const stars = used <= 0 ? 3 : used <= 2 ? 2 : 1; (no helper = 3 stars, 1 or 2 helpers = 2 stars, more = 1 star).
4. The game has no shop or real-money purchases; coins are a score that the player collects.

10. Recipe H: replace sounds and music

Sounds are MP3 files in assets/sfx/, music is assets/music/tema.mp3. The list below shows which file plays for each event (set in source/src/audio/sfx.js, FILES).

1. Open your sound in Audacity, cut the silence at the start (short sounds feel faster) and export as MP3 (128 kbps is enough).
2. Save it with the same file name over the old one, or save it with a new name and change the name in FILES (without .mp3).
3. Music: replace assets/music/tema.mp3 with a loopable MP3. Keep it small (2 to 4 MB) so the game loads fast.
4. Players can lower effects and music separately in Settings.

11. Recipe I: change colors and the font

1. Most colors of the space theme are in source/css/04-overrides.css (the last style file wins). Use the search of your editor to find a color code, for example #, and change it.
2. The outline color of some effects drawn on the board is INK in source/src/config.js.
3. Font: the game uses Fredoka (assets/fonts/fredoka-latin.woff2 and fredoka-latin-ext.woff2). To use another font, put its .woff2 files in assets/fonts/, change the two @font-face blocks at the top of source/css/01-base.css (the src: url(...) lines) and keep the name Fredoka or replace it everywhere. Include the font license.
4. Check the menu, a level and the windows after changing colors: some buttons are pictures and do not change with CSS.

12. Recipe J: rename or reorder the worlds

1. World names are in WORLDS in source/src/config.js (name:). The game does not print them on screen: they are the accessible labels of the map arrows (read by screen readers). The id is internal: leave it as it is.
2. Each world uses its own tile sheet (tiles-0 to tiles-3), level background, map and portrait versions (see the table in section 2). To swap two worlds, swap their files.
3. There are 15 levels per world (WORLD_SIZE) and 60 in total (LEVEL_COUNT in levels.js). Adding a fifth world needs new art for every screen and changes in the code; ask for custom development if you need it.

13. Check and publish your changes

1. In source/, run npm test (rules, all 60 levels and languages).
2. Run npm run serve and play a level in landscape and in portrait (F12 > phone mode).
3. Run npm run build: it copies index.html, css/, src/ and assets/ to game/. If you deleted or renamed files, delete the old ones in game/ yourself.
4. Upload the contents of game/ to your host, replacing the old files.
5. If you still see the old version, clear the cache (DOCUMENTATION.html, Updates and cache).

14. If something goes wrong

• A picture is missing or broken: the file name or folder is different from the original, or the file is not a real PNG. Names are case sensitive on most web hosts.
• The game stops loading after editing a .js file: a quote, comma or bracket is missing. Press F12, open the Console tab: it shows the file and the line. Put back the line from your backup.
• The layout looks wrong after changing a picture: the new picture has a different size or proportion. Use the size from the table in section 2.
• npm test fails after changing levels: a number in TARGET is not a multiple of 3, or a row does not have 15 numbers.
• Still stuck? Write to willian@polargames.com.br with your purchase code and a screenshot.