Equation · Cages — Equation Puzzle

A complete, production-ready HTML5 math-puzzle game built for commercial distribution. Zero external JavaScript dependencies. Runs on any modern browser straight from a static file host with no build step required.

Overview

Equation · Cages bundles three separate math-puzzle modes in one package: Cage Puzzle (a Sudoku-style grid where cages of cells must solve a printed equation), Equation Match (a tile-swapping grid where equations and answers must be paired up), and Number Crossword (a crossword grid filled in by solving Across/Down equations). Every puzzle in all three modes is generated procedurally at play time — there is no bundled puzzle list. The game features Easy/Medium/Hard difficulty tiers plus a seeded Daily Challenge (shared across all three modes), five selectable board themes, an XP progression system with seven rank tiers, eight achievements, a local best-times leaderboard, an optional Time Attack countdown for Cage Puzzle mode, a Cage Puzzle solved-grid import tool, a configurable hint system, and a full sponsor/ad integration framework — all in a single self-contained HTML5 package.

About the Game

• Entry point is index.html — no build step, no CLI tools, no package manager required
• Pure vanilla HTML5, CSS3, and ES6+ JavaScript — zero libraries, zero frameworks
• Game engine and UI for all three modes are contained in a single IIFE in scripts/js/game.js
• There is no bundled puzzle or word-list file — cage layouts, match tiles, and crossword grids are all generated algorithmically at runtime, for all three modes and all difficulty tiers
• All CSS lives in scripts/css/style.css; sponsor/ad placeholder in scripts/sponsor/sponsor-placeholder.html
• Ads are switched on or off from a single file: config/ads.js
• Two bundled image assets: scripts/images/background.jpg (shared background texture) and scripts/images/favicon.jpg
• Procedural Web Audio API sound engine — no audio files bundled
• All game state persisted to localStorage with graceful degradation when storage is unavailable
• Browser support check on boot — displays a dedicated “Browser Not Supported” screen if requirements are not met

Game Modes

Mode is chosen right after the lobby, on its own dedicated screen, before difficulty. Each mode has its own generator and grid renderer, but all three share the same header, sidebar actions, themes, XP system, and complete screen.

• Cage Puzzle (flagship mode) — A 9×9 grid where every row and column must contain the digits 1–9 exactly once (there is no 3×3 sub-box constraint, unlike classic Sudoku). The grid is divided into bold-outlined “cages” — irregular groups of 1 to 4 adjacent cells — and each cage carries a small equation in its corner (e.g. 20+, 294×) that the digits placed inside it must solve. Single-cell cages are pre-filled “givens.”
• Equation Match — A grid of square tiles (3×3 on Easy, 4×4 on Medium, 5×5 on Hard). Every internal edge between two neighboring tiles shows a two-step linear equation on one side (e.g. “4x + 9 = 5”) and its numeric answer on the other (e.g. “x = -1”). Tiles start shuffled; clicking two tiles swaps their positions. Clicking a single unselected tile first opens a detail popup showing all four of its edges.
• Number Crossword — A crossword-style grid of intersecting numeric entries, listed as Across and Down clues in a panel below the grid. Each clue is a two-step linear equation (e.g. “6n + 7 = 529”); solving for the unknown and typing its digits into the matching run of cells shares digits at every intersection with a crossing entry.

The Import Puzzle field on the difficulty screen (paste an 81-digit solved grid, digits 1–9, no zeros) is only available for Cage Puzzle mode — it builds a fresh cage layout on top of the grid you provide. Equation Match and Number Crossword are always freshly generated.

Difficulty Modes

• Easy — Cage Puzzle: small cages, addition/subtraction only. Equation Match: 3×3 tiles. Number Crossword: 6 clues on an 11×11 grid.
• Medium — Cage Puzzle: bigger cages, adds multiplication. Equation Match: 4×4 tiles. Number Crossword: 8 clues on a 13×13 grid.
• Hard — Cage Puzzle: bigger cages still, all four operators including division. Equation Match: 5×5 tiles. Number Crossword: 10 clues on a 15×15 grid.
• Daily Challenge — the same puzzle for every player on a given calendar day, chosen by a date-based seed, for whichever mode the player has selected. Built at the difficulty configured for the Daily Challenge (Medium by default). The card is marked visually as done once the player completes that day’s puzzle, until the next calendar day, and increments the daily streak. Excluded from the leaderboard.

Themes

Five board themes are selectable from the “Board · Style” screen, shared across all three game modes. The active theme is saved to localStorage and restored on every visit. The default theme is Warm Paper.

• Warm Paper — classic parchment feel (default)
• Jungle — dense canopy darkness
• Neon City — electric arcade glow
• Midnight Ink — sleek deep universe
• Rose Gold — warm blush elegance (marked as new)

How to Play

