Accessibility ModandClaude Opus 5
fd06961af5
Both aiming modes announced their name and then went silent, so there was no way to know what the arrow keys were pointing at. Prompted by "it says targetting, melee, but when I press the arrow keys it does not tell me what I am currently selecting." They look like a pair and are not, which is the whole shape of the fix. Throw has a real free-roaming cursor on level.cursorX/cursorY, so its descriptor is ingame_observe plus one clause: whether the tile is a legal target. That clause is recomputed from level.FoV, level.interactableArea and level.canThrowOnCell rather than read off the state's targetAllowed upvalue, because ingame_targeting_throw.lua:228 sets targetAllowed false for the whole 0.3s cursor glide and only the animation's onFinish restores it -- and mid-glide is exactly when we speak, so it would have said "blocked" on every single move. The same class of trap as the examine-cursor popup lag, and the same answer: read the model, not the view. Melee has no cursor and no target state at all. ingame_targeting_melee.lua:184-195 takes one direction key and fires the callback in that same keypress, so nothing is ever "currently selected" and there is no focus for a read() to return. Its descriptor speaks only on entry, listing the eight adjacent tiles -- which are precisely the legal targets, the game's rule being Chebyshev <= 1. Arrows still commit immediately; the game plays as it did. A two-step confirm cursor was considered and rejected for that reason. That entry line is surroundings.scan()'s sentence, so scan() splits into describeNeighbours() returning the text and scan() speaking it. onOpen grows the ability to be a function rather than a fixed string, since the neighbours differ every time. menus.selfTest needed a branch for a descriptor with neither read nor probe -- melee is the first -- or it would index a nil probe and take the whole self test down with it, which is the one report that must never fail quietly. Neither mode is reachable by its key in the prologue: b is filtered out by the room's level.allowedActions, and t falls through to gotoInventory() when there is nothing throwable. Found that by writing the testbed block as keypresses and watching it land in the inventory. It now drives both states directly, borrowing levelWindow, hpbar and levelDescriptionWindow off the ingame state's upvalues the way gotoAction would pass them. 129 testbed checks, 0 failures. The throw block asserts the focus text CHANGED across a cursor move rather than merely being non-nil, which is the assertion that would have caught the targetAllowed mistake had it been made. Still unverified against real content: only "can throw" has been heard, not "blocked", "out of range" or "no line of sight". 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.