Add AI-upscaled critter/object art as a new MDL mod type
build / build (push) Successful in 3m36s

Extends the MDL system beyond text overrides: bitmaps/<label>.json
names a model/scale and resource list, and mdlp extracts each
resource's frames, runs them through an ONNX Runtime CPU upscaler
baked into mdlp-image, re-quantizes to the game's palette, and writes
the result back - same build-time pipeline as message overrides.

Adds animgallery, a standalone viewer that renders any data
directory's animated resources as an HTML/GIF gallery with a
checkbox-driven MDL JSON generator, and -only-changed to preview just
what a mod overrides against the base game.

Fixes a real data race in hacked's ChangeNotifier.hashAll() (found via
go build -race causing non-deterministic resource counts), via a new
numbered patch rather than editing the vendored source.

Adds engine-patches/, a general-fixes counterpart to
android/engine-patches/ now staged and applied to the desktop builds
too (previously unpatched): a real GL_UNPACK_ROW_LENGTH stride bug, an
audio error-logging improvement, and two critter-rendering fixes -
mod art was losing to the base game's own re-opened resource files,
and critters rendered at the wrong size/position once that was fixed,
both from how the billboard renderer derives on-screen size and
placement straight from bitmap pixel dimensions.

Updates README.md and AGENTS.md to document engine-patches/.
This commit is contained in:
ml
2026-09-27 20:52:35 +02:00
parent 389abd7de7
commit ab2b778f44
25 changed files with 2009 additions and 35 deletions
+53 -10
View File
@@ -23,13 +23,13 @@ repository.
of `hacked/` at build time (same pattern as the root project's
`android/engine-patches/`, see the repository root's
[AGENTS.md](../AGENTS.md) section 6) - `hacked/` itself is never edited
in place.
in place. See section 1.1 for what each patch does.
- `sqweek-dialog/` - `github.com/sqweek/dialog`, `hacked`'s native
file-dialog dependency. Vendored at the exact version `hacked/go.mod`
would otherwise pull from the module proxy (ISC License), so it can be
patched the same way as `hacked/` itself (see section 2's crash fix).
patched the same way as `hacked/` itself (see section 1.1).
- `sqweek-dialog-patches/` - patches for `sqweek-dialog/`, same pattern as
`hacked-patches/`.
`hacked-patches/` (section 1.1).
- `mdlp/` - the **Mod Definition Language Processor** (section 4). First-party
Go source, not vendored - edit it directly, no patch system needed.
- `ss-specs/` - [InkyBlackness ss-specs](https://github.com/inkyblackness/ss-specs),
@@ -63,6 +63,40 @@ support (level/resource files, `res/data/`); this folder is about the
external tools that create and inspect that content, not about changing the
engine itself.
### 1.1. Patch reference
`src/hacked-patches/` and `src/sqweek-dialog-patches/` (applied to scratch
copies of `src/hacked/` and `src/sqweek-dialog/` respectively) are both
plain, numbered patch files applied in order at build time - neither
vendored source is ever modified in place. What each one does:
`src/hacked-patches/`:
- **`01-use-patched-dialog.patch`** - adds a `go.mod` `replace` directive
pointing `github.com/sqweek/dialog` at the local, patched
`../sqweek-dialog` instead of the upstream module, so `hacked` (and
anything else building against this source, such as `mdlp`/`animgallery`)
picks up the crash fix below.
- **`02-fix-hashall-race.patch`** - fixes a real data race in
`ss1/resource/ChangeNotifier.go`'s `hashAll()`: it hashes many resources
concurrently (one goroutine per ID) to detect what changed after a
modification, but only guarded the resource *lookup* with a mutex, not
the actual block-reading inside `hashResource()` - resources from the
same underlying file share a stateful reader, so concurrent unguarded
reads corrupted each other, non-deterministically. Found via `go build
-race` after `animgallery` produced a different resource count on every
run against the exact same input. The mutex now guards the whole hash
computation per resource, not just the lookup.
`src/sqweek-dialog-patches/`:
- **`01-xinitthreads.patch`** - adds `XInitThreads()` before `gtk_init()`
in the Linux backend. Without it, `hacked` segfaults the moment a native
GTK3 dialog (file/folder browse) opens while a GLFW/OpenGL context is
live: GLFW's own X11 backend installs a process-wide Xlib error handler
that conflicts with GTK's unless Xlib has been told up front that it
will be used from multiple threads.
## 2. Building `hacked`
Packages `dist/<version>.linux64.tgz` and `dist/<version>.win64.zip` (native
@@ -139,11 +173,16 @@ Rebecca Lansing's first email.
## 4. Mod Definition Language (mods/)
The workflow above is manual and its result (whatever you clicked through in
`hacked`) isn't checked into git. `mods/` holds the same kind of edits as
plain, reviewable JSON instead, and `mdlp` (the **Mod Definition Language
Processor**, `mdlp/`) turns them into the same kind of mod folder and a zip,
reproducibly and offline.
MDL is a small, declarative JSON format for describing a mod's content -
one file per piece of content (a message override, an upscaled sprite, and
so on), naming the game resource it touches and the values to set, rather
than the resource's actual binary data. `mdlp` (the **Mod Definition
Language Processor**, `mdlp/`) reads these files and produces the same kind
of mod folder `hacked` itself would save, reproducibly and offline. Since a
plain-text description is all that's checked into git, mods stay reviewable
and reproducible from the game's own data alone (see section 4.3) - unlike
the workflow in section 3, whose result only ever lives in whatever you
clicked through in `hacked`.
### 4.1. Layout
@@ -208,8 +247,12 @@ Needs the game's own data directory at `../res/assets/ss_ee/data` (see the
root [README.md](../README.md) section 3) as read-only reference data, so
overrides that touch only some fields of a message can inherit the rest.
Output lands in `dist/mods/<mod-name>/`: a `mod/` folder (the same shape
`hacked`'s own Project window Save produces) and `<mod-name>.zip`.
Output lands in `dist/mods/<mod-name>/mod/` (the same shape `hacked`'s own
Project window Save produces) for each mod, plus one combined
`dist/questshock-mods.zip` packaging all of them together. Nothing but
`mods/`'s own JSON/text files needs to be checked into git - the game's own
data (already required locally, already git-ignored) plus those files is
always enough to reproduce this output from scratch.
Test every built mod at once with `run-mods.sh` (Linux) / `run-mods.bat`
(Windows), copied into the root project's own `dist/`/`dist-win/` by