Buildsworn product page

Buildsworn: Getting started

This is the complete reference that ships with your license key and lives on adrenalinegames.pl. New to Claude Code or terminals? Start with the Quickstart (one action per step, first map and first gate in 30 minutes). Want to see how a game is actually built this way? The Cookbook: eleven recipes from our own production. Read this one once, top to bottom. It takes about 15 minutes to go from download to the first gated session.

1. What you bought

Buildsworn is a production pipeline for Unreal Engine 5 driven by Claude Code. It has three parts:

Part What it is Where it lands
MCP server (buildsworn.exe) 162 tools Claude can call: an API index of your engine (~300,000 classes, functions, properties, includes, deprecations parsed from the installed headers), code navigation, safe edits with backups, UBT compile, packaging, plugin validation, quality gates (gate_run, log_gate, ue_test_run, perf_gate), screenshots and game_visual_check, session state, project notes, release pipeline, optional PixelLab / Gemini / remote server modules C:\Program Files\Buildsworn\buildsworn\
Claude Code plugin 6 hooks (backup before every edit, no sed on C++, no base64 transfers, ask before kill/delete/restart, compile error digest, session brief), skills /start /gate /compile /release /session-start /session-end, agents ue-compiler-fixer, adversarial-qa, bp-reader, vault-librarian, patch-notes-writer installed into Claude Code from a local marketplace
Playbook The rules that keep an agent honest on a real game project, distilled from six shipped games C:\Program Files\Buildsworn\playbook\

One license key = one developer, up to 2 machines (desktop + laptop); Studio keys cover 5 machines of a company or team. The key is in the e-mail you got when you registered (Solo, free: get one here) or bought (Studio). The license never expires. Solo gets every update. Studio includes 12 months of updates; after that your installed version keeps working, and a renewal (bought with the same PayPal e-mail, no reinstall) unlocks new versions again. license_status shows the update window. No key yet? Leave the field empty in the installer: a free 7-day trial is activated for that machine (one trial per machine). A machine is identified by its Windows machine GUID and your Windows user name. Renaming the PC does not count; a Windows reinstall or a different user account does (support resets seats on request). The identifier is a one-way hash; we never see your hardware details. Lost the e-mail? The product page has "Lost your key?": it mails every key registered to your PayPal address. Digital product: no refunds after the key is issued, but support is included: if it does not work on your machine, write to us and we fix it with you. Full terms: https://adrenalinegames.pl/buildsworn-eula.html

2. Requirements

3. Install

  1. Run buildsworn-setup-<version>.exe. Windows SmartScreen may warn on first run (More info, Run anyway) until our code-signing certificate is in place; the SHA256 of every release is printed on the download page.
  2. Wizard pages:
    • Engine root and workspace. The engine root is the folder that contains UE_5.6, UE_5.7, UE_5.8. The workspace is where Buildsworn keeps plugins to package, build output, releases and notes (default C:\Users\<you>\buildsworn).
    • Project folders. Where your .uproject files live (default Documents\Unreal Projects). Several folders: separate with ;.
    • License and optional services. Paste your license key. PixelLab / Gemini keys are optional (links to get them are on the page) and can be added later. Right after install every key is checked with one small live request; the result is in install.log (gemini OK / INVALID / not set) and any time later by asking Claude to "call check_keys".
    • Claude Code plugin. Leave it checked. The MCP server is registered in Claude Code either way (claude mcp add, user scope); the plugin adds the hooks, skills and agents on top. Hooks run through buildsworn.exe itself: you do not need Python installed.
  3. The installer then runs the configuration step (a console window flashes for a few seconds). It writes %APPDATA%\buildsworn\config.json, installs the plugin and runs a health check. The log is at %LOCALAPPDATA%\buildsworn\install.log. Open it if anything looks off.
  4. In the background it starts building the Unreal API index: it parses the headers of your newest installed engine (about 3 minutes, ~120 MB in %LOCALAPPDATA%\buildsworn\api_index\). Ask Claude to "call ue_api_status" to see progress; other engine versions: "call ue_api_ingest 5.6". With the index, Claude checks every signature, #include and deprecation against your engine instead of guessing (ue_api_search, ue_api_signature, ue_api_include, ue_api_class, ue_api_deprecated).

