Read This First

This page is your editing manual for the complete Matchiverse project. Each file is explained in plain language with safe editing steps and clear testing guidance.

What this project contains

• The live game page and game logic.
• Styling and layout rules.
• Documentation page (this file).
• Backup and legacy files for reference.
• Assets like images and sounds.

Safe editing routine

1. Create a backup copy before major changes.
2. Edit one file at a time.
3. Save and refresh browser after each change.
4. If layout or game breaks, revert only the last edit.
5. Keep ID names unchanged in HTML unless you also update JavaScript.

Files in your workspace

Project Structure and How Things Connect

The project is a classic static website game. There is no build system required. Browser reads HTML, then CSS, then JavaScript directly.

Execution flow

1. Browser opens index.html.
2. It loads style.css for visual design.
3. It loads main.js for gameplay behavior.
4. Game boot starts on page loaded event.
5. Assets are pulled from assets folder when needed.

Core dependencies to respect

• Buttons and panels in HTML are linked by ID to JavaScript logic.
• Class names are linked to CSS styles and JavaScript state classes.
• Image and audio path strings in JavaScript must match folder names exactly.
• Local storage keys keep player progress and currency.

File Guide: index.html

This is the main page that contains all visible screens: start screen, level screen, game screen, and modals.

Page architecture inside index.html

• Top audio controls are globally visible and include pause, sound, and music toggles.
• Start screen contains logo, coin indicator, and primary navigation buttons.
• Level screen contains level grid generated dynamically by JavaScript.
• Game screen contains HUD, timer, board container, and powerup controls.
• Modal block group includes tutorial, pause, game-over, and unlock dialogs.
• Audio tags at end of body are required for game sounds.

What can be edited safely

• Button visible text such as PLAY, LEVELS, Hint, Shuffle.
• Modal title and description sentences.
• Section heading words like Choose Level.
• Accessibility labels where wording improvements are needed.

What should not be changed without code updates

• ID values, for example playBtn, gameBoard, timerBar, unlockModal.
• Audio element IDs and source path names.
• The script include that loads main.js.
• Screen wrapper order and class names such as screen and active.

Detailed safe edits with examples

When adding a new button or panel

1. Add markup with a new unique id and class in index.html.
2. Add matching style block in style.css.
3. Register click handler in main.js registerUIEvents section.
4. If panel is a modal, include show and hide handling through existing modal helpers.
5. Test both desktop and mobile widths.

Customization playbook for index.html

Power customization patterns in index.html

• Add a new helper section under game controls for tips or live events.
• Add localization placeholders using data attributes, then map in JS later.
• Split long tutorial paragraphs into bullet lists for better readability.
• Create alternate modal templates and toggle visibility from JS for campaigns.

Debug checklist for index.html edits

• Button visible but not working: verify ID spelling and event registration in main.js.
• Modal not opening: verify modal id plus show class usage.
• Audio not playing: verify source file path and audio element id.
• Screen not changing: confirm active class toggles and screen id consistency.

Typical edits and where

File Guide: style.css

This file controls all colors, spacing, animations, typography, and mobile behavior.

Best place to start

• At top, edit color variables under root to reskin game quickly.
• Adjust button appearance in glass-btn and icon-toggle-btn rules.
• Tune board size using cell-size and media query sections.

Safe visual edits

• Colors, gradients, borders, shadows, font sizes.
• Padding and margin spacing.
• Animation speed and hover effects.

Careful edits

• Changing display and position values can hide game controls.
• Changing grid columns and rows in game board may break selection logic.
• Very small button sizes can make touch input difficult on phones.

File Guide: main.js

This is the gameplay engine. It controls board generation, drag matching, rewards, level unlocking, timer, modals, audio, and startup flow.

Code architecture in main.js

• Wrapped in an IIFE to avoid global variable leakage.
• Config blocks store board, timer, storage-key, and powerup constants.
• Single state object tracks runtime and persistent values.
• DOM cache object stores required elements once at startup.
• Feature blocks are grouped by responsibility: levels, board, timer, tutorial, audio, and events.
• Initialization happens in initializeApp on DOMContentLoaded.

Low-risk JavaScript settings you can change

• Timer values, for example max time and bonus per icon.
• Powerup diamond cost values.
• Unlock cost numbers for levels.
• Tutorial text content in helper functions.

High-risk areas

