Getting Updates

Your folder is a snapshot. Nothing about your game — its code or its SDK — updates itself. This page is the whole model of how updates actually reach your disk, plus the one command that tells you the truth about what you're running.

GitHub's main is not your main

When a change merges on GitHub (a teammate's PR, an agent's PR, a BodyLink SDK re-pin), it changes GitHub's copy of the repo. Your local clone is the snapshot you took the last time you cloned or pulled — and it stays exactly that snapshot until you ask for more. A merge never touches your disk. That's not a bug or a sync delay; it's how git works, and it's what lets you keep local edits without the world moving under you.

So when someone says "the fix is on main" and your folder doesn't have it: both statements are true. GitHub's main has it. Your snapshot doesn't. Yet.

The two-command update (game repos)

For a game repo cloned from GitHub, getting current is exactly two commands, run in the game folder:

git pull
        npm install
  • git pull brings your snapshot up to date with GitHub's main — including the package.json line that pins which SDK build your game uses.
  • npm install then downloads and installs whatever that pin names. A pulled package.json is still just text until you install; the SDK bytes land in node_modules only on this step.

Neither happens by itself, and neither replaces the other.

The truth-check: npm ls bodylink-platform

npm ls bodylink-platform

This reads what is actually installed in node_modules — the code your game really runs. Trust nothing else:

  • not the version you remember installing,
  • not package.json alone — that's what you asked for, not what you have,
  • not a green npm install — npm can satisfy a URL dependency from a stale lockfile resolution and report success while leaving the old bytes in place.

If npm ls bodylink-platform prints the version you expect, you're on it. If it doesn't, you're not — whatever anything else told you.

Updating a scaffold (no git upstream)

A project you scaffolded with create-bodylink-game has no GitHub upstream to pull from — you update the SDK pin directly.

Scaffolds on SDK 0.7.5 or newer ship a verified one-command upgrade:

npm run sdk:update

It resolves the current release-channel manifest (Stable by default — see SDK Channels), runs the install, then re-reads the installed version and refuses to pretend: if the install silently kept the old version, it exits non-zero and prints the exact recovery commands. Success is one line:

bodylink-platform <old> → <new> installed and verified

Older scaffolds (before sdk:update existed) use the raw install: read the channel manifest (<origin>/sdk/stable/sdk-manifest.json, falling back to beta and then the legacy top-level /sdk/sdk-manifest.json until the first Stable promotion exists), take its tarball field, and install it — the filename is not guessable, always read it from the manifest:

npm install <origin>/sdk/<tarball-from-manifest>
        # e.g. npm install <origin>/sdk/bodylink-platform-0.7.5.tgz

Then run the truth-check. Always.

When the update didn't take: the recovery block

Symptom: you installed, but npm ls bodylink-platform still shows the old version. Cause: npm reused a stale lockfile/URL-dependency resolution. Fix: delete both caches of that decision and reinstall:

rm -rf node_modules package-lock.json
        npm install
        npm ls bodylink-platform

(Windows PowerShell: Remove-Item -Recurse -Force node_modules, package-lock.json.)

On a scaffold with npm run sdk:update, you don't have to memorize this — verification failure prints exactly this block, with the install line pinned to the exact target tarball, and ends by telling you to re-run sdk:update to re-verify.

dev:hosted tells you when you're behind

You don't have to poll for updates. Every npm run dev:hosted boot compares your installed SDK against the live release-channel pointer (when online) and, if you're behind, prints a boxed notice naming the exact upgrade command — npm run sdk:update where the scaffold has it, the raw npm install <origin>/sdk/<tarball> line where it doesn't. The check never blocks or fails your dev session: offline it skips with a single dim line, and BODYLINK_SDK_UPDATE_CHECK=0 turns it off entirely.

Related pages