4. Verify (2 minutes, do not skip)

The short way: open a terminal in any folder, run claude, type /start. It checks the server, the license, the keys, the API index, finds your project and tells you what to do next. The long way, if you prefer to see it yourself:

Open a new terminal (PATH changed) and run:

buildsworn --health

You should see your engine versions (-> 5.6, 5.7, 5.8), your project folders and license: key set. Then start Claude Code in any folder and type:

/mcp

buildsworn must be listed as connected. Ask Claude: "call license_status". Expected: LICENSED: seat 1/2, valid until <date>. If it says UNLICENSED, ask Claude to "call license_activate" and read the reason (typo in the key, no internet, seat limit). Installed without internet? The trial or activation could not run. Once online: buildsworn --trial (no key) or "call license_activate".

5. Your first session

No project at hand? C:\Program Files\Buildsworn\playbook\demo\BrainDemo is a minimal C++ project with one deliberate gap: copy it next to your projects, /session-start BrainDemo, /gate (FAIL on verify_funcs, exact file:line), ask Claude to implement ResetStats, /gate again (PASS). Five minutes, and you have seen the whole loop.

Open a terminal in your project folder (the one with the .uproject) and run claude.

  1. /session-start MyGame sets the current project and prints a briefing (empty the first time).
  2. Ask for something real, e.g. "add a stamina component to the player character, C++ only". Watch the hooks work: every edited file gets a .bak_<date> copy, sed on C++ is refused, taskkill asks you first.
  3. /compile builds through UnrealBuildTool (never Live Coding). Errors come back as file:line digests and, if you want, the ue-compiler-fixer agent loops compile-fix-compile until green.
  4. /gate runs the final gate: compile, function audit, Automation tests (if you pass a filter), the latest log scanned for Fatal / ensure / Failed to load, plus the read-back and screenshot rows. Claude is allowed to say "done" only while quoting that table. That is the whole point of the product.
  5. /session-end writes the state to disk so the next session starts with a briefing instead of scrolling history.

6. Configuration, done properly

Everything lives in one file: %APPDATA%\buildsworn\config.json. Environment variables override it (UE5_ENGINE_PATH, BUILDSWORN_WORKSPACE, VPS_HOST, GEMINI_API_KEY, PIXELLAB_API_KEY, BUILDSWORN_LICENSE_KEY). buildsworn --config writes a config.example.json next to it with every key.

{
  "engine_root": "C:\\Program Files\\Epic Games",
  "workspace": "C:\\Users\\you\\buildsworn",
  "project_roots": ["C:\\Users\\you\\Documents\\Unreal Projects", "D:\\Games"],
  "default_project": { "name": "MyGame", "path": "D:\\Games\\MyGame", "uproject": "D:\\Games\\MyGame\\MyGame.uproject" },
  "test_projects": { "5.8": "D:\\Games\\PluginHost58" },
  "vault_dir": "C:\\Users\\you\\buildsworn\\Vault",
  "aliases": { "~mygame": "D:\\Games\\MyGame" },
  "vps_host": "deploy@my-server.example", "vps_key_file": "C:\\Users\\you\\.ssh\\id_ed25519",
  "vps_services": { "my-backend": { "port": 3001, "dir": "/home/deploy/my-backend", "data": "data/app.db", "health": "/health" } },
  "gemini_api_key": "", "pixellab_api_key": "",
  "license_key": "BSWN-XXXX-XXXX-XXXX-XXXX"
}
Key Why it matters
engine_root Buildsworn detects every UE_5.x under it and picks the right one from each project's EngineAssociation. Wrong root = "no installed engine".
project_roots Lets you say /compile MyGame instead of pasting paths. Add every drive you keep projects on.
default_project The project used when a tool gets an empty project_path. set_project changes it at runtime.
test_projects Per-engine host projects used to validate and package plugins (ue5_validate_plugin, release_plugin). Not needed for game projects.
vault_dir Markdown notes folder (Obsidian opens it as a vault). session_start / session_end and the notes tools live here.
aliases ~name shortcuts usable in every path argument. Built-ins: ~workspace ~output ~releases ~vault ~logs ~screenshots ~downloads ~desktop ~docs.
vps_* Optional SSH access to your own server for deploys and log checks. Leave empty if you have none; the tools then say "not configured".
license_key Your seat. license_status shows the fingerprint and expiry; the activation token renews itself online once a month.

