Signs the player in, keeps the game up to date, and starts it.
The game itself has no login screen — this is what replaced it. The launcher
authenticates against wcauthserver, writes the session into the game's
profile.toml, and starts the game pointed at a data directory that survives
updates.
┌──────────────────────────────────────────┐
wc-launcher ──▶│ wcauthserver (identity only) │
│ │ POST /api/v1/auth/login → session │
│ │ GET /api/v1/keys → authkeys │
│ └──────────────────────────────────────────┘
│
│ ┌──────────────────────────────────────────┐
├────────▶│ s3.wyvencraft.com (no account) │
│ │ releases/game/index.json → catalogue │
│ │ releases/game/<tag>/… → the build │
│ └──────────────────────────────────────────┘
│
├─ writes <data>/profile.toml the session the game restores
├─ writes <data>/authkeys.toml so hosting works
└─ spawns <versions>/<tag>/wyvencraft
cwd = the version dir (finds assets/)
WYVEN_DATA_DIR = <data> (finds saves/)
The launcher opens on the home screen whether or not anyone is signed in, and a
build already on disk plays straight away. Playing signed out means singleplayer
only — the game enforces that itself, greying out its Multiplayer button and
refusing the connect path on the same can_play_multiplayer check.
An account buys exactly one thing: playing with other people. Builds are
published to a public catalogue on s3.wyvencraft.com, so installing and
updating need no account and no account server — a player who has never signed
in can download the game and play it, and the update check keeps working while
wcauthserver is down.
That is also why the update check works while the game is running. The one rule that matters then is that the launcher must not touch the refresh token, and reading a public catalogue does not. Installing still refuses, because it replaces a version directory the running game has open.
The launcher signs in; it never signs up. Accounts are created at wyvencraft.com.
Everything lives under one root — ~/Library/Application Support/Wyvencraft
on macOS, %APPDATA%\Wyvencraft on Windows, ~/.local/share/Wyvencraft
otherwise:
launcher.json launcher settings (account server, log filter)
profiles.json the player's profiles, and which one is selected
versions/<tag>/ an installed build: the wyvencraft binary plus assets/
data/ the game's WYVEN_DATA_DIR
saves/ profile.toml authkeys.toml ops.toml
logs/ launcher.log, game.log
runtime/moltenvk/ the Vulkan driver the launcher installs on the game's behalf
launcher-update/ a downloaded launcher, until it replaces the running one
versions/ and data/ are separate on purpose: applying an update replaces a
whole version directory, so nothing that must survive one may live inside it.
runtime/ and launcher-update/ are outside it for the same reason.
The game agrees with this layout — its src/paths.rs resolves the same default,
so starting it by hand finds the same worlds.
There is no index of what is installed. versions/ is the record: each build
carries a .wyvencraft-tag file naming the release it came from, because the
directory name is a sanitised tag and that sanitising is lossy. A build removed
by hand simply stops being listed, with nothing left to fall out of sync.
A profile is a name bound to a version. Latest is built in, is the default, and cannot be renamed or deleted — it always runs the newest release, and while it is selected the launcher will not start an older build: the Play button becomes Update & Play until the newest one is installed.
That force is deliberately gated on knowing. If the account server cannot be reached, the newest release is unknown, and an unknown release must never become a locked door — an offline player still gets to play the build they have.
Any other profile is pinned to one release and never updates itself. All
profiles share the same data/, so saves are common to all of them: a profile
chooses a build, not a world. A pinned build is never deleted to make room for a
newer one, and deleting a profile leaves its build on disk.
wails3 dev # hot reload, both sides
wails3 task build # -> bin/Wyvencraft
wails3 task package # -> bin/Wyvencraft.app (host arch)
wails3 task darwin:package:universal # -> bin/Wyvencraft.app (arm64 + amd64)
go test -race ./internal/...go-task need not be installed separately; wails3 task runs the same targets.
Set the account server in Settings, or write it directly:
echo '{"authUrl":"http://localhost:8080"}' \
> ~/Library/Application\ Support/Wyvencraft/launcher.jsonOnly sign-in goes there. Builds come from the catalogue either way, so a local
server with no release configuration is fine — updates_enabled: false on
/healthz is expected and the launcher never reads it.
Point the launcher at a different catalogue with WCL_CATALOG_URL, which is an
environment variable rather than a setting on purpose: changing the account
server changes who you are and invalidates the session, and neither is true of
where the builds are read from.
WCL_CATALOG_URL=http://localhost:9000 ./bin/wc-launcherReleases lag the game repo. To exercise the whole launch path against a build from a checkout rather than a download:
cd ~/Developement/wyvencraft && cargo build --release
mkdir -p /tmp/wc-devgame && cp target/release/wyvencraft /tmp/wc-devgame/
cp -R assets /tmp/wc-devgame/
WCL_DEV_GAME_DIR=/tmp/wc-devgame ./bin/wc-launcherSkipped by default so go test ./... stays hermetic. They sign in against a
real account server, read the real catalogue, and download a real release:
WC_IT_AUTH_URL=http://localhost:8080 \
WC_IT_USERNAME=someone WC_IT_PASSWORD=... \
WCL_DEV_GAME_DIR=/tmp/wc-devgame \
go test ./internal/services/ -v| Package | What it owns |
|---|---|
internal/paths |
The directory layout above. Must agree with the game's src/paths.rs |
internal/profiles |
profiles.json: the profile list and the selection. Not internal/profile |
internal/wcauth |
The account-server client: login, refresh, logout, keys. No downloads |
internal/profile |
profile.toml and authkeys.toml — the handoff to the game |
internal/catalog |
The published catalogue on s3.wyvencraft.com: what exists, and where |
internal/install |
Asset selection, resumable download, checksum, unpack, prune |
internal/selfupdate |
The launcher's own update: GitHub releases, staging, the swap |
internal/version |
Which build this is, stamped in by the release workflow |
internal/gamesvc |
Child environment, Vulkan discovery, spawn, stderr streaming |
internal/markdown |
Release notes → HTML, with raw HTML dropped |
internal/services |
The four objects the frontend calls, and the session rules |
The game comes from the catalogue on s3.wyvencraft.com. The launcher does
not: this repository is public, so it reads its own releases straight from the
GitHub API. Two independent paths on purpose — a launcher too old to sign in is
exactly the one that has to be able to replace itself, and it must not depend on
the object store being configured correctly to do so.
It checks once at startup and offers a strip on the home screen. Download
fetches the release asset, verifies its SHA-256, unpacks it into
launcher-update/, and checks that the bundle is signed by team S6EF64ZEMD
before going anywhere near the installed copy — TLS and the checksum prove the
bytes came from GitHub intact, and the signature proves GitHub was serving ours.
Restart to update hands over to the downloaded build. A process cannot
replace itself, so the new launcher does it: it starts with --apply-update <target> <pid>, waits for this one to quit, copies itself into place with
ditto, and reopens. The copy lands beside the target first, so a failure never
leaves the Applications folder without a launcher in it.
Neither step runs while Wyvencraft does. The rules below are why.
Publish a GitHub release and .github/workflows/release.yml does the rest: it
builds a universal .app, signs it with the Developer ID certificate, notarizes
it, staples the ticket, and attaches
wc-launcher-<tag>-macos-universal.zip plus its .sha256 to the release.
gh release create v0.2.0 --generate-notesThe tag is what the launcher compares itself against, and the workflow stamps it
into internal/version/VERSION before building. A local build says dev and
never offers to update itself.
Six repository secrets, all macOS signing:
| Secret | What |
|---|---|
MACOS_CERT_P12 |
base64 of the exported Developer ID Application .p12 |
MACOS_CERT_PASSWORD |
its export password |
MACOS_SIGN_IDENTITY |
Developer ID Application: … (S6EF64ZEMD) |
APPLE_API_KEY_P8 |
base64 of the App Store Connect .p8 |
APPLE_API_KEY_ID |
that key's id |
APPLE_API_ISSUER_ID |
the issuer id |
The workflow runs only on release: published and workflow_dispatch, both of
which execute in this repository's own context. Do not add a pull_request
trigger: this repository is public, and that would hand the signing key to
anyone who opens a fork PR.
The refresh token is stored once. It lives in the game's profile.toml and
nowhere else. Rotation is destructive and single-use, so a second copy would
inevitably become a stale one, and presenting a spent token revokes every
session for the account.
The launcher touches no token while the game runs. The game refreshes the
same family; two concurrent refreshes read as reuse server-side and sign the
player out everywhere. services.ErrGameRunning enforces this, and the session
is re-read from disk once the game exits.
The game renders through MoltenVK, and nobody should have to install Homebrew to
play a game. The launcher installs the driver itself: internal/deps downloads a
pinned, checksummed build into runtime/moltenvk/<version>/ beside versions/,
alongside the game and again at launch if it turns out to be missing. Roughly
3 MB, and invisible unless the connection is slow enough to want a progress bar.
internal/gamesvc then points the child at it with VK_ICD_FILENAMES,
VK_DRIVER_FILES and DYLD_LIBRARY_PATH, preferring, in order: whatever the
launcher's own environment already sets (a developer's shell), a MoltenVK/
directory inside the build, the launcher-managed copy, Homebrew, /usr/local,
$VULKAN_SDK.
DYLD_LIBRARY_PATH is the one that matters. vulkano tries libvulkan.dylib,
libvulkan.1.dylib and then libMoltenVK.dylib, so it reaches the driver with
no Vulkan loader installed at all; the ICD manifest is written beside the dylib
for the case where a loader is present and gets there first. Both are set, and
they land on the same driver either way.
The version is pinned in internal/deps/deps.go and the archive is published by
.github/workflows/moltenvk.yml under its own deps/moltenvk-<version> tag —
not a launcher release, because the driver changes on its own schedule. Bumping
it means running that workflow and pasting back the checksum it prints.
Only if all of that fails does the launcher refuse to start the game, which is still more useful than a crash inside the loader.
MIT — see LICENSE.
The launcher is the thinnest of the four pieces and there is nothing here worth
protecting: it signs you in, downloads a release, and starts the game. The
game and engine are MIT OR
Apache-2.0; the game's assets and the Wyvencraft name are not — see that
repository's assets/LICENSE and TRADEMARK.md. The auth server
is private, and its Docker image ships under its own terms.