Build from Source

For contributors and developers who want to work on the engine itself.

Requirements

Clone and build

git lfs install            # once per machine
git clone {{< param repo >}}.git
cd turian

zig build          # compile studio + CLI (Debug)
zig build run      # compile and launch Turian Studio
zig build test     # run all unit tests
zig build ci       # tests + ReleaseFast (matches CI)

Output binaries land in zig-out/bin/:

• turian-studio — the GUI editor
• turian-cli — the headless CLI

CLI usage (from source)

./zig-out/bin/turian-cli new-project ../my-game "My Game"
./zig-out/bin/turian-cli info        ../my-game
./zig-out/bin/turian-cli build       ../my-game

Adding a built-in component

1. Create engine/components/MyComponent.zig:

   pub const MyComponent = struct {
       value: f32 = 1.0,
   };
   

2. Register it in engine/components/root.zig.
3. Add a tag to the Component union in engine/scene/Component.zig.
4. Update BuiltinEntry.zig and scanner.zig (populateBuiltins).

Running tests

zig build test

Tests live inline in source files using Zig's built-in test blocks.

Platform support & cross-compiling

The Studio and CLI build and run on Linux, Windows, and macOS. The Studio uses SDL3-GPU and prefers a Vulkan device (needed by the SPIRV 3D viewport), falling back to the platform default (D3D12 on Windows, Metal on macOS) when Vulkan is unavailable — in which case the editor UI still works fully and only the 3D scene viewport shows "unavailable".

Zig cross-compiles the whole Studio from Linux with no Windows toolchain (SDL3, dvui and freetype are all built from source):

zig build -Dtarget=x86_64-windows-gnu -Dno-test

The resulting turian-studio.exe is self-contained (SDL3 is statically linked) and can be smoke-tested under Wine.

CI/CD

The GitLab pipeline (.gitlab-ci.yml) and how it's kept fast (a prebuilt CI image, cross-branch cache reuse, the one-time image bootstrap a Dockerfile change needs) are documented in [docs/ci.md]({{< param repo >}}/-/blob/main/docs/ci.md) in the repository — maintainer-facing, not needed for a typical contribution.

← All docs Edit this page