Klotski Modern

This is the modernization of the 2019 CIS 27 OpenGL Klotski project. The rule engine is separate from rendering, and the project now includes a new OpenGL 3.3 game window.

Version 1.0.0 is the first complete public release. It combines the five-level campaign, shortest-path assistance, level editor, persistent records and settings, bilingual interface, calm audio design, polished victory flow, and a multi-resolution Windows icon based on the classic Heng Dao Li Ma layout.

See RELEASE_NOTES.md for the bilingual release guide and known notes.

What works

• The original 4 x 5 starting layout
• One-cell movement in four directions
• Collision and board-boundary validation
• Safe handling of empty cells, invalid cells, and unknown piece IDs
• Undo and reset
• A shortest-path solver that returns a legal move-by-move solution
• Win detection when the 2 x 2 goal piece reaches the bottom-center exit
• A dependency-free console preview
• A dependency-free test executable
• A resizable GLFW/OpenGL 3.3 graphical game
• A three-step English/Chinese first-run guide that highlights Cao Cao and the exit, then stays dismissed across future launches
• Mouse drag movement and on-screen Undo, Reset, Hint, Levels, and Exit buttons
• Optimal hints that highlight a piece, name its direction, and show the remaining moves
• Full shortest-solution playback from the current position, with pause/resume, single-step, 0.5x/1x/2x speed selection, live progress, and Stop
• Assisted wins are clearly marked and do not overwrite personal records
• One calm looping background theme generated directly by the game and shared by menus and levels
• Separate button, movement, blocked-move, and victory sound effects
• Consistent three-part settings controls for music and effects; drag the center value to any volume from 0-100% or use the side buttons for 1% adjustments
• One-click preference reset with a keyboard shortcut, without replaying the tutorial
• An on-screen audio toggle; press M at any time to mute or restore all audio
• English and Simplified Chinese UI with separate native font families, 2x supersampling, pixel-aligned placement, and locally saved language preference
• Keyboard shortcuts: S to solve/stop, Space to pause/resume playback, N or Right Arrow to single-step, X to change playback speed, H for a hint, Z to undo, R to reset, M for audio, and Escape for levels
• Smooth eased movement for normal moves, undo, and reset
• Hover, selection, blocked-move, button, and victory feedback
• Language-aware piece labels for Cao Cao, Guan Yu, Zhang Fei, Zhao Yun, Ma Chao, Huang Zhong, and four soldiers
• Engraved character text, corner ornaments, highlights, shadows, and role-specific colors
• A start screen and five-level campaign selector
• Verified 12-, 36-, 60-, 84-, and 116-move difficulty progression
• Per-level timer, par, best move count, and best completion time
• Persistent records stored in the user's local application-data folder
• Victory results with moves versus par, elapsed time, assisted-run status, personal records, new-best highlighting, replay, and next-level actions
• Final-level and custom-level victories return to the level list instead of looping to level one
• A grid-based level editor with Easy, Medium, and Classic starting templates
• Free piece dragging with overlap and boundary validation
• Solver verification, automatic custom PAR calculation, and local save/load
• A sixth level card for playing the saved custom level
• A dedicated Windows app icon and embedded executable version information

Play now

Double-click bin/Klotski Modern.exe, choose a level, and drag a piece in the direction you want it to move. A three-step guide appears for new players before the first level. Each drag advances one grid cell when the destination is valid. Click HINT whenever you want the optimal next move; the cyan outline marks the piece to move. Click SOLVE to watch the entire shortest solution from the current position. During playback, use PAUSE/PLAY, STEP, the 0.5X/1X/2X speed button, or STOP. Choose SETTINGS on the home screen (or press O) to drag the center music and effect values to any volume from 0-100%, or use the side buttons for precise 1% changes. The same screen sets the default playback speed and UI language. Use the audio button in the top-right corner, or press M, to mute and restore audio. Click RESET DEFAULTS or press D on the settings screen to restore preferences.

Choose EDITOR on the home screen (or press E) to create a custom layout. Drag any piece to a new grid position, click VERIFY to confirm that the layout is solvable, then click SAVE. The saved layout appears as level 6 on the level-selection screen. Editor shortcuts are 1/2/3 for templates, V to verify, S to save, and Escape to go back.

Build with Visual Studio 2026

Install the Desktop development with C++ workload and CMake tools, then open this folder directly in Visual Studio, or run from a Developer PowerShell:

cmake -S . -B build
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure

Run the graphical game:

.\build\Release\klotski.exe

Or run the console preview:

.\build\Release\klotski_cli.exe

Commands use piece IDs displayed on the board:

m 4 d
undo
reset
quit

Architecture

• include/klotski/Game.hpp - public rule-engine API
• include/klotski/Level.hpp - built-in level definitions and metadata
• include/klotski/Solver.hpp - shortest-path solver API
• include/klotski/CustomLevel.hpp - custom-level validation and serialization API
• include/klotski/Settings.hpp - persistent audio, playback, language, and tutorial state
• src/CustomLevel.cpp - safe custom-level file parsing and layout checks
• src/Game.cpp - board validation, movement, history, and win logic
• src/Level.cpp - the verified easy, medium, and classic layouts
• src/Settings.cpp - validation and serialization for user preferences
• src/Solver.cpp - breadth-first search with equivalent-piece state deduplication
• app/AudioEngine.hpp and app/AudioEngine.cpp - XAudio2 playback and generated audio
• app/OpenGLMain.cpp - GLFW/OpenGL graphical game
• app/KlotskiModern.rc, assets/klotski-icon-classic.png, and assets/klotski-classic.ico - Windows icon and version resources
• app/main.cpp - console UI
• tests/GameTests.cpp - self-contained regression tests

GLFW 3.4 and glad 2.0.8 are downloaded automatically by CMake from their official GitHub repositories. Rendering reads piece positions from klotski::Game; it does not own the board state. Music and effects are generated at runtime, so the published game remains a single executable and does not require external audio files. Custom levels are stored in the KlotskiModern folder under the user's local application-data directory. settings.txt in the same folder stores audio, playback-speed, language, and first-run guide preferences.

License

Klotski Modern is released under the MIT License. See THIRD_PARTY_NOTICES.md for GLFW, glad, and Khronos notices. Source-code contributions are welcome; see CONTRIBUTING.md before opening a change.