gen1recomp/docs/updater.md

Updater

A packaged build carries a fixed engine plus the game source it starts from, and that source is only ever the fallback. It ships in one of two shapes: fused (a game.love baked into the executable, so LÖVE reports love.filesystem.isFused() true) or unpacked (a source directory the launcher hands to the runtime, love <dir>, which is what every PortMaster-style port does and which reports isFused() false). On every launch, before anything else runs, Boot.run (src/update/Boot.lua) looks in the save directory's updates/ folder for a downloaded gen1recomp-X.Y.Z.love payload that is both strictly newer than the bundled engine version and runnable on this shell. If one qualifies, it is mounted over / (so its files win over the bundled source for every subsequent require) and chainloaded in place: the payload's main.lua and love.load run as if they had shipped in the executable. Nothing on disk is rewritten either way -- an update is a mount layered over the source -- so the handoff is sound for a fused archive and for an unpacked directory alike. Boot.canUpdateInPlace decides whether a build may update at all: a fused build always may, an unpacked build may when its engine is a released X.Y.Z, and a dev/source checkout never may (its engine is the "0.0.0-dev" placeholder, so the working tree always runs itself).

The pieces are deliberately layered so the risky part is small. Boot.select is a pure function (no love.* calls) that, given probed candidates and the bundled engine/shell, decides what to run and what stale payloads to delete. Boot.probePayload mounts one archive at an isolated mountpoint and reads its src/core/Version.lua with loadstring (never require, so it is never cached as a module) to learn its engine and minShell. Boot.run orchestrates the crash guard, enumeration, selection, and the mount + chainload, with full rollback on any failure. Checking for and fetching a new payload is a separate, slower path: src/update/Check.lua is a thin main-thread state machine the launcher screen polls, while the curl calls, JSON parsing, and sha256 verification run on a background love.thread (src/update/check_worker.lua) so a hung network call never blocks a frame.

Version.lua fields

src/core/Version.lua carries four fields the updater reads directly (the existing modApi, linkProtocol, saveFormat, and cache fields are untouched):

• engine - the semver release, e.g. "1.4.0". The repo default is the "0.0.0-dev" placeholder; CI stamps the real X.Y.Z into the packed game.love only, never the working tree. A "0.0.0-dev" engine always reports itself up to date (it never chases a release, and it never counts as a valid payload to chainload).
• shell - the native-shell contract this build's fused executable implements.
• payloadHost - the native host family an in-place payload targets. Ordinary LÖVE packages use "love". A specialized native package uses a distinct, stable identifier and accepts only payloads carrying that same identifier. A missing field defaults to "love", preserving compatibility with payloads released before this field existed.
• minShell - the lowest shell contract required to run this payload.

Bump minShell only when a payload needs something the currently-shipped native shell cannot provide, for example a LOVE version bump, a new required system binary, or a change to love.run itself (see Known limitations below). An older shell refuses to chainload a payload whose minShell exceeds the shell it provides; Boot.select keeps that payload in updates/ rather than deleting it, in case a future shell upgrade can run it, and Check's worker reports needs_full so the player is pointed at a full installer instead. Do not bump minShell for an ordinary Lua/data release; that is exactly the case the updater exists to avoid a reinstall for.

Change payloadHost only when the packaged Lua depends on a different native host family. This is separate from minShell: the host name answers which native integration the payload targets, while the shell number answers which revision of that integration it requires. A mismatched-host payload is never mounted or deleted as stale; the launcher directs the player to a full package.

Release assets

Each tagged release vX.Y.Z carries the existing per-platform archives (gen1recomp-X.Y.Z-macos.zip, -windows.zip, -linux-x86_64.AppImage, -linux-arm64.AppImage, -linux.flatpak, -android.apk, -ios.ipa, -switch.zip, Xbox and PortMaster archives) plus two assets the updater itself consumes:

• gen1recomp-X.Y.Z.love - the payload, matched by the exact pattern gen1recomp-<version>.love (see isPayloadName in Boot.lua and Check.parseRelease).
• sha256sums.txt - shasum -a 256 output (<hex> <filename>, bare filenames) covering at least the .love payload. Check.parseSums tolerates a leading * binary marker and a ./ prefix but expects the filename otherwise to match the asset name exactly.

A release missing either asset is treated as "no in-place update available": Check reports needs_full. It also selects the exact current platform asset from the same release and persists the requirement, so it is visible again on every launch, including offline launches.

Save-directory layout

Under the save directory (identity pokemon-love2d):

updates/gen1recomp-<X.Y.Z>.love                 downloaded payload(s)
updates/gen1recomp-<X.Y.Z>-sbc-portmaster.zip   downloaded port package (ports)
updates/pending.txt                             crash-guard marker
updates/full-update.json                        persistent native-package requirement

pending.txt holds the filename of the payload currently being chainloaded. Boot.run's chainload writes it immediately before mounting, and removes it on both a successful handoff and a clean rollback. If it is still present the next time Boot.run starts, the previous boot died mid-handoff, so that named payload is distrusted: it and the marker are deleted before candidates are enumerated. Boot may still fall back to an older valid payload, or to the bundled game, in that case.

