alchemist-accessibility/accessibility/docs/00-dev-setup.md

# Development setup

How to get from nothing to a tree you can run, test and publish from. The
arrangement is a little unusual, because the mod lives inside a copy of a
commercial game that must never be published.

**If you are already set up**, the only things you need daily are
[Everyday commands](#everyday-commands) and [Publishing](#publishing).

---

## The two trees

This repository exists in two forms, and the same `CLAUDE.md` ships in both, so
check which one you are in:

| | **Development tree** | **Standalone mod repo** |
|---|---|---|
| Contents | The whole extracted game (1838 files) **plus** `accessibility/` | `accessibility/` and the docs only |
| Beside `accessibility/` | `main.lua`, `states/`, `models/`, … | nothing |
| Can you run the game? | Yes | **No** |
| Can you run the testbed? | Yes | **No** |
| Remote | **None, deliberately** — see [Publishing](#publishing) | `code.iamtalon.me/talon/alchemist-accessibility` |
| Where it comes from | You build it, below | Generated from the dev tree by `publish.sh` |

The standalone repo is **derived, never developed in directly**. Every publish
rewrites its history from scratch, so any commit made there is destroyed on the
next publish. Always work in the development tree.

Everything outside `accessibility/` in the dev tree is the vanilla game: read-only
reference material. You read it to find out how the game works; you patch it only
where the docs sanction, which currently means exactly one line.

---

## What you need

| | Why | Notes |
|---|---|---|
| **The game, 0.4.2, as an extracted source folder** | The thing being modded | A directory containing `main.lua` and `conf.lua`. **Not** a packed `.love`, **not** the Steam build — see below. |
| **LÖVE 11.5** | Runs the game | `conf.lua` pins `t.version = "11.5"`. Installed here at `C:\Program Files\LOVE\`. Use **`lovec.exe`**, not `love.exe`. |
| **Standalone Lua 5.4** | Unit tests and syntax checks without launching the game | `lua` and `luac` on PATH. |
| **A screen reader, or nothing** | To hear the output | Tolk drives NVDA / JAWS / System Access and falls back to SAPI 5. Dev here uses **NVDA**. Speech is also mirrored to the console, so you can verify from a log with no reader running at all. |
| **`uv` (for `uvx`)** | `git-filter-repo` at publish time | Only needed when publishing. |

Optional: `luacheck`. `.luacheckrc` is configured (`std = "min+alch"` with an
explicit globals list) but the linter is not currently installed — `luac -p` is
what actually gets run.

### Why the game must be an extracted folder

`ffi.load("Tolk")` goes through the **OS** loader, not LÖVE's virtual filesystem,
so the TTS DLLs must exist as real files on disk. They can never live inside a
`.love` archive. This is also why the mod loads them by absolute path via
`love.filesystem.getSource()`. See `accessibility/vendor/love2talk/VENDORED.md`.

---

## Building the development tree from scratch

**1. Extract the game** into a working directory. This tree lives at
`D:\code\Sulphur Memories Alchemist 0.4.2 sanctified`.

**2. Commit the pristine game and tag it**, *before* adding any mod code, so the
baseline is genuinely clean:

```
git init
git add .
git commit -m "Vanilla Sulphur Memories: Alchemist 0.4.2"
git tag vanilla-0.4.2
```

The tag holds 1838 files and **no `accessibility/` directory**. That is the whole
point of it: it is what makes the footprint check below trustworthy.

**3. Add `accessibility/`** — copy it in, or clone the standalone repo and move
its `accessibility/` folder into place.

**4. Add the one line to `main.lua`.** In `love.load()`, immediately after
`console.prepare()`:

```lua
require("accessibility").initialize() --ACCESSIBILITY MOD: sole entry point
```

`accessibility/publish/install.patch` applies exactly this. The placement is not
arbitrary: by that point templates are preprocessed, keybindings are loaded,
`states.setup()` has run and the console canvas exists — and it is still before
the first `states.switch()`.

**5. Check the TTS DLLs survived the copy.** `accessibility/lib/` must contain
`Tolk.dll`, `nvdaControllerClient64.dll` and `SAAPI64.dll`.

⚠ `.gitignore` has a blanket `*.dll` with a deliberate `!accessibility/lib/*.dll`
un-ignore. If you ever restructure that folder, the DLLs will silently stop being
tracked and the mod will be mute for anyone who clones it.

**6. Verify.** Run the [everyday commands](#everyday-commands). A working setup
prints, at startup:

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

`speech channel: NO` means the DLLs loaded but nothing is listening — start a
screen reader, or expect SAPI.

---

## Everyday commands

Run all of these after any change. The testbed in particular: it has caught
essentially every bug in this project, and a change that looks obviously correct
is exactly the kind that fails it.

```
cd "D:/code/Sulphur Memories Alchemist 0.4.2 sanctified"

lua accessibility/tests/test_history.lua     # pure Lua, instant
luac -p accessibility/*.lua                  # syntax only, no LOVE needed

bash accessibility/tests/run-testbed.sh      # ~4 min — save-safe, see below

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

The last one **must** print `main.lua | 1 +`. That is the invariant that keeps the
mod cheap to lift onto a new game version.

**What matters in the testbed run is `0 failures`, not the check count**, which
varies between runs because several blocks are conditional.

To just play it:

```
"C:/Program Files/LOVE/lovec.exe" .
```

### Save data

LÖVE writes to `~/AppData/Roaming/LOVE/Alchemist` (`t.identity = "Alchemist"` in
`conf.lua`). The testbed scenario assumes a fresh save and will not navigate
correctly without one — it drives a new game from the main menu through the
prologue, which has already happened in any real save.

**Do not clear that directory by hand.** It holds the player's actual
playthrough, and `rm -rf` on it — which is what these docs used to say — destroys
it. Use `accessibility/tests/run-testbed.sh`, which:

1. **Moves** the save to `Alchemist.a11y-backup.<pid>` (never deletes it),
2. runs the testbed against the empty directory LÖVE then creates,
3. discards the test run's directory and moves the real save back, from an `EXIT`
   trap so this happens on failure, on a crashed run and on Ctrl-C too.

If the restore itself ever fails it says so loudly and leaves the backup on disk
rather than pressing on.

Why a wrapper and not something inside the mod: `love.load` calls
`config.initialize`, `keybindings.initialize` and `user.initialize` long before
`main.lua` reaches `require("accessibility").initialize()`. By the time any of
our Lua runs, the save directory has already been read — the swap has to happen
around the process.

Override the interpreter path with `LOVE=/path/to/lovec.exe` if yours differs.

Runtime files the game also drops next to the source during dev (`config.json`,
`user.json`, `keybindings.json`, savegames) are already in `.gitignore`.

### Reading the console

`lovec.exe` gives a console window, and every utterance is mirrored there as a
`[speech]` line — so speech is verifiable from a log rather than only by ear:

| Prefix | Meaning |
|---|---|
| `[speech]!` | interrupted whatever was being said |
| `[speech]*` | urgent, spoken immediately (bypasses the frame queue) |
| `[speech] ` | queued normally |

### If something mysteriously does not speak

Read the **startup self-test**. It reports every patch and every descriptor probe.
Most menu narration reads the game's file-local variables via `debug.getupvalue`,
so a renamed local in a future game version shows up there as
`PROBE BROKEN: no upvalue 'x'` rather than as silence three screens in.
`ok (unset until opened)` is normal.

---

## Publishing

**The development tree has no git remote, and must not be given one.** It holds
all 1838 files of a commercial title. Pushing it anywhere would distribute the
game.

Publishing therefore means: rebuild a separate repository that contains only the
mod, and push *that*.

```
sh accessibility/publish/publish.sh
```

This clones the dev tree to `../alchemist-accessibility-publish` and runs
`git-filter-repo` over the clone with a single filename callback that does three
things at once: keeps only `accessibility/` and `CLAUDE.md`, lifts
`accessibility/publish/README.md` and `install.patch` up to the root (so a visitor
to the mod repo finds them where they expect), and drops the publish machinery
itself from the **whole history**.

All three being one filter is what makes the rewrite deterministic, and that is
worth more than it sounds — see [Why this is not a force-push](#why-this-is-not-a-force-push).

Then **the check that matters**: it lists every path in the rewritten history and
aborts if anything that is not the mod or its docs survived. A clean run says:

```
clean: history contains only the mod and its docs
```

If it says `ABORT: non-mod files present in history`, **do not push** — a game
file leaked through the filter.

The script prints the push commands and stops rather than pushing for you:

```
cd ../alchemist-accessibility-publish
git remote add origin https://code.iamtalon.me/talon/alchemist-accessibility.git
git push -u origin master
```

⚠ Paste those as **separate lines**. If a shell wraps the `remote add` line, the
URL ends up on its own and gets run as a command.

### Why this is not a force-push

`git-filter-repo` is deterministic: given the same input commits and the same
filter, it produces byte-identical output commits, because it preserves author
and committer timestamps and a commit's SHA is a function of its tree and its
parents. Verified by running `publish.sh` twice into different directories and
diffing `git rev-list --all` — all 24 SHAs identical.

So **a publish that only adds commits to the dev tree is a plain fast-forward**,
and pushes only the new objects. Git is content-addressed on top of that: the
bulk of the repo is the four wall-tone WAVs (~740 KB) and the Tolk DLLs
(~135 KB), and those blobs are keyed by content, so they are never re-uploaded
even when a rewrite does happen.

It used to be a force-push every time, for a reason worth not reintroducing. The
script ended with a `git rm -r accessibility/publish` and a `git commit`, and
that commit was created fresh with the *current time* on every run — so the tip
SHA changed even when nothing else had, and the old tip was a sibling of the new
one rather than an ancestor. It was also not achieving much: `git rm` only
removes a file from the tip, so `publish.sh` was still present in every older
commit of the published repo. Filtering it out instead fixed both.

**If the push is rejected as non-fast-forward, that now means something**: the
dev history itself was rewritten — an `amend`, a `rebase`, or a rebase onto a new
game version. `--force` is correct there, and the mod repo is derived output so
nothing is lost. But it should be a deliberate act, not the daily command. A
force-push you always run is a force-push you stop reading.

⚠ The corollary, unchanged: any commit made **directly in the published repo** is
destroyed by the next publish. Always work in the development tree.

---

## Rebasing onto a new game version

Commit the new pristine tree on top of the `vanilla-0.4.2` baseline, then replay
the mod commits. The only game-file conflict possible is the single `main.lua`
line. Then run the startup self-test and read it: it tells you immediately which
patches and probes the new version broke.