Start here — no coding experience needed

This handbook shows you exactly which file to open and which exact line to change for every kind of edit — new puzzles, new pictures, new colors, new prices, new sounds. You never need to understand the code, just find the labelled spot and swap the value.

What WordFusion is made of

WordFusion is a single small game built from five plain text files that all sit in the same folder. Nothing is compiled or hidden — every file can be opened in a simple text editor.

Two ground rules that prevent 90% of problems

1. Always make a copy before you edit. Duplicate the whole project folder and call it something like wordfusion-backup before you touch anything. If a change breaks the game, you can restore instantly.
2. Change one small thing, save, then test. Don't make ten edits and then check — make one, refresh the browser, confirm it still works, then move to the next.

Use the numbered path on the left to jump to any topic, or use the Next button below to go through the handbook in order — that's the recommended path for a first read.

Adding and editing puzzles

Every puzzle the player solves — its clue pictures and its answer word — lives in one file: levels.json. The game reads this file top to bottom and turns each entry into one level, in order.

The shape of one puzzle

Open levels.json. You'll see a list of entries that look like this. Each one needs exactly two things: the answer word, and the list of images that act as clues for it.

Adding a brand-new puzzle

1. Add your clue picture files into the assets/images/ folder first, so you know their exact file names.
2. Open levels.json and find the closing } of the very last puzzle in the list.
3. Type a comma , right after that closing } — every entry except the last one needs a trailing comma.
4. Paste in a new { "answer": ..., "images": [...] } block underneath, following the pattern above.
5. Type the answer in capital letters, with no spaces (use one word, or letters only — see the note below for phrases).
6. Save the file and refresh the game in your browser to see the new level appear at the end of the list.

Rules the game expects

• Letters only, no spaces — an answer like "ICE CREAM" won't work, because the game builds one blank tile per character and one letter tile per letter. Use "ICECREAM" instead, and let the picture clue explain the two words.
• Capitalization doesn't matter when typing it — the game automatically uppercases the answer, but typing it in capitals keeps the file easy to read.
• Any number of clue images is fine — one, two, or more; each one shows in the puzzle with a + between them.
• Decoy (wrong) letters are automatic — you never add fake letters yourself. The game invents extra letters that aren't in the answer and mixes them into the tile tray for you.

Replacing pictures, logo, and background

Every image the game uses is just a file inside the assets/images/ folder, referenced by name. To change a picture, replace the file — or point the game at a new file name.

Easiest method: keep the same file name

If you replace logo.png with a new picture but save it with the exact same file name and drop it into the same folder, nothing else needs to change — index.html already points at that name.

Using a different file name

If your new file is named differently, open index.html, and use your editor's Find tool (usually Ctrl+F / Cmd+F) to search for the old file name, then replace it.

This logo tag appears twice in the file — once for the Loading screen and once for the Level Select screen — so repeat the change (or use "Replace All" in your editor) for both.

Changing wording, titles, and button labels

Every word the player reads on screen — button labels, tutorial instructions, shop text — is plain text sitting inside index.html. You're just retyping words between tags, not writing code.

How to find and change text

1. Open index.html in your text editor.
2. Use Find (Ctrl+F / Cmd+F) and search for the exact words you see in the game (e.g. search for Great!).
3. You'll land on a line like <div class="board-ribbon-text">Great!</div> — only change the word between the > and <, never the tag names around it.
4. Save the file and refresh your browser.

Common text, and where to find it

Changing colors and the overall theme

Every color used anywhere in the game is defined once, at the very top of style.css, in a section called design tokens. Change a color there and it updates everywhere that color is used — you never need to hunt through the whole file.

Where the color list lives

