Arith

A mental arithmetic trainer in Godot 4.6. Long-term idea: "Typing of the Dead" (or a racing game) for arithmetic facts.

Currently: + and − facts to 20 (0–10 + 0–10, and their inverses), 2-digit

• and − with and without carrying and borrowing, and the multiplication table, 0–12 × 0–12, chosen adaptively per player — it keeps first-try success around 85–90%, reviews facts as they fade, and introduces new ones a few at a time, table by table. Type the answer and press Enter (Backspace, or the number pad's +, to correct): on the number keys, on "laptop letters" (7 8 9 / U I O / J K L as a number pad, 0 on M or Space, Enter on any key to their right), or on an on-screen keypad at the right for tablets (a setting). A wrong answer keeps the problem up; after 2 wrong tries (a setting, can be "never") the answer is shown and the problem comes back 3 problems later. Five fast right answers in a row can earn a Boost: harder problems, a warmer screen and a star per right answer, until the first miss or ten problems. Every 40 problems or so a Spotlight gives eight from one times table (or the squares), the one you know least well, on a cool blue screen. Every 60 or so a Cruise climbs from easy facts upward, a little harder and quicker each step, while the green screen fades over the time you have; it ends at a miss or a slow answer. Esc goes back to the title screen.

The title screen has START, Players (choose, add, rename, delete, and "Where to start?": a quick check, or a level chosen per +, − and ×), Settings (how answers are typed, reduce flashes, reduce motion, show the answer after N tries; per player) and placeholder entries for Difficulty and Theme.

Each player has a profile under user://profiles/<id>/: profile.json (name, colour, settings) and attempts.jsonl, an append-only log of every answer. The first start creates "Player 1".

The speedometer shows correct answers per minute over the last 60 s. The clock starts at GO, after a 3-2-1 count-in.

Layout

• scripts/, by layer; only screens/, ui/, dev/ and the autoloads in data/ are nodes, the rest is pure logic:
  • curriculum/ — Problem, Skill, Curriculum, Procedures (generated 2-digit problems): what can be asked.
  • scheduling/ — Scheduler and its AdaptiveScheduler, RandomScheduler, PlacementRound; Variety measures repetition.
  • learner/ — Learner, ModelEnsemble, SpeedBaseline, and LearnerModel with its implementations in models/.
  • modes/ — special modes: ModeController (a Scheduler), Mode, BoostMode, SpotlightMode and its Topics, CruiseMode.
  • session/ — gameplay rules: Session, AnswerEntry, SpeedTracker.
  • input/ — KeyMap: key presses to digits per input setting.
  • data/ — the Settings and Profiles autoloads; storage via ProfileStore, Profile, AttemptLog.
  • screens/ — one script per scene; Screens lists their paths.
  • ui/ — widgets: on-screen keypad, speed gauge, count-in, drifting numbers, colour dot, mode banner.
  • dev/ — test mode: the DevTools autoload and game_driver.gd.
  • simulation/ — SimulatedLearner, Simulation.
• scenes/, resources/pastel_theme.tres, resources/icons/ — the screens and their look.
• tests/ — dependency-free headless unit tests for the logic.
• tools/ — command-line scripts (simulate.gd).
• docs/ — PLAN.md (next), LOG.md (done), RESEARCH.md (background), VALUES.md (tunable parameters).

Test mode

For working on everything except the arithmetic. Debug builds only (editor runs, godot --path ., debug exports); in a release export it never turns on. Toggle with F12, or start with it on: godot --path . -- --dev.

Key	Does
F1 / F2	Answer the current problem right / wrong
F3	Autoplay: answers every 0.6–2 s, 85% right
F7 / F8 / F11	Start a boost / a spotlight / a cruise now
F4	Fast count-in (1 s; on by default in test mode, applies on restart)
F5	Restart the current screen
F6	Dump the overlay to the console
F9 / F10	Toggle reduce flashes / reduce motion
F12	Test mode on/off

While on, an overlay (top right) shows FPS, settings and the session's internals, and events (answers with response times, GO, scene and settings changes) are traced to the console as [dev t] category: message.

The code is scripts/dev/dev_tools.gd (the DevTools autoload) and scripts/dev/game_driver.gd. It ships in release builds but is gated on OS.is_debug_build(). To strip it entirely, an export preset's exclude filter could drop both files, with the autoload registered only in debug builds.

Simulate

godot --headless --path . -s tools/simulate.gd -- --learners=20
godot --headless --path . -s tools/simulate.gd -- --scheduler=random --pool=all

Plays simulated learners (beginner, typical, advanced) through real sessions on a simulated clock and reports first-try success, answers per minute, how repetitive it felt (Variety), how many facts they truly know before and after, and how each model scored — including against the simulated truth. Options are listed at the top of tools/simulate.gd. Takes a few seconds (the adaptive scheduler re-rates every fact on each pick); run ./verify.sh first after adding classes, so Godot has registered them.

Verify

./verify.sh

Runs gdformat/gdlint if gdtoolkit is installed, then the unit tests (as a headless scene, so autoloads exist).

Screenshot/drive scripts that render a window should pass --disable-vsync: with vsync on, a hidden or off-screen window blocks in the buffer swap.