Accessibility ModandClaude Opus 5
c841bcc68d
The documented way to run the testbed began with
rm -rf ~/AppData/Roaming/LOVE/Alchemist
which is the player's actual playthrough. It was written down as the
official procedure in four places, so every run of the test suite ate a
real save -- including twice in the session that produced the previous
commit. Reported by Talon.
The testbed does genuinely need an empty save directory: it drives a new
game from the main menu through the prologue, which has already happened
in any real save. So tests/run-testbed.sh MOVES the save aside (never
deletes it), runs, discards the test run's directory and moves the real
one back. Restore is on an EXIT trap plus INT/TERM, so it also happens on
a failed run, a crash and Ctrl-C. If the restore itself fails it says so
loudly and leaves the backup on disk rather than pressing on.
This cannot live inside the mod: love.load calls config.initialize,
keybindings.initialize and user.initialize long before main.lua reaches
require("accessibility").initialize(), so by the time any of our Lua runs
the save directory has already been read. The swap has to happen around
the process.
The rm -rf is removed from all four docs that carried it, each replaced
with the script and the reason not to clear that directory by hand --
being written down as procedure is what made it recur.
accessibility/.gitattributes forces LF on *.sh, or a Windows checkout
hands bash a \r and the script dies. It sits inside accessibility/ on
purpose: a top-level one would show up in the game-file footprint check,
which still reads `main.lua | 1 +`.
Verified with a marker file in a populated save directory: 38 checks, 0
failures, marker intact, no leftover backup directories.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Accessibility mod — developer documentation
Making Sulphur Memories: Alchemist 0.4.2 blind-accessible.
Player-facing keymap and setup: accessibility/README.md.
Picking this up mid-stream? Read scratch.md first. It is the living handoff document: current state, every bug found and why, and the traps.
| Doc | Contents |
|---|---|
| scratch.md | Start here. Working state, bugs found, gotchas, keymap, how to run the testbed. |
| 00-dev-setup.md | Setting up. The two trees, prerequisites, building the dev tree, everyday commands, publishing. |
| 01-architecture.md | How the game is built: states, console, level model, keybindings. |
| 02-hooking-strategy.md | How the mod attaches with (near) zero edits to game files. |
| 03-implementation-plan.md | The original six-phase plan, with outcomes. |
| 04-open-questions.md | Questions raised; see 05 for answers. |
| 05-decisions.md | Decisions made, and the D4 correction. |
Status
Phases 0–5 complete. 23 state descriptors, 5 patches, 34/34 testbed checks, history unit tests passing.
Game-file footprint: one line in main.lua. Verify at any time:
git diff --stat vanilla-0.4.2 -- . ':!accessibility' ':!.gitignore' ':!CLAUDE.md'
The three findings that shaped everything
-
The game was already keyboard-complete. All 28 states implement
keypressed, with a full rebindable-keys system. The gap was that nothing announced what was focused — so the job was narration, not reimplementation. -
The game already writes the text.
console.printis a single chokepoint for all log messages;level.getCursorMessage()describes tiles;inventoryCursorPopup.setcovers four screens. Mostly we re-route existing strings to speech rather than writing a description engine. -
Everything is a
required singleton, anddebug.getupvalueworks. Module functions can be patched in place, and file-local focus variables (selectedOption, …) are readable from outside. Hence the one-line footprint.
Architecture in one breath
main.lua calls require("accessibility").initialize(). That patches module
singletons (console.print, popupStack.add, inventoryCursorPopup.set,
modules.slider), wraps states.switch / update / keypressed / textinput,
and installs a global hotkey layer. Per-screen narration lives in
accessibility/states/<statename>.lua descriptors, read via debug.getupvalue.
A startup self-test reports which patches and probes still resolve — the canary
for a future game version moving something.