Accessibility ModandClaude Opus 5
18e6473dd3
New sessions land in what looks like a game repository and start treating the
task as game development, so the accessibility framing had to be re-explained
every time. CLAUDE.md states it up front: everything outside accessibility/ is
the vanilla game and is read-only reference, and a request phrased as a game
bug ("the journal doesn't work") means a screen reader user cannot use it.
Deliberately a pointer rather than a copy, so it cannot drift out of sync with
accessibility/docs/. It sends readers to docs/scratch.md first and carries only
what a fresh agent would otherwise get wrong: that the user is blind so no
verification may depend on seeing anything, the small-footprint rule, that
speech must never throw, the FoV rule, how to run the testbed, and how to read
the startup self-test when something is silent.
CLAUDE.md sits in the game tree, so it would show up in the footprint check
that must stay "main.lua | 1 +". Excluded there and in the three places the
docs quote that command.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3.4 KiB
CLAUDE.md
What this repository is
This is an extracted copy of the commercial game Sulphur Memories: Alchemist 0.4.2 (LÖVE 11.5, Lua/LuaJIT) — and the work here is a blind-accessibility mod for it, not game development.
Everything outside accessibility/ is the vanilla game. Treat it as read-only
reference material: you read it to find out how the game works, and you patch it
only in the rare case the docs sanction. All mod code lives in accessibility/.
If a request sounds like a game change ("make the journal readable", "the
inventory doesn't work"), it almost always means "a screen reader user cannot
use this" — the fix belongs in accessibility/, not in states/ or models/.
Read this before doing anything
accessibility/docs/scratch.md — a living handoff document. It carries the
current state of play, confirmed decisions that should not be relitigated, the
traps that have already cost real debugging time, and what is verified versus
merely written. Read it first, and update it before you finish.
Then accessibility/docs/README.md maps the rest: architecture, hooking
strategy, the phased plan, open questions, decisions.
accessibility/README.md is the user-facing manual — the key bindings the mod
adds. Update it when you add or change a key.
Working agreements
- The user is blind. Every verification must be describable in text. Never rely on a screenshot, and never ask them to check something visually. Console output and testbed transcripts are the evidence.
- Change as little game code as possible, so the mod re-applies cleanly to
new game versions. Currently the entire game-side footprint is one line in
main.lua. Check it has not grown:It must staygit diff --stat vanilla-0.4.2 -- . ':!accessibility' ':!.gitignore' ':!CLAUDE.md'main.lua | 1 +. The pristine tree is taggedvanilla-0.4.2. - Speech must never throw. A missing DLL degrades to silence; the game keeps running. Wrappers call through to the original and return its results verbatim.
- Never reveal anything outside
FoV/rememberedFoV. The mod must not become a cheat.
accessibility/docs/scratch.md has the full invariant list; these are the ones
worth knowing before you write a line.
Verify after any change
lua accessibility/tests/test_history.lua # pure Lua, instant
rm -rf ~/AppData/Roaming/LOVE/Alchemist # clean save
"C:/Program Files/LOVE/lovec.exe" . --a11y-test # ~4 min
The testbed drives the real game by code and navigates by reading focus rather than counting keypresses. It has caught essentially every bug in this project, so run it — a change that looks obviously correct is exactly the kind that fails.
What matters is 0 failures, not the check count, which varies between runs
because several blocks are conditional.
Use lovec.exe (not love.exe) for a console. Every utterance is mirrored there
as a [speech] line, so speech is verifiable from a log rather than only by ear:
! interrupted, * immediate, queued.
If something mysteriously does not speak
Run the game and read the startup self-test. It reports every patch and every
descriptor probe. Most menu narration reads the game's file-local variables via
debug.getupvalue, so a renamed local in a future game version shows up there as
PROBE BROKEN: no upvalue 'x' rather than as silence three screens in.
ok (unset until opened) is normal.