alchemist-accessibility/accessibility/docs/scratch.md

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 complete. Phase 1 next.

---

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

Done — Phase 0 (bootstrap) · commit 5c581ed

• git init, pristine tree committed and tagged vanilla-0.4.2 (commit bbb70d0, 1838 files, accessibility/ deliberately excluded so the tag is genuinely clean).
• love2talk vendored to accessibility/vendor/love2talk/ — see VENDORED.md there for the five local modifications.
• DLL elevation problem solved. Tolk.dll etc. live in accessibility/lib/ and are loaded by absolute path via love.filesystem.getSource(), with SetDllDirectoryA pointing at that folder so Tolk can find its own screen-reader clients. No admin rights, no copying into Program Files. Tracked in git via a !accessibility/lib/*.dll un-ignore.
• accessibility/speech.lua — pcall-guarded, frame-queued, logToConsole = true.
• accessibility/init.lua — patch registry + states.switch / states.update hooks
  • startup self-test.
• accessibility/stateNames.lua — spoken names for all 28 states.
• One line added to main.lua. Nothing else in the game touched.

Verified working via lovec.exe .:

[accessibility] TTS initialised
[accessibility] TTS: available
[accessibility] speech channel: yes
[speech]! Main menu

Next — Phase 1: console history + review keys

Wrap console.print, keep our own unbounded history (the game's expires after 3s), mirror its (x3) coalescing, add review keys. Needs Q4 answered (auto-speak policy) but a sensible default can ship first.

---

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
main.lua	+1 line: require("accessibility").initialize() after console.prepare()	Sole mod entry point. Placed there because templates, keybindings, states.setup() and the console canvas are all ready by then, and it's before the first states.switch().

Verify this list is exhaustive at any time with:

git diff --stat vanilla-0.4.2 -- . ':!accessibility' ':!.gitignore'

Currently: main.lua | 1 +.

How to run

cd "D:/code/Sulphur Memories Alchemist 0.4.2 sanctified"
"C:/Program Files/LOVE/lovec.exe" .

lovec (not love) gives the console, where [speech] lines mirror every utterance — speech is verifiable from the log, not only by ear. ! after [speech] means the utterance interrupted.

---

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.