1. From the lobby, press Play to go to the mode-select screen.
2. Choose Cage Puzzle, Equation Match, or Number Crossword.
3. Select Easy, Medium, Hard, or Daily on the difficulty screen. Optionally, in Cage Puzzle mode, paste a solved 81-digit grid into the Import Puzzle panel instead of pressing Start Puzzle.
4. In Cage Puzzle: fill every row and column with 1–9 once each, so that every cage’s cells satisfy its corner equation. Use Pencil Mode to jot candidate digits instead of placing a final answer.
5. In Equation Match: click two tiles to swap them, working toward every edge showing a matched equation/answer pair.
6. In Number Crossword: solve each Across/Down clue’s equation and type its digits into the matching cells.
7. Use Check, Hint, Undo, Reset, or New from the sidebar as needed, then complete the puzzle to see your time, moves, and any newly unlocked achievements.

Game Screen Controls

• Check — validates the current board and flags incorrect entries
• Hint — mode-aware: in Cage Puzzle it fills a cell with its correct digit; in Equation Match it swaps one tile into its correct position; in Number Crossword it reveals one correct digit. Unlimited by default, but can be capped per puzzle via config.
• Undo — reverts the last move
• Reset — shows a confirmation popup, then restarts the same puzzle from scratch, clearing all entries and the timer
• New — shows a confirmation popup, then returns to the lobby so a new puzzle can be started
• Pause — pauses the timer and opens a popup with options to Resume, start a New Game, or Quit to lobby
• Pencil Mode (Cage Puzzle) — tap the pencil button, or press P, to jot candidate notes in a cell instead of placing a final answer

Keyboard Shortcuts

• 1–9 — place a digit in the selected cell
• Backspace / Delete — erase the selected cell
• P — toggle Pencil Mode
• Ctrl+Z (or Cmd+Z) — undo the last move
• Arrow keys — navigate between cells

Time Attack (Optional, Off by Default)

A configurable countdown for Cage Puzzle mode only. When timeAttackSeconds is set above 0 in the configuration, a shrinking progress bar appears above the board and the puzzle ends in a loss if time runs out before it’s solved. Disabled by default and not applied to the Daily Challenge.

Import Puzzle (Cage Mode)

On the difficulty screen, players can paste any complete, valid 81-digit solved 9×9 grid (digits 1–9, no zeros) into the Import Puzzle panel. The game validates the string for row/column conflicts, then generates a fresh Medium-complexity cage layout on top of it. The resulting puzzle displays a “Custom” badge in the game header and is not recorded on the leaderboard. This feature is available for Cage Puzzle mode only.

XP and Rank System

Players earn XP on each puzzle they solve: a base amount per difficulty, plus a bonus for finishing with zero mistakes, plus a bonus for finishing under the par time. The seven rank tiers are:

• Apprentice — 0 XP
• Solver — 300 XP
• Thinker — 800 XP
• Expert — 1,800 XP
• Master — 3,500 XP
• Sage — 6,000 XP
• Grand Master — 10,000 XP

The current rank and progress toward the next tier are shown as an XP bar in the lobby, shared across all three modes.

Achievements

Eight achievements are tracked automatically and displayed as gold badges in the lobby once unlocked:

• First Win — complete your first puzzle
• Perfect Solve — finish a puzzle with zero mistakes
• Speed Demon — finish a puzzle in under 3 minutes
• 3-Day Streak — play 3 days in a row
• 7-Day Streak — play 7 days in a row
• Hard Mode — complete a puzzle on Hard difficulty
• 10 Puzzles — complete 10 puzzles
• Daily Champ — complete a Daily Challenge

Leaderboard

A local best-times leaderboard is accessible from the lobby. It stores the top results (default: 10 entries per difficulty, configurable) across Easy, Medium, and Hard tabs, ranked by fastest time. Each entry records time, mistake count, and date. The leaderboard can be cleared from the leaderboard screen. Daily Challenge and imported Custom puzzles are not recorded on the leaderboard.

Lobby Statistics

The lobby displays three at-a-glance stats: total puzzles Played, personal Best Time, and current win Streak.

Settings

All settings are accessible from the lobby settings button. There is no persistent localStorage save of settings between sessions — settings apply for the current session only and reset to defaults on page reload.

• Sound Effects — toggle procedural Web Audio API sounds for moves, errors, and win jingles. Can also be toggled from the lobby’s sound icon. No background music is included.
• Show Errors — highlights incorrect digits in red as soon as they’re placed. Applies to Cage Puzzle mode.
• Highlight Same Numbers — shows matching digits across the grid when a cell is selected, in Cage Puzzle mode. Off by default.
• Animated Particles — toggle the floating background particle animation on the canvas layer. Disabling it can improve performance on lower-end devices.

Ad Monetization

The game ships with a fully integrated, configurable sponsor/ad system ready to connect to any ad network.

