Headless 3D and VFX engine for agents. Research preview.
Build from source
Run these commands from the checkout root. Source builds need Rust, a native
C/C++ toolchain, Python with safe tar extraction filters, and the pinned Slang
compiler. Cargo does not download Slang. The supported Unix toolchain archives
are Apple Silicon macOS and x86-64 Linux (see dist/slang.json); there is no
pinned Intel Mac or Linux ARM archive.
Prerequisites
The pinned Slang 2026.20 macOS binaries target macOS 26. Older macOS versions have not been qualified with this toolchain.
On macOS, install Apple's command line tools, then install Homebrew from https://brew.sh if it is not already available:
xcode-select --install
Finish that installer before continuing. Use Homebrew Python explicitly: stock macOS Python 3.9 may lack the extraction filters required by the Slang installer. No pip packages are needed.
brew install [email protected]
PYTHON="$(brew --prefix [email protected])/bin/python3.12"
On Ubuntu 24.04 x86-64 (the Linux baseline), install:
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libclang-dev curl git python3 ca-certificates
PYTHON=python3
Basis texture bindings require libclang (libclang-dev on Ubuntu; supplied
by Apple's command line tools on macOS). If bindgen cannot find it, set
LIBCLANG_PATH to the directory containing libclang.
Other Linux distributions need equivalent C/C++ build tools, libclang and Python 3.12+
(or a Python release with backported tarfile.data_filter). Rendering also
needs a working Vulkan driver; building and GPU-free commands do not need a GPU.
For your own NVIDIA Linux machine, a Docker runtime is available.
Install Rust 1.96, matching CI, through rustup (https://rustup.rs):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/vork-rustup.sh
sh /tmp/vork-rustup.sh -y --default-toolchain 1.96
. "$HOME/.cargo/env"
Install Slang and build
Clone the repository if needed, then enter it.
Choose a new, empty destination outside the checkout. The installer downloads
and verifies the archive against dist/slang.json, and refuses to overwrite
an existing directory. Keep the entire toolchain, including its libraries,
modules and notices, together.
"$PYTHON" scripts/install-slang "$HOME/.local/share/vork/slang-2026.20"
export VORK_SLANGC="$HOME/.local/share/vork/slang-2026.20/bin/slangc"
"$VORK_SLANGC" -version
cargo +1.96 build --release --workspace --locked
./target/release/vork --help
./target/release/vork help
The build compiles shaders for both Vulkan and Metal on either host. It checks
the Slang version against the pin. VORK_SLANGC must be an absolute executable
path; alternatively the build can find the pinned slangc on PATH. Export
VORK_SLANGC again in each new shell, or add the export to your shell startup
file. A cannot start slangc error means this setup is missing; a version
mismatch means a different compiler was selected.
The binary is target/release/vork, or $CARGO_TARGET_DIR/release/vork when
that environment variable is set. These commands do not install it globally.
Runtime program compilation also needs Slang; retain the export when running
the binary from the build directory.
Rendering and test dependencies
Start with vork help and the scenes in examples/. macOS uses Metal; Linux
uses Vulkan. Install FFmpeg/ffprobe for video commands and encoding tests
(brew install ffmpeg on macOS, sudo apt-get install ffmpeg on Ubuntu).
The public workspace includes CPU unit tests and small fixtures. The text tests
use the bundled Liberation Sans font under SIL OFL 1.1; its copyright and licence
are in crates/vork-std/tests/fonts/OFL.txt. Renderer fixtures are synthetic scene,
shader and glTF inputs shipped with the source. No asset downloads are needed to
run the default tests. Corpus-dependent tests that require unshipped assets are
excluded from the public source; they are not part of its test coverage.
Renderer GPU tests require the explicit runtime opt-in VORK_GPU_TESTS=1;
without it they print a skip diagnostic (visible with -- --nocapture).
CPU and numeric tests remain enabled. Tests marked ignored explain their additional requirements. GPU tests need a
supported Metal/Vulkan device, including ray-query support; a CPU-only test run
does not validate rendering. To run ignored tests after installing their stated
dependencies, set VORK_GPU_TESTS=1 and use
cargo test -p vork-render -p vork-cli -- --include-ignored --nocapture.
OIDN is loaded at runtime, not required to compile. For denoised renders and GPU tests that exercise denoising, install the pinned runtime with the same Python:
"$PYTHON" scripts/install-oidn "$HOME/.local/share/vork/oidn"
# macOS:
export VORK_OIDN="$HOME/.local/share/vork/oidn/lib/libOpenImageDenoise.2.dylib"
# Linux (use this instead):
export VORK_OIDN="$HOME/.local/share/vork/oidn/lib/libOpenImageDenoise.so.2"
Workspace tests additionally need Node.js/npm for generated SDK checks. Install the TypeScript dependencies and fetch the locked crate sources for the licence notice check, then check and test every public workspace target:
npm ci --prefix packages/ts
cargo +1.96 fetch --locked
cargo +1.96 check --workspace --all-targets --locked
cargo +1.96 test --workspace --locked
Use -- --nocapture to see test diagnostics, including any GPU test skipped when
adapter discovery finds no device. Missing fixtures, missing required tools and
failed assertions are failures. An ignored or skipped GPU test supplies no GPU
coverage.
See README installation for binary installation and runtime
setup, and vork help programs --all for authored Slang programs. Node/npm and the
SDKs are not prerequisites for the Rust workspace build.
Public workflows
Distribution archives are built privately and attached to public GitHub releases.
For source validation, run the workspace tests above and npm ci && npm test
in packages/ts. Rendering checks need the runtime dependencies above;
run the examples with a supported GPU and inspect the resulting frames.
Release shader assets
Hosted distribution jobs run scripts/prepare-shaders with the final binary
(after macOS signing). It invokes the hidden prepare-release-shaders command:
the ordinary setup catalogue and Slang compiler run against a no-op wgpu device,
without opening a GPU driver, OIDN device or executing shaders. Denoiser
preparation constructs only the renderer's pack/unpack pipelines. macOS emits Metal source;
Linux and Windows emit SPIR-V. The bundle excludes all driver cache entries
and is bound to the packaged binary's SHA-256. scripts/package-release refuses
to package without this verified bundle. vork setup on the user's real GPU
then warms its own driver cache from those portable assets.
check-release --skip-setup --skip-render verifies installation, compiler and
portable assets on GPU-free hosted runners. Installed rendering, video and
denoising still require the real-device acceptance check.