v0.0.3 PRE-ALPHA
A puzzle game built on the structure and rules of real one-to-one cognitive assessments. Every puzzle is generated fresh, your skills grow as a constellation of skill-point rings graded from D to S, and harder puzzles keep coming after the real test runs out.
This is not a psychological test. It uses no real test's items, and its grades come from rough standards made up for this game. They can't be compared with the results of a real assessment, can't diagnose anything, and must not be used for school, work, legal or medical decisions.
- If you're nervous about an upcoming assessment. Learn what a real session is like: the examiner who won't say if you're right, the timers, going back to easier items, being stopped after a few misses. A short walkthrough explains each of these before your first full run, and you can hide all grades so you can rehearse without worrying about a result.
- If you want a challenge. Rated puzzle sets work like a chess puzzle rating, and difficulty keeps climbing past the real test's hardest item. The daily challenge gives everyone the same ten puzzles each day, with a result you can copy and share.
- If you're just curious. The Learn screen explains how the test works, what each subtest is for, how to read the scores, and some common myths.
puzzleth.github.io/Puzzleth/game works on phones, tablets and computers, with nothing to install. Hold your phone sideways. Puzzleth saves your progress in that browser. On a phone, "Add to Home Screen" gives it its own icon and more room on screen.
The first load downloads about 13 MB, nearly all of it a Python runtime that runs in the browser. Music streams in as it plays. Later visits are faster. When a new version comes out, the page loads it the next time you open it, or offers it with an Update available button on the menu if you're already playing.
Download Puzzleth-<version>-windows.exe from the
Releases page and run it. It needs no Python or
install, and plays offline (the leaderboard needs a connection). It isn't code-signed, so Windows
may warn about an unknown publisher: choose "More info", then "Run anyway".
git clone https://github.com/Puzzleth/Puzzleth.git
cd Puzzleth
./puzzle./puzzle uses your Python if it has pygame-ce, or nix-shell if you're on
Nix. Otherwise install it first (Python 3.10 or newer):
pip install -r requirements.txt
tools/fetch_music.sh # downloads the music (it isn't kept in the repository)
python3 main.pyYour progress is saved to ~/.puzzleth/profile.json.
Players. Everyone who plays on the same computer or browser enters a name, arcade style, and keeps their own progress, ratings, daily streak and feedback settings. Tap your name beside the title (or press P) to switch players, add a new one or remove one.
Online leaderboard. Each player can join the leaderboard from its screen (Leaderboard on the
menu, or B). Nothing is sent until they do. Then their name and puzzle ratings are posted after
every rated set, and they're ranked once they've played ten puzzles of a subtest. Players with the
same name are told apart by a short tag such as #K3QX. Leaving the leaderboard, or removing the
player, deletes their ratings from the server.
Moving to another device. Joining the leaderboard also backs up that player's progress and
settings on the server. Leaderboard > Move to another device shows their recovery code, such as
K3QX-7HMP-W2ZA. On the new device, choose Restore a player (when it asks for a name, or on
the players screen) and enter the code. The player moves there with their progress and leaderboard
place. The old device keeps its copy of the progress but stops posting to the leaderboard. Anyone
with the code can take the player over, so keep it private, or get a new code from the same screen.
Everything works with a mouse or touch screen: on-screen keypads, Confirm, Give up and Pause buttons appear where a keyboard would otherwise be needed.
Sound. Digit Span reads the digits out loud, one per second, as in a real session. Timers tick in their last five seconds, and right/wrong chimes play only when feedback is on, so the full assessment never gives anything away. Settings has separate volumes for sound effects and music.
Your own music and sounds. Put .mp3, .ogg or .wav files in puzzleth/music/ and they
play in a shuffled loop, each fading in and out. To change any sound effect or the spoken digits, add a file with the same
name to puzzleth/sounds/; puzzleth/sounds/README.md lists every
sound and when it plays. On the desktop you can use ~/.puzzleth/music/ and ~/.puzzleth/sounds/
instead, leaving the game's own folders untouched.
Keys: Enter starts the full assessment, D opens the daily challenge, L opens Learn, B opens the leaderboard, F11 toggles fullscreen, and Esc pauses during a subtest. Each subtest's intro screen shows its own controls.
| Mode | What it is |
|---|---|
| Full assessment | All ten core subtests in the real order and under test conditions: no feedback, real time limits, real stopping rules. Ends with a D to S grade for each of the four areas and your overall Grade Score. |
| Training | Click any node in the skill tree to practise one subtest under the real rules, with optional feedback after every item. |
| Rated sets | Ten puzzles matched to your puzzle rating (Matrix Reasoning, Visual Puzzles, Block Design, Arithmetic). Available from each of those subtests' intro screens. |
| Daily challenge | Ten puzzles from one subtest, from easy to beyond the real test. Everyone gets the same puzzles each day, and only your first try counts. |
| Leaderboard | Compare your puzzle ratings with players everywhere, one board per subtest with rated sets. Joining is up to each player. |
| Learn | What to expect in a real session, the ten subtests, the four areas, how scores work, myths and facts. |
| Area | Subtest | Notes |
|---|---|---|
| Verbal Comprehension | Similarities, Vocabulary, Information | Multiple choice, with options written to match how examiners award 2, 1 or 0 points |
| Perceptual Reasoning | Block Design, Matrix Reasoning, Visual Puzzles | Fully generated; every puzzle is checked to have exactly one solution |
| Working Memory | Digit Span (forward, backward, sequencing), Arithmetic | One digit per second; Arithmetic hides the problem after it has been "read" |
| Processing Speed | Symbol Search, Coding | 120-second limits; Coding uses a symbol-to-digit key |
Real administration rules are built in: adult start points; reversal, where earlier items are given in reverse until two in a row are fully right, with full credit for the easier items skipped; discontinue rules; per-item time limits; and Block Design speed bonuses.
Grade Scores. Every subtest, each of the four areas and the full assessment get a letter grade:
D, C, B, A, and S for the very best (drawn in gold; a D comes out battered). A subtest's skill
points are 10 + 3·(raw − mean)/SD, clamped to 1–19, one per pip on its ring. An area or the
overall grade combines its subtests' z-scores, corrected for how closely they correlate:
z = mean_z / sqrt((1 + (n−1)·r) / n). The grade comes from z: S from +2, A from +1, B from −⅓
(around average), C from −1⅓, D below. The means and SDs are estimates tuned to this game, not real
norms. Hide the grades any time in Settings.
Puzzle rating. Each difficulty level has a nominal rating. Level 1 is about 650, and the real
test's last item is 1800. After each puzzle your rating moves the Elo way:
rating += K·(result − expected). Puzzles are picked near your rating, so you solve about half.
Levels past the real test add things like 4×4 Block Designs, five-rule matrices, bigger Visual
Puzzles and multi-step word problems.
- Languages. Puzzleth is in English, Romanian and French. Choose one when the game starts; it
is saved on the device and can be changed in Settings. Similarities, Vocabulary and Information
have their own words and questions in each language rather than translations, so that items are
as natural and as hard as the English ones, and Digit Span speaks the digits in that language.
So in those three subtests, the daily challenge is the same for everyone playing in the same
language. To add a language, see
puzzleth/i18n.py. - Practice effects. Practising test formats can raise scores on a real test. If you are assessed by a professional, tell them you've practised.
python3 -m unittest discover -s tests # or: nix-shell --run "python3 -m unittest discover -s tests"
python3 tools/screenshots.py # regenerate the images in docs/screenshots
tools/make_sounds.py --voice en_US-ljspeech-high.onnx # regenerate puzzleth/sounds (needs ffmpeg, piper)
tools/make_sounds.py --language fr --voice fr_FR-siwis-medium.onnx # the French digits (or ro, mihai)Web version. pygbag compiles the same code to WebAssembly.
pip install pygbag==0.9.2 fonttools
tools/build_web.sh --serve # try it at http://localhost:8000
tools/build_web.sh # static site in build/web/, ready for any web hostThe build converts any .mp3 and .wav files in puzzleth/sounds/ and puzzleth/music/ to
.ogg, which every browser plays, so it needs ffmpeg if you've added some. To keep the first load small,
the music is served beside the page and streamed when a song starts rather than packed into the
game's download, and the fonts are cut down to the characters the game uses.
Each build names the game's download after its contents and writes version.txt. Browsers can't
then start an old game from a new page, and an open page can see that a newer build is out.
The GitHub Actions workflow in .github/workflows/pages.yml runs the tests, then builds and
publishes the game to GitHub Pages under /game on every push to main, beside the website from
the website branch (which carries the same workflow, so a push there republishes both). To turn it on, open the repository's
Settings > Pages and set Source to "GitHub Actions".
Windows executable and releases. The version is set in puzzleth/__init__.py and shown on the
menu. To release it, push a matching tag. .github/workflows/windows.yml then builds the .exe
with PyInstaller, checks that it starts, and publishes it on the
Releases page.
git tag v0.0.3 && git push origin v0.0.3To build it yourself on Windows, run pip install pyinstaller pillow, then the pyinstaller
command from that workflow.
Leaderboard server. server/ holds the online leaderboard, a Cloudflare Worker with a D1
database. server/README.md explains how to deploy it (free, a few commands)
and then point the game at it through SERVER_URL in puzzleth/online.py. After updating the
server's code, run schema.sql again and redeploy (see that README). Until that's set,
the game hides the leaderboard. To try it without Cloudflare, run npm run local in server/
and start the game with PUZZLETH_SERVER=http://localhost:8787 ./puzzle.
The tests cover the administration rules, the scoring and rating maths, and the generators. For the generators, they check thousands of random seeds for a unique matrix answer, exactly one Visual Puzzles solution, integer arithmetic answers, and valid Symbol Search rows. They also check that daily puzzles are identical for every player.
Copyright (c) 2026 Tabulah Education. All rights reserved. This is proprietary software: you're welcome to play the official builds above, but no permission is granted to copy, modify, re-host or distribute the game or its code. See LICENSE.
The bundled fonts, Inter and
JetBrains Mono, are under the SIL Open Font
License (see puzzleth/fonts/). The web page template is adapted from pygbag's (MIT). The sound
effects are synthesized by tools/make_sounds.py, and the spoken digits were made with
Piper's LJSpeech voice, whose recordings are public domain.
Music. All music is made by andrii g. on Pixabay, is downloaded into puzzleth/music/ by tools/fetch_music.sh from the URLs in
puzzleth/music/songs.txt, and is used under the
Pixabay Content License. It isn't covered by this
project's license.