Data the server writes for itself (logs, screenshots, sqlite, editor bridge queue, reports, baselines) goes to %LOCALAPPDATA%\buildsworn. Delete it any time; nothing of yours is in there.

Editor bridge (UE 5.6 / 5.7)

To let Claude run Python inside a running editor (ue5_editor_exec, ue5_snippet, ue_screenshot): 1. Enable Python Editor Script Plugin in the project, restart the editor. 2. Copy C:\Program Files\Buildsworn\buildsworn\_internal\ue5brain\py_bridge\init_unreal.py to <Project>\Content\Python\init_unreal.py. 3. Restart the editor; the Output Log shows [MCP Bridge] Started. ue5_editor_status confirms it.

7. Make your own plugin the same way

The product is not only the tools; it is the way of working. You can extend it without touching our code:

7a. Shipping to Steam: /release

Add your app to config.json ("steam": {"steamcmd": "...\\ContentBuilder\\builder\\steamcmd.exe", "username": "you", "apps": {"MyGame": {"app_id": 1234560, "depot_id": 1234561}}}), log in once by hand (steamcmd +login you, so no password is ever stored), then /release MyGame. The skill runs the gate, packages the game, audits the folder (no steam_appid.txt, no .pdb), writes the SteamPipe scripts, shows a dry run and uploads only after you write "upload". The first upload is a preview; no branch is ever set live from here. You switch the branch in Steamworks after testing.

7b. What the agent can do on your computer (read this once)

Buildsworn is a power tool. With it, Claude can: run shell commands (local_cmd), kill processes (kill_process, always asks first), read and write any file under your user profile, the workspace and your project folders, take screenshots and drive mouse/keyboard for game_visual_check (move the mouse into a screen corner to abort automated input), and, only if you configured vps_*, run commands on your own server over SSH. The hooks make the dangerous ones ask and back up, but the final say is the permission prompt in Claude Code. Do not run it with permissions bypassed on a machine you do not fully own.

8. Updating, moving, uninstalling

9. When something is off

Symptom Check
/mcp does not list Buildsworn claude mcp list should show buildsworn. If not: claude mcp add --scope user buildsworn -- "C:\Program Files\Buildsworn\buildsworn\buildsworn.exe". Plugin missing from claude plugin list? claude plugin marketplace add "C:\Program Files\Buildsworn\marketplace" then claude plugin install Buildsworn@buildsworn.
UNLICENSED: license server unreachable Internet / firewall for adrenalinegames.pl. A cached token keeps working for 30 days.
no installed engine for '5.8' engine_root in config.json; buildsworn --health prints what it found.
Compile refuses: editor holds the DLL Close the editor, or let the tool do it with close_editor=True (it asks first). Never Live Coding.
Hooks not firing They only run inside Claude Code sessions where the plugin is enabled; claude plugin details Buildsworn@buildsworn lists them.
Anything else %LOCALAPPDATA%\buildsworn\logs\mcp_<date>.log and install.log. Send both to support with your key's first 9 characters.

Support bundle: buildsworn --support-bundle (or ask Claude to "call support_bundle") writes one zip on your Desktop with the logs, the health check, the key check and your config with every key redacted. No project files. Attach it to the form.

Telemetry is off unless you ticked the box in the installer ("telemetry": true in config.json). When on, the only thing sent is a daily count of gate PASS/FAIL and the product version. Nothing else, ever.

UE 5.8 and Epic's Unreal MCP: the installer registers Epic's editor server as unreal-mcp in Claude Code when it finds the ModelContextProtocol plugin in a UE 5.8 install. Enable the plugin in the editor and run ModelContextProtocol.StartServer in the console; editor work then goes through Epic's server, build/gate/package through Buildsworn.

Support: https://adrenalinegames.pl (contact form), reply within two working days.