Grid & Cage — Three Sudoku Variants, One Grid

A complete, production-ready HTML5 logic-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.

Disclaimer: This item includes an optional sponsor/ad slot framework that can be connected to third-party ad networks or sponsor services (such as Google AdSense, AdMob, ironSource, or similar). These are external, third-party services outside of this product and outside of the seller’s control, and may involve their own separate costs, terms, or account requirements. Buyers are responsible for reviewing and agreeing to the terms of any ad network or sponsor service they choose to integrate.

Overview

Grid & Cage bundles three Sudoku variants on one shared 9×9 engine: Killer Sudoku (cages that sum to a target, with no repeated digit inside a cage), Jigsaw Sudoku (nine irregular regions replace the classic 3×3 box), and Diagonal Sudoku (classic box rules plus both corner-to-corner diagonals). Every puzzle 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, five selectable board themes (each with its own fixed background image), a shared XP progression system with seven rank tiers, a local best-times leaderboard, an eight-achievement system, 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 puzzle modes are contained in a single IIFE in scripts/js/game.js
• There is no bundled puzzle file — Killer, Jigsaw, and Diagonal Sudoku boards are all generated algorithmically at runtime, for every difficulty tier
• 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: scripts/config/ads.js
• Five bundled background images, one per theme (scripts/images/bg-amber.webp, bg-jungle.webp, bg-obsidian.webp, bg-midnight.webp, bg-crimson.webp) and one favicon (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

Puzzle Modes

The mode is chosen right after the lobby, on its own dedicated “Choose a Mode” screen, before difficulty. All three modes share the same 9×9 grid, row, and column rules — only the extra region rule changes.

• Killer Sudoku — Fill the grid 1–9 with no row, column, or 3×3 box repeating a digit. Every dashed cage’s cells must add up to the target printed in its corner, with no digit repeated inside a single cage.
• Jigsaw Sudoku — Standard row/column rules, but the nine irregular bold-outlined regions each hold every digit 1–9 exactly once, replacing the 3×3 box entirely.
• Diagonal Sudoku — Standard row, column, and 3×3 box rules, plus both main corner-to-corner diagonals must also hold every digit 1–9 exactly once.

The difficulty screen’s heading, subheading, and difficulty descriptions all update dynamically to match the selected mode.

Difficulty

• Easy — smallest cages (Killer) or highest given-digit count (Jigsaw/Diagonal).
• Medium — bigger cages / fewer givens than Easy.
• Hard — largest cages / fewest givens; toughest logic.
• Daily — a puzzle unique to each player, seeded from today’s date plus a per-device player ID, built at a configurable difficulty (Medium by default via dailyDifficulty). No server or puzzle database — a fresh puzzle is generated every calendar day and never repeats. Killer, Jigsaw, and Diagonal each track their own Daily independently; completing one mode’s Daily marks only that mode’s card done until the next calendar day.

The grid is always 9×9 for every mode and difficulty — difficulty controls cage sizes (Killer) or how many digits are pre-filled as givens (Jigsaw, Diagonal), not the grid size itself.

Import Puzzle (Killer Sudoku Mode Only)

On the difficulty screen, in Killer Sudoku mode only, players can paste a complete, already-solved 81-digit grid (digits 1–9, no zeros) into the Import Puzzle panel. The game validates that every row, column, and box is legal, then builds a Killer Sudoku cage layout around it and loads it as a “Custom” puzzle. This panel is hidden on the Jigsaw and Diagonal difficulty screens — importing always produces a Killer-style cage board, regardless of which mode was open when the import row was last visible. Custom puzzles are not recorded on the leaderboard.

Themes

Five board themes are selectable from the “Board · Style” screen, shared across all puzzle modes. Each theme owns one fixed background image — there is no separate background picker. The active theme is saved to localStorage and restored on every visit. The default theme is Obsidian Night.

• Obsidian Night — charcoal black, cool ice-blue glow (default)
• Midnight Blue — deep navy, bright white ink
• Golden Amber — sunlit gold on black ink
• Emerald Jungle — deep green with white ink
• Crimson Ember — bold red, dark ink (marked as new)

How to Play

1. From the lobby, press Play to go to the Choose a Mode screen.
2. Choose Killer Sudoku, Jigsaw Sudoku, or Diagonal Sudoku.
3. Select Easy, Medium, Hard, or Daily on the difficulty screen. Killer Sudoku also offers the Import Puzzle panel here.
4. In Killer Sudoku: fill every cell 1–9 with no repeats in a row, column, or box, and make every cage’s cells add up to its target with no repeated digit inside the cage.
5. In Jigsaw Sudoku: fill every cell 1–9 with no repeats in a row, column, or irregular region.
6. In Diagonal Sudoku: fill every cell 1–9 with no repeats in a row, column, box, or either main diagonal.
7. Use Check, Hint, Undo, Reset, and New as needed, then complete the puzzle to see your time, moves, mistakes, and XP earned.

Game Screen Controls

Every mode uses a numpad (tap a cell, then tap 1–9) plus a left-side action sidebar:

• Check — checks every filled cell against the solution; shows a toast for remaining cells or shakes any cells that are wrong.
• Hint — fills a cell with its correct digit.
• Undo — reverts the last placed digit or pencil mark.
• Reset — restarts the same puzzle from scratch, with confirmation.
• New — returns to the lobby to start a new puzzle, with confirmation.
• Pencil (numpad button, or press P) — toggles candidate-note mode for a cell instead of placing a final answer.
• Pause — pauses the timer with a popup to Resume, start a New Game, or Quit to Lobby.

Keyboard Shortcuts

• 1–9 — place a digit in the selected cell
• Backspace / Delete / 0 — clear the selected cell
• P — toggle pencil mode
• Ctrl+Z (or Cmd+Z) — undo the last move
• Arrow keys — move the selected cell
• Esc — open/close the pause popup

XP and Rank System

All three modes award XP toward one shared rank system using the same formula: a base amount per difficulty, plus a bonus for finishing with zero mistakes, plus a bonus for finishing under the par time for that difficulty. Both bonus amounts and all base/par values are configurable.

The seven rank tiers:

• 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.

Achievements

Eight achievements are tracked and displayed as gold badges in the lobby once unlocked (the lobby shows up to 4 at a time, with a “See More” button opening a full Achievements page for the rest):

• First Win — complete your first puzzle, in any mode
• Perfect Solve — finish a puzzle with zero mistakes
• Speed Demon — finish a puzzle in under 3 minutes (best time)
• 3-Day Streak — reach a win streak of 3
• 7-Day Streak — reach a win streak of 7
• Hard Mode — complete a puzzle on Hard difficulty
• 10 Puzzles — complete 10 puzzles
• Daily Champ — complete a Daily Challenge

All three modes count equally toward these achievements and toward the games-played, best-time, and streak stats shown on the lobby.

Leaderboard (Best Times)

A local best-times leaderboard is accessible from the lobby, with Easy / Medium / Hard tabs, ranked by fastest time (up to 10 entries per tab by default, configurable). Each entry records time, mistake count, and date. Wins from all three modes share the same Easy/Medium/Hard tabs — there is no separate leaderboard per mode. Daily Challenge wins are recorded under the Medium tab. Custom-imported boards are excluded. The leaderboard can be cleared from its own screen.

Settings

All settings are accessible from the lobby settings button. The board Theme is the only choice saved to localStorage and restored on every visit. The four toggles below are session-only — they reset to defaults on page reload and are not written to localStorage.

• Sound Effects — toggle procedural Web Audio API sounds for moves, errors, and win sounds. Can also be toggled from the lobby’s sound icon. Session-only.
• Show Errors — highlights incorrect numbers in red. Session-only.
• Highlight Same Numbers — shows matching digits when a cell is selected. Off by default. Session-only.
• Animated Particles — toggle the floating background particle animation on the canvas layer. Session-only.

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 popup containing an iframe sized to the standard 300×250 Medium Rectangle format
• A countdown timer starts at 5 seconds by default (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 scripts/config/ads.js. As shipped, scripts/config/ads.js sets ads.enabled: true, so the sponsor popup is on by default — set it to false to turn it off
• Ad trigger points: before a puzzle starts, whether from Start Puzzle, Play Again, or the Import Puzzle panel

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. Grid & Cage 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.

Ad Network Approval FAQ

• Do I need to register with the ad network first? Yes — every ad network requires its own account, registered and approved by that network, before real ads will show in the sponsor slot.
• Who approves my account? The third-party ad network itself, entirely on its own terms. This product only provides the ad placement/integration infrastructure — it has no role in, and no control over, that decision.
• Is approval guaranteed? No. Approval is not guaranteed by this product or its author; each network reviews applications against its own eligibility requirements and policies.
• How long does approval take? Review and approval times vary by provider and are set entirely by that provider.
• What is the buyer responsible for? Meeting the ad network’s eligibility requirements, agreeing to its terms of service, and maintaining the account — this product cannot guarantee eligibility on the buyer’s behalf.

Configuration System

Game behavior is controlled by a window.EQUATION_CONFIG object, which scripts/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)
• Mistake threshold before the “keep going” toast appears (mistakeLimit, default 3; 0 = never shown)
• Difficulty used to build the Daily Challenge puzzle (dailyDifficulty, default “medium”)
• Optional Time Attack countdown, any non-Daily puzzle (timeAttackSeconds, 0 = disabled by default)
• Cap on hints per game, shared across all modes (maxHintsPerGame, 0 = unlimited, default)
• XP base 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 text per difficulty (difficulty.easy.label, and matching keys for medium/hard/daily)
• Leaderboard max entries (leaderboardMaxEntries, default 10)
• Ad system enable flags and countdown duration (ads.enabled, ads.preGame.enabled, ads.preGame.countdown)
• Confetti and particle enable/count/speed (confetti.enabled, confetti.count, particles.enabled, particles.count, particles.speed)

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, template literals
• Procedural puzzle generator — Killer, Jigsaw, and Diagonal Sudoku boards are all built algorithmically at runtime; a seeded RNG mixes today’s date, the mode, and a per-device player ID to give each player their own never-repeating Daily Challenge, with no server or puzzle database
• Web Audio API — procedural sound effects; 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, and leaderboard 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 (the codebase uses ES6+ features such as arrow functions, Promise, and Set)
• All localStorage access is wrapped in try/catch for safe degradation in private browsing mode