Build Smithbox from source

The team's Smithbox is a fork of vawser/Smithbox. The checkout is S:\Smithbox, branch mcp-bridge. Changes are made there. Team builds reach teammates through the auto-updater.

What was checked for this page: the rules file, project file, build paths and the release scripts were read. Nothing was built. Two parts are not checked against a run: the shader recompile and the Vulkan validation variables (those come from the team's notes). Each is marked below.

The rules of the Smithbox repo

S:\Smithbox\CLAUDE.md applies to every agent working there. The parts that matter here, quoted:

• "Do not delete files or folders. Instead move them to the .archive folder."
• "Do not create or force-push git commits."
• "Use C# when writing temporary tools, except when intructed to use other languages." and "Do not use Python."
• "Create projects in the Smithbox/Tools folder for temporary tools, rather than using the scratchpad."
• "Do not try to verify changes by launching the program. Pass to the user and tell them what to check for."
• "Create planning and analysis markdown (.MD) files in the Smithbox/Documentation/Claude folder."

So an agent does not commit in this repo unless Stan says so in that session. When he does, use the commit style of the recent history: type(scope): lowercase summary.

Two more rules that are not in that file:

• Never discard edits in a running Smithbox. See the safety rules in mcp-bridge.md.
• Never delete or move S:\Smithbox-havok-pin. It is a second worktree of this repo, pinned at an older commit (854818a37). The Eclipse port tools build against it.

Before you start

• The .NET 10 SDK. The projects target net10.0. Check with dotnet --list-sdks.
• Smithbox must be closed. The build writes into the folder the running exe is in, and those files are locked while it runs.
• Before you ask anyone to close Smithbox, or close it yourself: call smithbox_status and look for unsaved maps and can_undo. If anything could be someone's work, ask them to save first. Do not unload with discard_changes.

Build

From S:\Smithbox:

dotnet build src\Smithbox.Vulkan\Smithbox.Vulkan.csproj -c Release -m:1

-m:1 builds one project at a time. The release script uses it too; the team's notes say parallel builds ran out of memory.

The exe is:

S:\Smithbox\src\Smithbox.Vulkan\bin\Release\net10.0\win-x64\Smithbox.Vulkan.exe

That is also the exe the MCP tool launch_smithbox starts by default.

If the shared build is in use (someone's Smithbox is open and must stay open), build a copy into another folder instead of closing theirs. The team's notes do this by adding -p:OutDir=<folder> and running that copy on another bridge port. This was not re-checked here. See "Running a test copy on another port" in mcp-bridge.md.

Shaders

The compiled shaders (.spv) are checked in next to their sources in src\Smithbox.Data\Assets\Shaders\. If you edit a shader source (for example FlverShader\FlverShader.frag), recompile it and commit the new .spv files with the source, or the change does nothing.

src\Smithbox.Data\Assets\Shaders\compile.ps1 shows the commands: glslangvalidator -V for each .vert, .frag and .comp, then Veldrid.SPIRV.VariantCompiler for the FlverShader set. Not run for this page. The team's notes say a copy of Veldrid.SPIRV.VariantCompiler with libveldrid-spirv.dll is needed for it; check that before you rely on it.

Check your change

Agents do not launch Smithbox to verify (see the rules above). Build, then tell the person what to look at. If you need more information from their run, add temporary log lines they can send back.

The auto-updater, as a teammate sees it

Only the team build updates itself: a Smithbox folder with update-channel.json next to the exe. A build you made yourself never checks.

• It checks when Smithbox starts and every 3 hours after that. Help > Check for updates checks by hand.
• A newer release downloads in the background while you work. The menu bar shows "Downloading update ..." with a percentage.
• Then the menu bar shows Update <version> ready. Open it for the release notes and two choices:
  • Restart and update now: asks about unsaved changes, closes Smithbox, installs and starts it again.
  • Install when Smithbox closes: installs at the next normal exit.
• If an update cannot be installed, Smithbox stays on the old version and says so. Details are in .update\update.log next to the exe.
• A new teammate starts from the install zip and unzips it anywhere. After that every release arrives this way.

Settings and projects live in %LOCALAPPDATA%\Smithbox and are not touched by updates.

Find a GPU-specific rendering bug with Vulkan validation

For a rendering bug that only shows on some GPUs, run a test copy of Smithbox under the Vulkan validation layer instead of guessing.

Checked in the code: SMITHBOX_VULKAN_DEBUG=1 turns on Vulkan debug mode in a release build (it is always on in a debug build). The code comment says it is meant to be used with VK_INSTANCE_LAYERS set, so validation messages carry object names.

From the team's notes, not re-checked here: the LunarG Vulkan SDK is installed on the build PC at C:\VulkanSDK\1.4.363.1, and a validation run sets these before starting the test copy:

Run it on a test copy, not on the Smithbox someone is working in. The GPU a teammate's report came from is in the report's info.json. What the viewport draws is covered in rendering.md.

What goes wrong