Building from source

A source checkout is for working on SimVX itself. To make a game, Installation with pip.

Set up a checkout

You need Python 3.14+, a Vulkan driver (Installation), uv and glslc (a checkout compiles the engine’s shaders on first use; see Shader compiler).

git clone https://git.simvx.com/simvx/simvx.git
cd simvx
uv sync                     # every package, editable, plus the dev tools
uv sync --extra examples    # the example library, for `simvx examples`

Run everything from the repository root through uv run: a bare python or pytest does not resolve the workspace packages.

uv run python examples/tutorials/pong/main.py
uv run --package simvx-core pytest packages/core/tests

Always give pytest a path. Without one it collects every package’s suite at once.

Dependency groups

Group

Adds

Installed by

dev

pytest, ruff, mypy, and what the suites use beyond them

uv sync (the default group)

docs

Sphinx, MyST, autodoc2, sphinx-design, furo

uv sync --group docs

Native accelerators

simvx-audio-miniaudio, simvx-textures-basis and simvx-physics-jolt each build one shared library, loaded through cffi. uv sync builds them with the zig compiler, which their build requirements fetch from PyPI (with CMake and ninja for Jolt), so no system compiler is needed.

  • After editing C or C++ sources, rebuild one package; an unchanged version is otherwise kept:

    uv sync --reinstall-package simvx-physics-jolt

  • Build parallelism. The Jolt build runs a conservative number of compilers at a time, to fit a machine short of memory. Set CMAKE_BUILD_PARALLEL_LEVEL to run more.

  • Stale libraries. cffi resolves each function on first use, so a library built from older glue loads and fails later with an AttributeError. Set SIMVX_VALIDATE_NATIVE=1 to look up every declared function as the library opens; a missing one raises ImportError naming it. The test suites turn it on.

Each accelerator package has the same layout:

Path

Holds

src/simvx/<area>/<name>/

the Python binding, with _cdef.py holding the cffi declarations

src/simvx/<area>/<name>/glue/

the C or C++ glue, whose header (glue.h, or jolt_glue.h for Jolt) repeats the _cdef.py declarations

vendor/

the upstream library, unmodified

build_native_hook.py

the build, through the shared tooling in tools/native/

tools/native/README.md documents the build tooling and its tests.

The example library

The examples are the simvx-examples distribution, and it has no editable install. After editing anything under examples/_package/, reinstall it:

uv sync --extra examples --reinstall-package simvx-examples

SIMVX_EXAMPLES_ROOT points simvx examples at another tree, such as a checkout’s examples/.

Build the docs

uv run python tools/build_examples.py docs     # generates the examples gallery pages
uv run --with setuptools --group docs sphinx-build -j6 docs docs/_build/html

Then open docs/_build/html/index.html. The gallery pages are generated, not tracked, so the first command runs before the second.

Project structure

packages/
  core/             Backend-agnostic engine: nodes, signals, animation, audio, UI, physics, scene I/O
  graphics/         Vulkan renderer and windowing
  web/              Browser runtime and the `simvx export web` exporter
  editor/           Visual scene editor, built on simvx.core.ui
  ide/              Engine-native Python IDE (LSP, debugger, terminal)
  ai/               LLM layer
  audio-miniaudio/  Native audio accelerator (miniaudio)
  textures-basis/   Native UASTC texture transcoder (basis_universal)
  physics-jolt/     Native Jolt 3D physics backend, selected on request
examples/           Tutorials, feature references, demos and ports (the simvx-examples distribution)
docs/               Documentation site source
tools/              Build, test and docs tooling, including the native accelerator build
tests/              Repository-level tests that belong to no package

Next steps