Update flow

1. Boot (every launch, packaged builds only): crash-guard check, enumerate and probe every updates/*.love, pick the highest engine that is strictly newer than the bundled one and whose minShell this shell satisfies, delete stale payloads, chainload the winner (or run the bundled game if none qualifies).
2. Check (launcher screen): Check.start() kicks off an async check against the GitHub releases API; safe to call every frame, it is a no-op once a check is in flight or has reached a terminal state. Check.state() reports idle | checking | uptodate | available | downloading | ready | needs_full | full_downloading | full_ready | error plus the latest version, download progress, and (when applicable) the selected full-package asset.
3. Download + verify: on available, Check.download() tells the worker to fetch the payload, polling the growing .part file for progress. On completion the worker re-fetches sha256sums.txt, verifies the payload's sha256, and probes it with Boot.probePayload to gate its minShell against this shell's shell. A verified, runnable payload is renamed into place and reported as ready; anything else reports error or needs_full and leaves updates/ clean.
4. Restart to apply: a ready payload just sits in updates/ until the player relaunches; the next launch's Boot step (1) is what actually mounts and runs it. There is no in-session hot-swap. A shortcut launched with --update (src/core/Prelaunch.lua, #1657) is the one path that does this without the launcher on screen: it runs steps 2-3 before bootGame, and on ready writes the one-shot launch_update.txt marker and restarts, so the fresh boot chainloads the payload in step 1 and then boots the game. The marker is consumed on that next launch, so a payload that will not apply cannot restart-loop the shortcut. needs_full is never acted on unattended; it falls through and boots the game.
5. Native-package requirement: when minShell or payloadHost is incompatible, the worker writes full-update.json and surfaces a persistent launcher control. Android downloads the release APK, verifies its SHA-256 entry from sha256sums.txt, then invokes Android's Package Installer. The installer asks the user for consent and enforces package, version-code, and signing-certificate compatibility. A legacy APK without the installer bridge links its full package for one manual bootstrap update, including when its downloaded payload already reports the latest engine version. iOS links the sideload repository for a re-sideload; Xbox and desktop builds link their correctly named full package. A PortMaster-style port has no browser to open a download in, so it fetches its own package (-sbc-portmaster.zip, -rg34xxsp-stockos64-mod.zip) into the save directory through the same verified download, and the player re-extracts it over the port folder — see linux-arm-sbc.md. Switch keeps its native OTA flow. Which package a port offers comes from the launcher's environment (POKEPORT_PORTMASTER, POKEPORT_RG34XXSP, with POKEPORT_HANDHELD honoured as a legacy fallback), which is what Check.hostPort() reads.

Known limitations

• love.run persists across handoff. By the time chainload runs, the bundled love.run has already returned its stepper to LOVE; redefining the global love.run from the payload's main.lua does not affect the loop already driving the frame. A payload that must change love.run itself needs a minShell bump so an older shell refuses to chainload it rather than running with half its intended behavior.
• Android and iOS use the native download bridge, not curl. Neither platform ships curl, so the old check_worker.lua path (shell out to curl) always landed on error and the launcher chip's "Check for updates" tap was a no-op. The worker now talks through HostShell, the same transport as the mod catalog: curl on desktop, love.system.httpDownload on mobile. On Android that is the GameActivity JNI/HttpsURLConnection bridge; on iOS it is GRPickerBridge.httpDownload (URLSession). A fused sideloaded APK or IPA can therefore check GitHub and fetch the .love payload in-app. If neither transport exists, the worker reports needs_full and the launcher chip opens Check.releaseUrl(). Native package-only changes still need a full reinstall (minShell / payloadHost gate → needs_full). Applying a downloaded payload on Android relaunches via love.system.restartApp; iOS still uses in-process quit("restart").
• Android full updates are user-confirmed and certificate-bound. The app uses a private FileProvider cache path plus Intent.ACTION_INSTALL_PACKAGE, checks Android 8+'s per-app "install unknown apps" setting, and never requests a silent install. The release job must use the original long-lived Android signing key; a new key causes Android to reject an in-place update and requires a one-time manual reinstall. See mobile/ANDROID.md.
• Dev/source runs never self-update. Boot.canUpdateInPlace is false for a working tree -- its engine is the "0.0.0-dev" placeholder, which also always reports up to date -- so Boot.run returns immediately and Prelaunch's --update shortcut refuses to act. A source checkout is always "the game" itself; updating it means pulling the repo.
• An unpacked port updates the Lua, not the runtime. The PortMaster SBC and RG34XXSP packages ship a fixed love.aarch64 runtime beside a lovegame/ source directory. A payload layers new Lua and data over that source, so a LÖVE version bump, a new required system binary, or a love.run change still needs a full port package: the minShell gate reports needs_full, the chip fetches the port package into the save directory, and the player re-extracts it over the port folder.
• Nintendo Switch does not use this LÖVE self-updater. On NX, Platform.networkValidated() is false, so Boot.run / Check never download .love payloads. In-console OTA uses the native OTA launcher (DEVKITPRO), documented in switch-install.md. Wire format: src/update/SwitchOta.lua. Manual zip install remains the fallback.