Open style.css and look at the very first section, which starts with :root {. Each line inside is one named color, written as a 6-character code starting with #.

What each color group controls

Changing one color

1. Pick the color you want to change from the table above.
2. Find its line inside :root { ... } at the top of style.css.
3. Replace the 6-character code after the # with a new one (use any color picker website to get a code — search "hex color picker").
4. Keep the # and the semicolon ; exactly where they are.
5. Save and refresh — the new color appears everywhere that token is used.

Resizing the logo, tiles, and buttons

Just below the color list in style.css is a second group of tokens that control sizes — how big the logo is, how big letter tiles are, how wide the popups are. These automatically scale between phones and desktops, so you only set one value per element.

Each size is written as clamp(smallest, preferred, largest). You don't need to understand the middle value — just adjust the first number (smallest, used on phones) and the last number (largest, used on big screens) to make something consistently bigger or smaller.

Starting coins, hint charges, and rewards

A handful of plain numbers near the top of main.js control the game's economy — how many hints a new player starts with, and how many coins they earn per solved puzzle.

Starting hint and trash charges

Search for STARTING_HINTS near the top of main.js.

Starting coin balance

Search for coins = 100 — it appears in two places inside the loadState() function (a safety fallback and a first-time default). Change both to the same new number so they stay consistent.

Coins earned per solved puzzle

Search for COIN_REWARD inside the handleCorrectAnswer function.

Coins earned from watching an ad

Search for AD_REWARD_COINS inside the handleShopAdClick function — this is the reward for the "Get It ▶ AD" button in the shop.

Changing shop bundles and prices

The shop that opens when a player runs out of Hint or Trash charges is built from a row of bundles inside index.html. Each row is a simple, self-contained block you can copy, edit, or delete.

Anatomy of one bundle row

Search index.html for shop-row. You'll find four of them by default:

Adding a new bundle

1. Copy one entire <div class="shop-row" ...> ... </div> block.
2. Paste it directly below another bundle row, before the closing </div> of shop-body.
3. Update its data-power, both data-price values, and the visible label/button text to match.
4. Save and refresh — no changes are needed in any other file; the game automatically wires up any bundle row it finds.

The "watch an ad" reward

The top shop row (labelled 100 Coins with a "Get It ▶ AD" button) doesn't grant power-up charges directly — it grants coins, which the player can then spend on a bundle below. Its coin amount is controlled by AD_REWARD_COINS in main.js (see Coins, Hints & Rewards).

Renaming "Letter Flash" / "Letter Cleaner"

Because the shop's title text is set live by the game each time it opens, permanently renaming it means editing the words inside openShop() in main.js:

Changing background music and volume

All the little sound effects (clicks, chimes, the wrong-answer buzz) are generated by the game itself and don't need any sound files. The one piece of real audio is the looping background music, controlled by two lines near the top of audioManager.js.

Changing the music track

1. Add your new music file (an .mp3 works best) into assets/audio/.
2. Open audioManager.js and search for BGM_SRC.
3. Replace the file name with your new one, keeping the quotes.
4. Save and refresh — tap anywhere on the game once (browsers require a tap before audio can start).

Changing the music volume

Search for BGM_VOLUME, just below BGM_SRC. It's a number from 0 (silent) to 1 (full volume).

Previewing your edits safely

After every save, you'll want to see your change in a real browser before moving on to the next edit.

Important: don't just double-click index.html

WordFusion loads its puzzle list (levels.json) using a technique that most browsers block when a page is opened directly from your computer's file system (this shows as a blank puzzle screen with no error visible). You need a very small local web server instead — it sounds technical, but it's one command.

Option A — Visual Studio Code + Live Server (easiest for beginners)

1. Install the free Visual Studio Code editor.
2. Inside it, install the Live Server extension (search for it in the Extensions panel).
3. Open the WordFusion project folder in VS Code.
4. Right-click index.html in the file list and choose "Open with Live Server".
5. Your browser opens automatically, and it refreshes itself every time you save a file.

Option B — Python's built-in server (if you already have Python)

1. Open a terminal / command prompt inside the project folder.
2. Type python -m http.server and press Enter (on some computers, use python3).
3. Open a browser and go to http://localhost:8000.

If something looks broken

• Check the Troubleshooting page for the most common causes.
• Undo your last edit (Ctrl+Z / Cmd+Z in your editor) and save again — if the game works again, the problem was in that specific change.
• Compare your edit character-by-character against the "Before/After" examples in this handbook — a missing comma, quote, or bracket is behind almost every issue.

Common problems and quick fixes

Almost every issue after an edit traces back to one of the situations below.

The puzzle screen is blank, or levels never load

• You're likely opening index.html directly instead of through a local server — see Testing Your Changes.
• Check levels.json for a missing comma, a missing closing ] or }, or a stray extra comma after the last puzzle.

A picture doesn't show up (broken image icon instead)

• The file name typed in levels.json or index.html doesn't exactly match the real file name — check spelling, capitalization, and the file extension (.png vs .jpg).
• The image file wasn't actually placed inside the assets/images/ folder.

A shop bundle charges the wrong price

• You likely updated only one of the two data-price spots in that row — see Shop & Prices for both locations.

My color/size change didn't do anything

• Your browser may be showing a cached (old) version of style.css — do a hard refresh (Ctrl+Shift+R / Cmd+Shift+R).
• Double check you edited the value inside :root { ... } at the top of the file, not a similarly-named value elsewhere.

Background music won't play

• Browsers require one tap/click on the page before any audio can start — this is a browser rule, not a bug. Click anywhere on the game once.
• Check the sound icon in the top-right of the Level Select screen isn't showing the muted 🔇 state.
• Confirm the file name in BGM_SRC matches the real file inside assets/audio/.

The game looks fine on desktop but cramped on my phone

• Adjust the smallest (first) number in the relevant clamp() size token in style.css — see Sizes & Spacing.

Where everything lives, at a glance

Bookmark this page — it's the fastest way to jump straight to the right file once you already know the handbook.