Accessibility ModandClaude Opus 5
e57350ded3
Establishes the mod skeleton and gets speech working end to end. Game-file footprint: one line in main.lua. - accessibility/init.lua: sole entry point. Patch registry, hooks states.switch (announces screen changes) and states.update (per-frame speech flush, avoiding an edit to love.update). Startup self-test prints what resolved -- the canary for when a future game version moves something we hook. - accessibility/speech.lua: TTS wrapper. pcall-guarded so a missing DLL degrades to silence instead of crashing. Queues utterances within a frame and joins them, since one game turn emits several console.print calls and speaking each with interrupt would leave only the last audible. - accessibility/stateNames.lua: spoken names for the 28 states. - accessibility/vendor/love2talk: vendored TTS library, see VENDORED.md. Loads Tolk.dll by absolute path via love.filesystem.getSource() and adds that directory via SetDllDirectory, so the DLLs live in the project instead of needing an elevated copy into Program Files. Verified with lovec against NVDA: TTS available, speech channel yes, 'Main menu' spoken on startup. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
95 lines
5.1 KiB
Markdown
95 lines
5.1 KiB
Markdown
# SCRATCH — current working state
|
||
|
||
**Read this first on any handoff.** Living document: update it whenever state changes, before ending a turn.
|
||
|
||
Last updated: 2026-08-01 · Currently: **Phase 0, starting**
|
||
|
||
---
|
||
|
||
## What this project is
|
||
|
||
Blind-accessibility mod for *Sulphur Memories: Alchemist* 0.4.2 (LÖVE 11.5, Lua/LuaJIT), extracted to
|
||
`D:\code\Sulphur Memories Alchemist 0.4.2 sanctified`. All mod code lives under `accessibility/`.
|
||
Design goal: **change as little game code as possible** so the mod re-applies cleanly to new versions.
|
||
|
||
Full research is in `accessibility/docs/` — read `README.md` there for the map.
|
||
|
||
---
|
||
|
||
## Confirmed decisions (do not relitigate)
|
||
|
||
| # | Decision |
|
||
|---|---|
|
||
| D1 | Dev uses system LÖVE at `C:\Program Files\LOVE\` (`lovec.exe` for console output). Distribution deferred. |
|
||
| D2 | Tracker hierarchy: category (`Ctrl+PgUp/Dn`) → kind (`PgUp/Dn`) → instance (`Shift+PgUp/Dn`), `Home` = distance+direction. |
|
||
| D3 | **Small explicit patches** to game files are allowed where they simplify things — but every state descriptor also carries a `probe` spec so we can flip to zero-edit `debug.getupvalue` mode if the game ships fused on Steam. `render` is shared by both backends. |
|
||
| D4 | Six tracker categories confirmed and coverage-verified: Creatures / Items / Exits / Interactables / Terrain features / Alchemy. |
|
||
| — | Screen reader: **NVDA**. Running the game via `lovec` during dev is approved. |
|
||
| — | User is blind — all verification must be describable in text; don't rely on screenshots. |
|
||
|
||
## Still-open questions (in `04-open-questions.md`)
|
||
|
||
Q3 verbosity (relay vs augment) · Q4 console auto-speak policy · Q5 wall-tone triggers ·
|
||
Q6 keybinding integration vs separate · Q8 full keyboard audit as deliverable?
|
||
|
||
None block Phase 0. Q4 lands in Phase 1, Q5 + verbosity in Phase 2.
|
||
|
||
---
|
||
|
||
## Key facts worth not rediscovering
|
||
|
||
- **`console.print(msg, colorTemplate)`** in `modules/console.lua` is the *single* chokepoint for all game log text. Repeated identical messages coalesce into `"msg (x3)"` via a `times` counter. Buffer entries expire after 3s — useless as history, so we keep our own.
|
||
- **`level.getCursorMessage()`** returns the description under the examine cursor (actor first, then top visible tile). The game already has a full arrow-key examine mode: `states/ingame_observe.lua`.
|
||
- **`cursorPopup.set(...)`** — patching `views/inventoryCursorPopup.lua` + `views/levelCursorPopup.lua` narrates focus in `inventory`, `craft`, `refine`, `trade`, `ingame_observe` at once.
|
||
- **All 28 states already implement `keypressed`.** The gap is narration, not reachability.
|
||
- **`modules/tile.lua:234`**: `tile.tryInteract = (self.loot or self.tryInteractFunction) and function...` — authoritative "player can do something here" flag. Basis of tracker classification.
|
||
- **Template counts:** 231 tiles, 40 actors, 344 items. Parent inheritance is *already flattened* by `modules/tile/preprocess.lua` during `love.load`, so read fields directly.
|
||
- **6 un-nameable mechanical templates to exclude:** `blank`, `throw_blocker`, `movement_blocker`, `fire_detector`, `wall_features_position_dummy`, `ladder_down_hidden`.
|
||
- **`debug.getupvalue` works** on this Lua build — verified reading `selectedOption` / `optionsList` from a state's `keypressed`.
|
||
- **Tolk constraint:** `ffi.load("Tolk")` uses the OS loader, so DLLs must sit next to `love.exe` — they can *never* live inside a `.love` archive.
|
||
- `tolk.lua` calls `Tolk_Load()` at require time with no error handling, and `Love2talk.lua` leaks `backend` as a global. Always `pcall` the require.
|
||
|
||
---
|
||
|
||
## Current status
|
||
|
||
### Done
|
||
- Full architecture research → `docs/01-architecture.md`
|
||
- Hooking strategy → `docs/02-hooking-strategy.md`
|
||
- Phased plan → `docs/03-implementation-plan.md`
|
||
- Open questions → `docs/04-open-questions.md`
|
||
- Decisions + category coverage proof → `docs/05-decisions.md`
|
||
|
||
### In progress — Phase 0 (bootstrap)
|
||
Tasks #1–#5 in the task list. Nothing implemented yet; no game files modified yet.
|
||
|
||
### Next after Phase 0
|
||
Phase 1 = console history + speech + review keys. Highest value, lowest risk.
|
||
|
||
---
|
||
|
||
## Invariants for all mod code
|
||
|
||
1. Every wrapper calls through to the original and returns its results verbatim (`return realFn(...)` — preserve multiple returns).
|
||
2. Speech must never throw. Missing DLL ⇒ silent no-op, game still runs.
|
||
3. No behaviour change for sighted players.
|
||
4. Never reveal information outside `FoV` / `rememberedFoV` — the tracker must not become a cheat.
|
||
5. Grid scans (`xMax × yMax`) happen on keypress or turn change, never per frame.
|
||
6. Our keys fall through to the game handler unless we own them.
|
||
|
||
---
|
||
|
||
## Modified game files (keep this list exhaustive)
|
||
|
||
| File | Change | Why |
|
||
|---|---|---|
|
||
| *(none yet)* | | |
|
||
|
||
---
|
||
|
||
## Scratchpad / notes
|
||
|
||
- `.luacheckrc` uses `std = "min+alch"` with an explicit globals list — add mod globals there to keep lint clean.
|
||
- Upstream quirk (not ours to fix): `modules/tile/preprocess.lua` flattens parents in a single `pairs()` pass, so a grandchild may inherit from a not-yet-flattened parent depending on hash order.
|
||
- Tolk DLL sources on this machine: `D:\code\cafe`, `D:\code\dragonrpg-mapmaker`, `D:\code\DragonWarriorAccess`.
|