A Mate-in-N Chess Puzzle — Unity Template
Version 1.0 | Unity 6+ | URP
This asset is designed as a template and starting point for your own game development. It provides the core systems, architecture, and tools needed to build a mate-in-N chess puzzle game. You are expected to customize, extend, and modify this template to create your unique game. This is not a complete, ready-to-publish game — it's a foundation for developers to build upon.
Hyper Chess is a bite-sized chess puzzle game. Each level is a small board seeded with a few pieces; the player taps a white piece and slides it to deliver checkmate within the allotted number of moves. Levels are verified solvable by a built-in forced-mate solver, so every shipped puzzle has a guaranteed mate. The game ships with a per-level move budget, three boosters, a visual level editor, a batch automatic level generator, an outline highlight on selectable pieces, and a starter pack of generated JSON levels.
Tap a piece, then a highlighted destination to move it. Deliver checkmate before the move counter runs out. Standard chess movement for Queen, Rook, Bishop, Knight, Pawn, and King.
A full Unity Editor window with a visual board painter, per-cell piece placement, board-shape (hole) painting, and per-level move count + booster fields.
Batch-generate hundreds of forced-mate puzzles with a concave difficulty curve, ±jitter, board-size and piece-count ramps, and constraint relaxation. Append-only — never overwrites hand-tuned levels.
Level-gated boosters (Shuffle, Bomb, Unlock) with first-use tutorial popups, provided by the shared NewestDevUI UI/booster package.
A minimax mate-verifier guarantees every generated puzzle has a forced checkmate at the target depth — no luck-based or unsolvable levels ship.
Levels ship as plain JSON under Resources/Levels/. Regenerate or extend at any time with the Auto Level Generator.
Edit > Project Settings > Graphics)Assets/Hyper Chess/Scenes/GameNew.unityOnce in Play mode, tap a white piece — its legal destination cells highlight. Tap a highlighted cell to move. When your move delivers checkmate to the black king, the level is won, the win panel appears, and the next level loads automatically. If you run out of moves without mating, the lose panel appears and the level can be retried.
Each level displays a small board (with optional inactive “hole” cells), a handful of pieces, and a move counter. White moves first; the goal is to checkmate the black king within movesLeft moves. Tapping a white piece highlights its legal destinations; tapping a destination performs the move. Captures remove the enemy piece. Black responds with the solver's best defensive reply, so the player must find the forced mating line.
ChessPiece.GetAvailableMovesmovesLeft count; running out without delivering mate loses the levelChessSimulator evaluates check / checkmate / stalemate on the (possibly non-rectangular) boardLevelManager.AdvanceLevel() runs before the scene reloads; on lose, the same level reloads| Piece | Enum value | Movement |
|---|---|---|
Queen | 0 | Any number of cells orthogonally or diagonally |
Bishop | 1 | Any number of cells diagonally |
King | 2 | One cell in any direction |
Rook | 3 | Any number of cells orthogonally |
Knight | 4 | L-shaped jumps (2+1) |
Pawn | 5 | Forward one cell; captures diagonally |
Piece color is serialised as 0 = White, 1 = Black.
GameManager routes through its win path (firing SoundManager.Instance.PlayLevelClear()) and shows the win panel; the level index advances and the next level loads.Selectable pieces use a position-based inverted-hull outline (OutlineOnly.shader, loaded from Resources/ so it survives WebGL / IL2CPP shader stripping). Each piece also gets a soft drop shadow via AddDropShadow. Piece moves are eased with a short SmoothMove coroutine. A URP post-processing volume (Bloom, Color Adjustments, Tonemapping, Vignette) gives the consistent HyperCasual look.
Game-specific runtime scripts use the HypercasualGameEngine.Chess namespace. Shared UI / booster / win-lose / dev-mode scripts ship in the NewestDevUI package under the HypercasualGameEngine namespace.
| Script | Description |
|---|---|
BoardManager |
Builds the board from the level's rows/cols/layout, spawns tiles and pieces, loads piece meshes from Resources/ChessPieces.fbx, applies white/black materials, and attaches the outline child + drop shadow. Exposes world-position helpers and the live ChessPiece[,] board state. |
ChessPiece |
Base piece component plus the Queen, Bishop, King, Rook, Knight, and Pawn subclasses. Each implements GetAvailableMovesFrom against the active-cell grid; SmoothMove eases the transform to the target. |
ChessSimulator |
Pure (no-GameObject) board model: SimPiece struct, legal-move generation, IsSimInCheck, and CloneSim. Used by both the runtime win/lose checks and the editor forced-mate solver. |
GameManager |
Scene orchestrator ([DefaultExecutionOrder(-100)]). Loads the current level via LevelManager, builds the board, handles piece selection + movement, evaluates win/lose, drives dev hotkeys, and routes the end-game to the win/lose panel. |
LevelManager |
Static loader. Reads Resources/Levels/*.json into a sorted list, tracks the current index under PlayerPrefs key Hyper Chess_CurrentLevel, and exposes GetCurrentLevel, AdvanceLevel, GoToPreviousLevel, ForceReload, plus editor-only disk-write helpers used by the Level Editor and generator. |
PuzzleData |
Serialisable level schema: levelName, rows, cols, movesLeft, a list of PiecePlacement (type/color/row/col), an optional layout bool list for board holes, and the three booster-count fields read by BoosterManager.Init. |
Tile |
Single board cell. Stores its grid coordinate + base color and toggles a highlight when its cell is a legal destination for the selected piece. |
AddDropShadow |
Spawns a flattened unlit cylinder under each piece as a soft contact shadow. |
SoundManager |
Single-AudioSource SFX player with a master-volume slider. Exposes PlaySelect, PlayMove, PlayCapture, PlayLevelClear, PlayLevelFail, and the four booster methods (PlayBlocked, PlayBoosterShuffle, PlayBoosterBomb, PlayBoosterUnlock) required by NewestDevUI. |
CameraSwitcher |
Swaps camera presets / framing. |
| Script | Description |
|---|---|
BoosterManager |
Owns the three booster buttons. Reads counts from the level via Init(LevelData) (aliased to PuzzleData), binds Booster-Button-1/2/3 by name, shows a first-use tutorial popup before the can-run gate, and decrements counts + plays SFX when an effect fires. |
LoseWinPanelManager |
Owns the win / lose panels. ShowWin() writes the “LEVEL N” text and re-wires buttons; LoadNextLevel() calls LevelManager.AdvanceLevel() before reloading the scene so progression sticks. |
DeveloperSettingsController / DeveloperModeButton |
Developer panel + toggle button: next/previous level, trigger win/lose, unlock & refill boosters, reset tutorial popups, with Shift+U/W/L/R hotkeys. |
RotateClockwiseZ, BoosterPopupIconMirror |
Small helpers for the win-screen radial shine and for mirroring a booster button's icon onto its popup. |
| Script | Description |
|---|---|
PuzzleEditorWindow |
Unity Editor window (Tools > Hyper Chess > Level Editor). Left panel: level list (add / duplicate / reorder / delete-with-confirm / save-all / reload). Right panel: piece / layout / generate paint modes, board canvas, per-level rows/cols/moves and per-level fields. |
AutoLevelGeneratorWindow |
Unity Editor window (Tools > Hyper Chess > Auto Level Generator). Batch-generates forced-mate levels with a concave difficulty curve, jitter, append mode, one cancelable progress bar, constraint relaxation, and a red Delete-All. |
PuzzleGenerator |
The forced-mate solver. Places random pieces under the configured constraints and runs a minimax mate-verifier to guarantee a checkmate exists at the target depth before accepting a position. |
HyperChessWelcomePopup |
Welcome window shown once per session on project open (reopenable at Tools > Hyper Chess > Welcome). Hosts buttons for the documentation, the level tools (Level Editor, Auto Level Generator), and an Asset Store review link. |
InputSystemCheck |
Editor-time diagnostic that warns (and offers to fix) if Active Input Handling is set to “New only” — the template relies on the legacy Input class, so it requires Both. |
In the Unity menu bar, go to Tools > Hyper Chess > Level Editor. This opens a dedicated Editor window — no need to enter Play mode.
Piece (place a chosen piece + color), Layout (toggle active / hole cells), and Generate (seed the board from the forced-mate solver)All levels are stored as individual JSON files in Assets/Hyper Chess/Resources/Levels/ with the naming convention Level_1.json, Level_2.json, … The runtime loader uses Resources.LoadAll<TextAsset>("Levels") and sorts by the trailing number in each filename.
The Automatic Level Generator batch-creates playable mate-in-N puzzles. Every generated level is verified by the minimax forced-mate solver, so each shipped puzzle has a guaranteed checkmate at its target depth.
In the Unity menu bar, go to Tools > Hyper Chess > Auto Level Generator.
| Setting | Description |
|---|---|
| Levels to Generate | How many new level files to create. New levels are appended after existing ones (never overwrites). |
| Ramp to max by level | The level number by which the difficulty curve reaches its maximum (concave ease-out). Defaults to 12. |
| Max mate-in-N | Hardest puzzle depth the curve climbs to (1–6; default 4). Higher depths take longer to solve and lean more on constraint relaxation. |
| Difficulty jitter | Random ± variation applied to the curve so consecutive levels feel less uniform. |
| Rows / Cols / White pieces (early & late) | Board-size and white-piece-count ranges; early levels lean toward the minimums, harder levels toward the maximums. |
| Max attempts / level | Solver attempt cap per slot before constraint relaxation kicks in. |
PuzzleGenerator for a verified forced-mate position. If a hard slot can't be solved, it relaxes the constraints (lower depth, fewer pieces, smaller board) so every slot fills, then writes Resources/Levels/Level_N.json.The generator never overwrites existing level files. It always starts numbering from the next available index (e.g., if Level_30 exists, new levels start from Level_31). Use the “Delete ALL Levels” button if you want to start fresh.
The game includes three booster slots, provided and managed by the shared NewestDevUI BoosterManager. Each booster has a configurable number of uses per level (set in the level JSON), an unlock level, and an optional first-use tutorial popup.
| Booster | Slot | Notes |
|---|---|---|
| Shuffle | Booster-Button-1 |
Driven by PuzzleData.shuffleBoosterCount. Unlocks at level 1 by default. |
| Bomb | Booster-Button-2 |
Driven by PuzzleData.bombBoosterCount. Unlocks at level 2 by default. |
| Unlock | Booster-Button-3 |
Driven by PuzzleData.unlockBoosterCount. Unlocks at level 3 by default. |
Booster buttons live in the scene under GameHUD_Panel/BottomHolder. Each button has a background overlay (Bg), a use-count badge (PowerUpCountText) showing remaining uses or the unlock level ("lvl N") while locked, and a first-use popup. Popup keys are stored in PlayerPrefs (BoosterPopupShown_Shuffle, BoosterPopupShown_Bomb, BoosterPopupShown_Unlock).
NewestDevUI ships BoosterManager with placeholder ApplyShuffle / ApplyBomb / ApplyUnlock effect methods that log + play SFX. Wire them to your own chess-side effects (e.g. reshuffle the pieces, remove a defender, reveal the solution move) to give the boosters real gameplay impact.
Use the Level Editor for hand-authoring and the Auto Level Generator for bulk content. The recommended flow is to batch-generate the bulk of the levels, then hand-tune Levels 1–5 in the Level Editor for a gentle on-ramp.
Piece meshes are loaded from Resources/ChessPieces.fbx by name (queen, king, bishop, knight/horse, rook, pawn). White and black materials are created in BoardManager.LoadMeshes. Replace the FBX (keeping the per-piece mesh names) or tweak the material colors to retheme.
Selectable pieces use Resources/OutlineOnly.shader — a position-based inverted-hull outline that ships identical visuals on Editor, WebGL, and Android. Adjust BoardManager.OutlineWidthFactor (a fraction of the mesh height) to make the silhouette thicker or thinner.
Audio lives on a single SoundManager singleton. Drop new clips onto the SoundManager GameObject in the scene (clips live in Assets/Hyper Chess/Audio/). Add a new clip field + matching PlayX() method if you introduce a new gameplay event.
Each level is a JSON file with the following structure:
type is the PieceType enum value (0=Queen, 1=Bishop, 2=King, 3=Rook, 4=Knight, 5=Pawn) and color is 0=White / 1=Black. layout is an optional row-major bool array of length rows×cols marking active (true) vs hole (false) cells; an empty / omitted list means a full rectangle. Grid coordinates are zero-indexed with (0,0) at the top-left.
| Issue | Solution |
|---|---|
| No levels load / empty board appears | Ensure JSON level files exist in Assets/Hyper Chess/Resources/Levels/ with the naming convention Level_1.json, Level_2.json, etc. Use the Auto Level Generator to create levels if the folder is empty. |
| Pink / magenta materials on objects | The project requires URP — go to Edit > Project Settings > Graphics and ensure a URP Render Pipeline Asset is assigned (valid assets live in Settings/). If objects look correct in the Editor but turn pink only in a build (WebGL / Android), a runtime-created material's shader was stripped: add Universal Render Pipeline/Lit and Universal Render Pipeline/Unlit to Project Settings > Graphics > Always Included Shaders. |
| Outline / highlight not visible | The outline shader must live under a Resources/ folder (Assets/Hyper Chess/Resources/OutlineOnly.shader) so it survives shader stripping in builds. If the silhouette is too thin, raise BoardManager.OutlineWidthFactor. |
| HUD / win-lose panels / boosters missing | The scene ships with the full UI already built. If you deleted part of it, re-import the package to restore Assets/Hyper Chess/Scenes/GameNew.unity. |
| Booster buttons don't respond | Ensure GameHUD_Panel/BottomHolder contains children named Booster-Button-1, Booster-Button-2, Booster-Button-3, each with a Button component. If you added a Canvas for sorting, also add a GraphicRaycaster. |
| First-use booster popups never show | The popups Booster-Popup-1/2/3 must exist in the scene (inactive). BoosterManager uses an inactive-aware scan, so don't rename them. To replay the tutorial, click “Reset Booster Popups” on the Developer Settings panel. |
| No sound | Select the SoundManager GameObject in the scene and confirm its clip fields are assigned (clips live in Assets/Hyper Chess/Audio/) and that master volume is above 0. |
| Level 2 never loads after a win (only Level 1 repeats) | Progression runs through LevelManager.AdvanceLevel() inside LoseWinPanelManager.LoadNextLevel(). Ensure the win panel's Continue button is wired (it ships wired in the scene) and that runtime PuzzleData uses HideFlags.HideAndDontSave if you create it in code. |
GameNew.unity and press Play; no setup step is requiredResources/Levels/ folder regularlyIf you get stuck or have any issues, feel free to reach out to us at ragendom@gmail.com. We are happy to help!