Sudoku — Number Puzzle

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

Sudoku challenges players to fill a 9×9 grid so that every row, column, and 3×3 box contains each digit 1–9 exactly once. The game features four difficulty modes including a seeded Daily Challenge, five selectable board themes, an XP progression system with seven rank tiers, eight achievements, a local best-times leaderboard, pencil-mark candidate notes, and a full 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 are contained in a single IIFE in scripts/js/game.js
• All CSS lives in scripts/css/style.css; ad placeholder in scripts/ads/ad-placeholder.html
• One background image asset: scripts/images/background.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
• Version 2.0 · © 2025 Saadie Lab

Difficulty Modes

• Easy — 36 clues pre-filled. Relaxed pace, described in-game as “Relaxed pace”.
• Medium — 28 clues pre-filled. Described in-game as “Needs thought”.
• Hard — 22 clues pre-filled. Described in-game as “Expert logic”.
• Daily Challenge — same puzzle for all players on a given calendar day, seeded from the current date (YYYY * 10000 + MM * 100 + DD). The card is marked visually as done once the player completes that day’s puzzle. Daily difficulty clue count defaults to Medium (28 clues) and is configurable.

Puzzles are generated procedurally at runtime — there are no pre-stored level files. A valid solution is generated first using a seeded shuffle algorithm, then cells are removed down to the target clue count while verifying uniqueness at each removal step.

Themes

Five board themes are selectable from the “Board · Style” screen. 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 difficulty selection screen.
2. Select Easy, Medium, Hard, or Daily to start a puzzle.
3. Tap or click a cell to select it, then tap a number on the numpad (or press a keyboard digit) to place it.
4. Fill every empty cell so that each row, column, and 3×3 box contains each digit 1–9 exactly once.
5. Use Pencil Mode to jot candidate numbers as small notes in a cell before committing.
6. The puzzle is complete when all 81 cells are correctly filled.

Game Screen Controls

• Check — validates the current board state; reports error count or cells remaining
• Hint — reveals the correct value for the selected cell (or a random empty cell if none is selected); plays a brief highlight animation before filling the cell
• Undo — steps back one move at a time using a full move stack
• Reset — shows a confirmation popup then clears all player entries, restoring only the original given clues
• New Game — shows a confirmation popup then generates a fresh puzzle at the same difficulty
• Pencil toggle (✏) — switches between normal entry mode and pencil/candidate-note mode
• Pause — pauses the timer and opens a popup with options to Resume, start a New Game, or Quit to lobby
• Show Errors toggle — inline toggle on the game board to show/hide incorrect number highlighting
• Highlight Same Numbers toggle — inline toggle to show/hide matching-digit highlighting across the board

Keyboard Shortcuts

• 1–9 — place digit in selected cell
• Backspace / Delete / 0 — erase selected cell
• P — toggle pencil mode
• Ctrl+Z / Cmd+Z — undo last move
• Arrow keys (↑ ↓ ← →) — navigate between cells
• Escape — open or close the pause popup

XP and Rank System

Players earn XP on each completed puzzle. XP is awarded as a base amount per difficulty plus optional bonuses for completing with zero mistakes and for beating 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.

Achievements

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

• First Win — complete one puzzle
• Perfect Solve — complete a puzzle with zero mistakes
• Speed Demon — set a best time under 3 minutes (180 seconds)
• 3-Day Streak — maintain a 3-day play streak
• 7-Day Streak — maintain a 7-day play streak
• Hard Mode — complete at least one Hard puzzle
• 10 Puzzles — complete 10 puzzles total
• Daily Champ — complete at least one 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. Each entry records time, mistakes, and count. The leaderboard can be cleared from the leaderboard screen. Daily Challenge times are not tracked in the leaderboard.

Lobby Statistics

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

Custom Puzzle Import

Players can import any valid Sudoku puzzle by entering an 81-digit string (digits 0–9, where 0 represents an empty cell) using the import panel on the difficulty selection screen. The game validates the string format and the given clues before starting. Imported puzzles are tracked separately from normal games and display a “Custom” badge during play.

Mistake Tracking

Up to three mistake dots are shown above the board. A configurable mistake limit (mistakeLimit, default: 3) can be set to display a persistent error toast when the threshold is reached — the game continues regardless. When more than three mistakes accumulate, an overflow indicator appears.

Time Attack Mode

An optional Time Attack mode is available via configuration (timeAttackSeconds). When enabled with a non-zero value, a countdown bar appears above the board. Time Attack is not active during Daily Challenge games. The bar turns red when under 20% time remaining.

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.

• Sound Effects — toggle procedural Web Audio API sounds (moves, errors, win). No background music is included.
• Show Errors — highlight incorrect numbers in red on the board
• Highlight Same Numbers — show matching digits across the board when a cell is selected
• Animated Particles — toggle the floating background particle animation on the canvas layer

Ad Monetization

The game ships with a fully integrated, configurable 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, then shows “Skip Ad →”
• Ad content is loaded from scripts/sponser/sponsor-placeholder.html. The file contains clearly marked AD REPLACEMENT START and AD REPLACEMENT END comment blocks showing exactly where to paste ad network code (e.g. Google AdSense embed snippet)
• The entire ad system can be disabled by setting ads.enabled or ads.preGame.enabled to false in the config object
• Ad trigger points: before each new game starts (pre-game interstitial)

Configuration System

Game behavior is controlled by a window.SUDOKU_CONFIG object defined before game.js loads. All values have built-in defaults so the game runs without any config. Configurable options include:

• Clue counts per difficulty (difficulty.easy.clues, difficulty.medium.clues, difficulty.hard.clues)
• Difficulty descriptions and labels
• Daily Challenge difficulty (dailyDifficulty)
• Show/hide timer (showTimer)
• Default theme (defaultTheme)
• Time Attack duration in seconds (timeAttackSeconds)
• Mistake limit (mistakeLimit)
• Max hints per game (maxHintsPerGame; 0 = unlimited)
• XP values per difficulty and bonuses (xp.easy, xp.medium, xp.hard, xp.noMistakeBonus, xp.speedBonus)
• Par times per difficulty for speed bonus (parTime.easy, etc.)
• Leaderboard max entries (leaderboardMaxEntries)
• Ad system enable flags and countdown duration
• Particle count and speed (particles.count, particles.speed)
• Confetti enable and count (confetti.enabled, confetti.count)

Tech Stack

• HTML5 — all screens and markup 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
• Web Audio API — procedural sound effects (place, erase, error, win, click); 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, achievements, leaderboard, daily challenge state
• No canvas-based game board — the Sudoku grid is built from DOM elements
• No frameworks, no npm, no build tooling

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