Builds and shipping

Weld builds the game where it makes sense: a Windows package on the team’s Windows PC even when you’re on a Mac, smoke tests on any node with Unreal, and uploads to itch.io from wherever you run weld ship.

Local commands

Run these inside the game repo (the folder with the .uproject):

weld game engines                 # Unreal installs Weld can use
weld game build                   # compile the editor target (<Name>Editor)
weld game smoke                   # automation tests, headless, structured pass/fail
weld game smoke --screenshots     # also render offscreen and collect screenshots
weld game package                 # BuildCookRun for this machine's platform (Development)
weld game package --config Shipping --platform Win64
weld game open                    # open the project in Unreal Editor
weld game doctor --fix            # check and repair the Unreal MCP setup

Each platform builds only on its own OS: Win64 on Windows, Mac on macOS. Add --json for machine-readable results; packages go to <project>/.weld/out/package/<platform> unless you pass --out.

Smoke tests: agents verify their own changes

weld game smoke launches the game headless, runs its functional tests, optionally captures offscreen screenshots and returns structured results. The same thing runs as a game.smoke job on another node. The weld-build skill uses it so Claude can check a gameplay change itself instead of asking you to play. Projects made with weld game new come with test scaffolding and a debug and automation API (weld.* console commands and state JSON) for exactly this.

Use the smoke test as the project’s T1 gate so every merge is tested: weld node link --t1-command "weld game smoke". See Merge queue.

Shipping to itch.io

weld ship does package → smoke → zip → upload in one command:

weld ship init --itch <user>/<game>     # writes a commented .weld/ship.toml
weld ship butler --install              # itch.io's official upload tool, into Weld's tools folder
weld ship --channel windows --dry-run   # everything except the upload
weld ship --channel windows             # the real thing

• Remote builds. From a Mac, --channel windows packages Win64 Shipping on a Windows node through a build.package job, boot-checks the packaged game, zips it with a weld-ship.json (version, commit, build config, smoke result) and uploads it with butler to <user>/<game>:windows. --local and --remote override where it builds.
• Rehearsal by default. Until [itch] is configured in ship.toml, every weld ship is a dry run.
• Version labels come from [build] version, else git describe. Override with --version-label.
• Useful flags: --skip-package <archive> reuses a package (for example after a failed upload), --no-smoke, --allow-failing-smoke, --config Development, --json.

The summary prints the itch.io page. If it warns that “the build node packaged commit X but your checkout is at Y”, pull on the build machine and ship again.

.weld/ship.toml

[itch]
user = "pete"               # itch.io account or team
game = "skyforge"           # https://pete.itch.io/skyforge

[build]
config = "Shipping"         # Shipping (boot check) or Development (automation tests on the package)
maps = ["/Game/Maps/Main"]  # empty = project defaults
smoke = true
boot_secs = 20

[channels.windows]          # built from a Mac on a Windows node via jobs
project_path = "D:/jam/SkyForge"   # the checkout on that node

[channels.mac]

[video]
seconds = 45

The itch.io key

For uploads from your own machine, butler reads BUTLER_API_KEY from the environment (or uses butler login). For uploads from a build node, store the key as a project secret; it’s leased only to the upload job and passed to butler through its environment, never printed:

weld secret set BUTLER_API_KEY --kind shell     # paste the value at the prompt

Gameplay video

weld ship video                          # prints the plan and the ffmpeg command
weld ship video --record --seconds 45    # launches the last shipped build and records it

It records the screen with ffmpeg (on macOS, give your terminal Screen Recording permission). Game audio isn’t captured; add music in an editor, or record with OBS when audio matters.

Preparing a build machine

A build node needs Unreal Engine 5.8 and the build role. Joining with --roles build (or weld setup --roles build) checks for it: Weld installs and opens the Epic Games Launcher and prints the steps, because Unreal needs your Epic login. Then:

weld node caps            # should list Unreal 5.8
weld node role add build

Keep at least 100 GB free for packaging and the derived data cache; weld cache prune frees Weld’s own caches. Full walkthrough: Windows PC as a build and GPU node. For a deadline, read Jam day.