• Ads are displayed in a full-screen overlay popup containing a sandboxed iframe sized to the standard 300×250 Medium Rectangle format
• A countdown timer starts at 5 seconds (configurable via ads.preGame.countdown). The Skip button is disabled until the countdown reaches zero
• Ad content is loaded from scripts/sponsor/sponsor-placeholder.html. The file contains clearly marked AD REPLACEMENT START and AD REPLACEMENT END comment blocks showing exactly where to paste ad code
• The entire ad system can be disabled by setting ads.enabled or ads.preGame.enabled to false in config/ads.js. As shipped, config/ads.js sets ads.enabled: false, so the sponsor popup is off by default until switched on
• Ad trigger points: before a puzzle starts, whether from Start Puzzle, Play Again, or the Import Puzzle panel — for any of the three modes

Important: Ad network integrations such as Google AdSense, AdMob, and ironSource are third-party external services not affiliated with or included in this product. Each network operates independently and has its own account registration process, eligibility requirements, approval policies, and potentially associated costs. Equation · Cages provides the ad slot infrastructure only — buyers are solely responsible for obtaining their own accounts, meeting each network’s requirements, and complying with their respective terms of service.

Configuration System

Game behavior is controlled by a window.SUDOKU_CONFIG object, which config/ads.js creates and adds its ad settings to. Add further keys to that same object (or your own script loaded before game.js) to customize other behavior. All values have built-in defaults so the game runs without any config. Configurable options include:

• Default theme (defaultTheme)
• Show/hide timer (showTimer)
• Hint limit per puzzle (maxHintsPerGame, 0 = unlimited)
• Mistake threshold before the “keep going” toast appears (mistakeLimit, 0 = never shown)
• Difficulty used to build the Daily Challenge puzzle, for any mode (dailyDifficulty)
• Time Attack countdown length for Cage Puzzle mode (timeAttackSeconds, 0 = disabled)
• XP values per difficulty and bonuses (xp.easy, xp.medium, xp.hard, xp.noMistakeBonus, xp.speedBonus)
• Par times per difficulty for the speed bonus (parTime.easy, parTime.medium, parTime.hard)
• Difficulty label and description text (difficulty.easy.label/.desc, and matching keys for medium/hard)
• Leaderboard max entries (leaderboardMaxEntries)
• Ad system enable flags and countdown duration (ads.enabled, ads.preGame.enabled, ads.preGame.countdown)
• Confetti enable and count (confetti.enabled, confetti.count)

Tech Stack

• HTML5 — all screens and markup for all three modes in a single index.html
• CSS3 — custom properties for theming, flexbox, keyframe animations, canvas particle layer
• Vanilla JavaScript ES6+ — single IIFE module, arrow functions, Set/Map, optional chaining, template literals
• Procedural puzzle generator — cage layouts (flood-fill region growth over a random 9×9 Latin square), Equation Match tile sets, and Number Crossword grids are all built algorithmically at runtime; a seeded RNG makes the Daily Challenge deterministic across all three modes
• Web Audio API — procedural sound effects (placing a digit, erasing, mistakes, and win jingles); no audio files
• Canvas API — floating background particles and win confetti animation
• Google Fonts CDN — Crimson Pro (400, 600), DM Sans (300, 400, 500)
• localStorage — theme, stats, XP, achievements, leaderboard, and daily challenge state
• No frameworks, no npm, no build tooling

Third-Party / External CDN Dependencies

This project relies on an external CDN for one resource. This dependency is third-party, hosted and operated outside of this project and outside of the seller’s control — its uptime, availability, and any future changes to its terms are the responsibility of the provider, not the seller.

• Google Fonts — loaded from fonts.googleapis.com via an @import in scripts/css/style.css, providing the Crimson Pro (400, 600) and DM Sans (300, 400, 500) font families.

An active internet connection is required for the browser to reach this CDN and load these fonts. Without one, the game still runs normally — text simply falls back to the browser’s default system font. Buyers who need a fully offline build can download the font files, host them locally, and replace the @import line in style.css with local @font-face rules.

No other third-party or CDN-hosted libraries (such as Chart.js, jsPDF, three.js, or html2canvas) are used anywhere in this codebase.

Requirements and Compatibility

• Any modern browser: Chrome, Firefox, Safari, Edge (browser support is checked at boot and requires localStorage, AudioContext, document.querySelector, Promise, Set, and Array.from)
• No server-side code required — deploy to any static file host (GitHub Pages, Netlify, S3, cPanel, etc.)
• Internet connection required for Google Fonts (Crimson Pro and DM Sans) to load correctly
• Fully responsive — layout adapts to desktop, tablet, and mobile screen sizes
• Internet Explorer is not supported
• All localStorage access is wrapped in try/catch for safe degradation in private browsing mode