Build and test

Build and Test

This is the shortest trustworthy path from a fresh checkout to evidence that Voxamine still works. It covers three independently buildable products:

• the Unity HDRP player;
• the standalone .NET authoritative-server track; and
• this Astro/Starlight documentation site.

Prerequisites

Product	Required toolchain	Source of truth
Unity player	Unity 6000.6.0f1 with the target platform module	ProjectSettings/ProjectVersion.txt
Player packages	Unity Package Manager resolution	Packages/manifest.json and packages-lock.json
Standalone server	.NET SDK compatible with Server/VoxelSandbox.Server.csproj	Server project file
Documentation wiki	Node.js and npm	external/shisaku.dev/package.json
Texture generator	Python 3, NumPy, Pillow, SciPy	Tools/TextureGen/README.md

Open the repository root in the exact Unity version. After package resolution, run Window → Voxel Workshop → Project Doctor before diagnosing unrelated project errors.

The build system at a glance

flowchart LR
    Source[Source and pinned manifests] --> Unity[Unity 6 HDRP player]
    Source --> Server[Standalone .NET server]
    Source --> Docs[Docs and Astro wiki]
    Source --> Tools[Deterministic asset tools]

    Unity --> Tests[Unity EditMode tests]
    Unity --> Raster[Windows or Linux raster build]
    Server --> Publish[Self-contained server publish]
    Docs --> Static[Static documentation site]
    Tools --> Assets[Reviewed project assets]

    Tests --> Release[Release evidence]
    Raster --> Release
    Publish --> Release
    Static --> Release
    Assets --> Release

No arrow bypasses review: generated art, a player build, and a documentation build are outputs that must be checked for the actual input revision.

Unity player

Fast, focused verification

Run a focused EditMode fixture while iterating on a bounded system. Replace the filter with the fixture that owns the change:

/path/to/Unity \
  -batchmode \
  -projectPath . \
  -runTests \
  -testPlatform EditMode \
  -testFilter "VoxelSandbox.Tests.<Fixture>" \
  -testResults ./Logs/focused-results.xml \
  -quit

Full EditMode gate

Run the full suite before calling an implementation slice ready. It currently takes roughly fifteen minutes when the workstation is under parallel-session contention.

/path/to/Unity \
  -batchmode \
  -projectPath . \
  -runTests \
  -testPlatform EditMode \
  -testResults ./Logs/editmode-results.xml \
  -quit

Inspect both the XML result and Logs/ on failure. Unity may change ProjectSettings/ProjectSettings.asset analytics defines in batch mode; that is local tool churn, not a gameplay change to stage.

Player builds

The enabled build order starts at Assets/_Game/Scenes/MainMenu.unity, then loads the deterministically composed gameplay scene. Use Tools → Voxel Sandbox → Build for interactive builds, or run the same checked build path unattended:

/path/to/Unity \
  -batchmode \
  -nographics \
  -projectPath . \
  -executeMethod VoxelSandbox.VoxelWorkshop.Modules.ProjectDoctor.StandaloneReleaseBuilder.BuildWindows64 \
  -quit

Use BuildLinux64 for Linux. Builds are written under ignored Builds/. A clean end-to-end player build on each matching platform-support installation remains a release gate, so record platform, commit, Unity version, and smoke result rather than assuming one platform proves another.

Standalone server

The server is a sibling .NET application, not Unity code. It deliberately has no Unity runtime dependency.

cd Server
dotnet run

For a deployable, self-contained artifact:

cd Server
dotnet publish -c Release -r linux-x64 --self-contained true -o publish/linux-x64

Run ./publish/linux-x64/VoxelSandbox.Server on the target. The public deployment needs both UDP (gameplay) and TCP (status/WebSocket) open on the configured port. Confirm GET /status after a smoke run; it reports transport, process, world, and compatibility information without exposing operator secrets.

The host is a real session layer but not yet full multiplayer gameplay: chunk/edit replication, inventory replication, and authoritative voxel collision remain intentionally incomplete. Do not advertise a published server as feature-parity multiplayer until those gates land.

Deterministic content tools

Run the smallest relevant generator check after changing its source. For example, the texture generator’s broad regression check is:

Tools/TextureGen/generate-block-textures.sh --selftest

This includes deterministic/golden-hash checks. If output intentionally changes, review the visual result, update the golden record intentionally, and commit that record with the source change. Do not regenerate project assets as incidental build output.

Documentation wiki

The wiki is an Astro/Starlight static site in external/shisaku.dev, tracked as a Git submodule. On a fresh game-repository clone, initialise it first:

git submodule update --init --recursive

Then build it from the site directory:

cd external/shisaku.dev
npm ci
npm run build

npm run build synchronises the authoritative root Docs/ files into the site before rendering. When Vercel builds the site as its own repository, it intentionally uses the committed synced pages instead; this keeps the deployed wiki self-contained. Mermaid diagrams are rendered by the site’s graph integration and must remain legible in both light and dark themes.

What to record with a completed slice

• the exact revision and version;
• the focused test(s) and full gate that ran, including any skipped gate and why;
• target platform/toolchain for a build or server publish;
• screenshots or a reproducible scene/seed for a visible change;
• player-facing evidence for science work: signal, instrument reading, journal explanation, and its stated uncertainty or approximation;
• known limitations that would make the result misleading if omitted.

That record is how a build becomes a trustworthy piece of the game rather than an unrepeatable machine-state accident.