Accessibility ModandClaude Opus 5
7ce429c2fb
The setup is unusual enough to need its own page, and the facts were scattered across scratch.md, CLAUDE.md and publish.sh: the mod is developed inside a copy of a commercial game, so the dev tree deliberately has no remote and publishing means rebuilding a filtered repo and force-pushing that instead. docs/00-dev-setup.md covers the two-tree arrangement and which one you are in, prerequisites and why the game must be an extracted folder rather than a .love (ffi.load goes through the OS loader), building a dev tree from scratch including the vanilla-0.4.2 baseline tag and the one main.lua line, the everyday commands, the save location, reading the [speech] console and the startup self-test, and the publish flow with its leak check. Linked from CLAUDE.md and the docs index. No code change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
54 lines
2.7 KiB
Markdown
54 lines
2.7 KiB
Markdown
# 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](scratch.md) first.** It is the
|
||
living handoff document: current state, every bug found and why, and the traps.
|
||
|
||
| Doc | Contents |
|
||
|---|---|
|
||
| [scratch.md](scratch.md) | **Start here.** Working state, bugs found, gotchas, keymap, how to run the testbed. |
|
||
| [00-dev-setup.md](00-dev-setup.md) | **Setting up.** The two trees, prerequisites, building the dev tree, everyday commands, publishing. |
|
||
| [01-architecture.md](01-architecture.md) | How the game is built: states, console, level model, keybindings. |
|
||
| [02-hooking-strategy.md](02-hooking-strategy.md) | How the mod attaches with (near) zero edits to game files. |
|
||
| [03-implementation-plan.md](03-implementation-plan.md) | The original six-phase plan, with outcomes. |
|
||
| [04-open-questions.md](04-open-questions.md) | Questions raised; see 05 for answers. |
|
||
| [05-decisions.md](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
|
||
|
||
1. **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.
|
||
|
||
2. **The game already writes the text.** `console.print` is a single chokepoint
|
||
for all log messages; `level.getCursorMessage()` describes tiles;
|
||
`inventoryCursorPopup.set` covers four screens. Mostly we re-route existing
|
||
strings to speech rather than writing a description engine.
|
||
|
||
3. **Everything is a `require`d singleton, and `debug.getupvalue` works.** 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.
|