Updater

A fused build (love.filesystem.isFused() true) ships a bundled game.love baked into the executable, but that bundled copy is only ever the fallback. 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 fused 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. A dev/source checkout is never fused, so Boot.run no-ops there and 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.zip, -linux-arm64.AppImage, -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/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

Boot (every launch, fused 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).
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.
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.
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.
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. iOS links the sideload repository for a re-sideload; Xbox, desktop, and PortMaster builds link their correctly named full package. Switch keeps its native OTA flow.

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.run returns immediately when love.filesystem.isFused() is false, and a working tree's engine is the "0.0.0-dev" placeholder that always reports up to date, so a source checkout is always "the game" itself; updating it means pulling the repo.
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.

9.9 KiB Raw Blame History