• Board selection rules and match removal flow.
• Local storage keys and migration behavior.
• Event registration for buttons and global pointer handling.
• Render and refill functions that keep board valid.

Core function map for editing

How to safely add a new gameplay setting

1. Add the setting inside Config block near similar constants.
2. Read setting from state or constants in one function first.
3. Update UI text in index.html if player-facing value changed.
4. Retest complete round and level screen flow.

Advanced customization matrix for main.js

Feature extension ideas for customization

• Add combo multiplier tiers by extending comboChain handling.
• Add daily rewards by storing last claim timestamp in localStorage.
• Add limited-time event mode by swapping activeAnimalKeys pools.
• Add animation intensity settings controlled by a new user preference key.
• Add custom sound profiles by switching audio source sets.

Customization safety checklist for main.js

1. Update one logic block only, then run a full match round.
2. Verify board still creates playable matches.
3. Verify timer and modals still close and open correctly.
4. Verify currency persists after browser refresh.
5. Validate level screen still loads and unlock prices display.

How to safely add a new button action

1. Create button markup in index.html with unique id.
2. Add style in style.css.
3. Create handler function near relevant feature block in main.js.
4. Bind handler inside registerUIEvents.
5. Use existing helpers for modal, toast, and currency updates.

Debug workflow for main.js changes

• If game never starts: inspect initializeApp, bootstrapState, and DOM id matching.
• If board appears but match fails: inspect selection functions and canExtendSelection rules.
• If timer acts weird: check interval clears in startTimer, showPause, returnToHome, and gameOver.
• If values reset unexpectedly: check persistCurrencies and localStorage key names.
• If one click triggers twice: ensure registerUIEvents is called once.

If you need to change game balance only

File Guide: disable.js

This small script disables right-click context menu and common developer shortcuts such as F12 and Ctrl+Shift+I.

Why it exists

• Discourages casual source inspection.
• Can reduce accidental menu interactions in some kiosk-like use cases.

Downsides

• Can frustrate normal users.
• Makes debugging harder even for owner.
• Does not provide real security.

Practical recommendation

Only keep this file if you intentionally want those restrictions. If not needed, remove the script include from your page.

Task Guide: Update Images and Audio

Background images

• Background files are in assets/images/background.
• Level backgrounds use naming like bg_level_1.png up to bg_level_11.png.
• Keep the same filenames to avoid changing code.

Animal icons per level

• Icons are in assets/images/levels/level_N folders.
• Each icon filename should be number based, for example 1.png, 2.png.
• main.js loads icons by number, so names must stay numeric.

Audio files

• Audio sits in assets/audio and is referenced in index.html.
• Keep names stable: bgm.mp3, select.mp3, match.mp3, gameover.mp3.
• If replacing format, also update source type in HTML.

Task Guide: Common Edit Recipes

Recipe A: Change game title text

1. Open index.html.
2. Find title tag in head.
3. Replace text between opening and closing title tags.
4. Save and refresh browser tab.

Recipe B: Make rounds longer

1. Open main.js.
2. Find TIMER object near top.
3. Set max value higher, for example 90.
4. Save and test one full round.

Recipe C: Change button colors

1. Open style.css.
2. Edit root color variables first.
3. Then adjust glass-btn and game-controls button blocks.
4. Check both desktop and mobile layout.

Recipe D: Change level unlock prices

1. Open main.js.
2. Find unlockCosts array.
3. Edit numbers carefully by level index.
4. Save and verify in level screen card prices.

Task Guide: Backup and Recovery

Your workspace includes backup and old files that can help if something breaks.

When to use backup files

• You changed many lines and cannot remember the original.
• Game no longer starts or UI is badly broken.
• You need to compare current and previous versions quickly.

Simple recovery method

1. Identify broken main file, for example main.js.
2. Open backup-main.js side by side.
3. Copy only the required section back.
4. Test again before copying more code.

Task Guide: Testing Checklist

Run this checklist after any file changes.

Function checks

• Start button opens game screen.
• Level button opens level screen.
• At least one match can be made.
• Timer decreases and game over modal appears at zero.
• Hint and Shuffle buttons react correctly.
• Pause and resume both work.

Visual checks

• No overlapping controls on mobile width.
• Board remains centered.
• Text remains readable on all backgrounds.

Data checks

• Coins and diamonds update and persist after refresh.
• Unlocked levels remain unlocked after refresh.

Manual key shortcut reminders: Ctrl + S save file, Ctrl + R refresh browser page.