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, 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.