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.
| File | What lives inside it | You'll open this to… |
|---|---|---|
| index.html | The screens themselves and every piece of visible text/labels | Change wording, button labels, tutorial text, shop prices |
| levels.json | The list of puzzles (picture clues + answers) | Add, remove, or edit puzzles |
| style.css | Every color, size, spacing, and animation | Change the look and feel |
| main.js | The game's rules โ coins, hints, scoring | Change starting coins, hint counts, rewards |
| audioManager.js | Sound effects and background music | Change music track or volume |
assets/images/ (logo, background, puzzle pictures)
and assets/audio/ (background music).
Two ground rules that prevent 90% of problems
- 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.
- 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
- Add your clue picture files into the assets/images/ folder first, so you know their exact file names.
-
Open levels.json and find the
closing
}of the very last puzzle in the list. -
Type a comma
,right after that closing}โ every entry except the last one needs a trailing comma. -
Paste in a new
{ "answer": ..., "images": [...] }block underneath, following the pattern above. - Type the answer in capital letters, with no spaces (use one word, or letters only โ see the note below for phrases).
- 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.
{ ... } block
including the comma that follows it (or precedes it, if you're
deleting the last one).
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.
| What it is | Default file | Used in |
|---|---|---|
| Game logo | assets/images/logo.png |
Loading screen and Level Select screen |
| Background | assets/images/background.png |
Behind every screen |
| Browser tab icon | assets/favicon.png |
Browser tab / bookmark |
| Puzzle clue pictures | Any name, your choice | Referenced individually from levels.json |
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
- Open index.html in your text editor.
-
Use Find (
Ctrl+F/Cmd+F) and search for the exact words you see in the game (e.g. search forGreat!). -
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. - Save the file and refresh your browser.
Common text, and where to find it
| Text | Search for | Notes |
|---|---|---|
| Browser tab title | <title> |
Near the very top of the file |
| "Play" button | Play</button> |
Level Select screen |
| "Great!" win message | Great! |
Win overlay ribbon |
| "Paused" message | Paused</div> |
Pause overlay ribbon |
| "Resume" / "Home" buttons | Resume</button> |
Pause overlay |
| Tutorial page 1 title/body | Letter Cleaner |
Help popup, page 1 |
| Tutorial page 2 title/body | Letter Flash |
Help popup, page 2 |
| Tutorial page 3 (Coins) title/body | data-page="2" |
Help popup, page 3 |
| "About Coins" popup (coin badge) | id="coinInfoOverlay" |
Level Select screen |
| Shop default title/subtitle | id="shopTitle" |
See the note below โ this text is overwritten live |
<div class="..."> or
id="playBtn". Those connect the text to the game's
logic and styling โ only change the plain words sitting between
them.
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
| Variable | Controls |
|---|---|
--panel-blue-top /
--panel-blue-bottom
|
The blue gradient behind the level/coin badges |
--gold-1 / -2 / -3
|
Coins, the Play button glow, win-screen board, shop buy buttons |
--teal / --teal-dark |
Small accent highlights |
--pink / --pink-dark |
Wrong-answer feedback tones |
--navy-cell / --navy-cell-dark
|
The empty answer-blank tiles |
--green-1 / -2 / -3
|
Letter tiles and the Play/board buttons |
--card-white |
The Shop popup's background |
Changing one color
- Pick the color you want to change from the table above.
-
Find its line inside
:root { ... }at the top of style.css. -
Replace the 6-character code after the
#with a new one (use any color picker website to get a code โ search "hex color picker"). -
Keep the
#and the semicolon;exactly where they are. - Save and refresh โ the new color appears everywhere that token is used.
--gold- values) keeps the light/shadow effect on
buttons looking natural, instead of flat.
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.
| Variable | Controls |
|---|---|
--logo-width-load |
Logo size on the Loading screen |
--logo-width-level |
Logo size on the Level Select screen |
--pic-frame-size |
Size of each puzzle clue picture frame |
--blank-size-w / -h |
Size of the empty answer-blank tiles |
--tile-size |
Size of the scrambled letter tiles |
--tool-btn-size |
Size of the Hint / Trash power-up buttons |
--puzzle-card-width |
Width of the level-select puzzle card |
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.
vw or cqw)
untouched โ that's what makes the size smoothly scale between
phone and desktop instead of jumping abruptly.
How coins work (in-game currency)
Coins are the game's only currency. This page explains, in plain language, what coins are for, how a player gets them, what they can be spent on, and where the game tells the player all of this.
What coins are
Coins are a free, virtual, in-game currency. Their only purpose is to let the player buy extra charges of the two help tools (Letter Flash โ reveals one letter, and Letter Cleaner โ removes wrong letters). Coins are never required to finish a level: every puzzle can be solved without them, and a player who never spends a coin can still play the whole game.
localStorage) โ nothing is sent to a server.
How a player earns coins
| Way to earn | Amount | Where it's set |
|---|---|---|
| Starting balance (first launch only) | 100 coins | coins = 100 in loadState() |
| Solving a level | +10 coins | COIN_REWARD at the top of main.js |
| Choosing to watch an optional ad (shop button) | +100 coins | AD_REWARD_COINS at the top of main.js |
Watching an ad is always optional โ it only appears as a button inside the shop, and nothing in the game forces the player to press it.
What a player spends coins on
Coins are spent only in the shop, which opens when a help tool runs out of charges. Each bundle shows how many charges it gives and its coin price (defaults below). If the player does not have enough coins the game says so and nothing is deducted.
| Bundle | Price (coins) |
|---|---|
| 1 charge | 150 |
| 3 charges | 400 |
| 7 charges | 900 |
| 10 charges | 1200 |
Where the game explains coins to the player
The same explanation is shown to the player in four places, so they never have to guess:
- About Coins popup โ tap the coin badge (the coin icon with an i) at the top-left of the Level Select screen. It lists how to earn, what to spend on, and the "no real-world value" note.
-
Help tutorial, page 3 (Coins) โ open the
?button during a puzzle and press the right arrow. - Shop โ shows the player's live coin balance, a "Free coins โ watch a short optional ad" row, a "Spend your coins" heading, and a short coin note at the bottom.
-
Win screen โ shows exactly how many coins were
just earned (for example
+10 Coins).
The reward numbers written in these popups are filled in
automatically from COIN_REWARD and
AD_REWARD_COINS, so if you change those two values the
on-screen explanations update themselves.
Connecting a real rewarded-ad network (optional)
The download is ad-network neutral. The "watch an ad" button
calls a small hook named requestRewardedAd() in
main.js. Out of the box (no ad SDK
installed) the hook grants the coins immediately so the game can
be tested. To use a real network, define this function in your
own page before main.js loads:
Coins are granted only when onReward() is called, so
closing an ad early gives no reward. If you don't want any ads, set
AD_REWARD_COINS to a value you're happy with and
delete the shop-row that contains
id="shopAdBtn" together with the
shopAdBtn line in
createShopPopup().
Reset a player's coins
Progress is stored under the key wordPicsState in the
browser's localStorage. Clearing the browser's site
data for the game returns the player to the starting balance.
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.
<span class="coin-count"
id="coinCount">100</span>
in index.html) is just a
placeholder โ update it too so it matches, though it's instantly
replaced with the real balance once the game loads.
Coins earned per solved puzzle
Search for COIN_REWARD near the top of
main.js (right under
STARTING_TRASH).
Coins earned from watching an ad
Search for AD_REWARD_COINS in the same place โ this is
the reward for the optional "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:
| Part | What to change |
|---|---|
data-power="3" |
How many charges this bundle grants |
data-price="400" |
Coin cost โ appears twice in each row, on the
outer <div> and again on the
<button>. Change both to the same number.
|
3 Charges text |
The label shown to the player โ keep this matching the power
number (the game also rewrites this label automatically each
time the shop opens, based on data-power)
|
400 button text |
The price shown on the button itself โ keep this matching the price |
data-price on the row, once on the button). If you
only change one of them, the button will still charge the
old price even though it displays a new number. Always
update both.
Adding a new bundle
-
Copy one entire
<div class="shop-row" ...> ... </div>block. -
Paste it directly below another bundle row, before the closing
</div>ofshop-body. -
Update its
data-power, bothdata-pricevalues, and the visible label/button text to match. - 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 Free 100 Coins โ Watch a short
optional ad, 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), and the number in the
label updates itself. Under the title the shop also shows the
player's current coins (id="shopCoinCount") and a
short note that coins are a free virtual currency with no cash
value (class="shop-note").
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
-
Add your new music file (an
.mp3works best) into assets/audio/. -
Open audioManager.js and search
for
BGM_SRC. - Replace the file name with your new one, keeping the quotes.
- 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).
playClick() and playCorrect() further
down the same file โ each one has a volume: value
between 0 and 1 you can nudge up or down the same way.
tone({ freq: ... })) is what actually
generates each sound โ editing anything besides a number can
silence that effect entirely.
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)
- Install the free Visual Studio Code editor.
- Inside it, install the Live Server extension (search for it in the Extensions panel).
- Open the WordFusion project folder in VS Code.
- Right-click index.html in the file list and choose "Open with Live Server".
- 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)
- Open a terminal / command prompt inside the project folder.
-
Type
python -m http.serverand press Enter (on some computers, usepython3). -
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+Zin 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 (
.pngvs.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-pricespots 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_SRCmatches 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.
| I want to… | Open this file | Search for |
|---|---|---|
| Add / edit a puzzle | levels.json | the last } in the list |
| Replace the logo or background | index.html | logo.png / background.png |
| Change any on-screen wording | index.html | the exact words shown in-game |
| Change a color | style.css | :root { at the top |
| Resize the logo / tiles / buttons | style.css | clamp( |
| Change starting coins | main.js | coins = 100 |
| Change starting hint/trash charges | main.js | STARTING_HINTS |
| Change coins earned per level | main.js | COIN_REWARD |
| Change coins earned from the optional ad | main.js | AD_REWARD_COINS |
| Edit the "About Coins" explanation text | index.html | coinInfoOverlay |
| Hook up a real rewarded-ad SDK | main.js | requestRewardedAd |
| Change shop bundle prices | index.html | shop-row |
| Rename "Letter Flash" / "Letter Cleaner" for good | main.js | openShop |
| Change background music | audioManager.js | BGM_SRC |
| Change music volume | audioManager.js | BGM_VOLUME |