Installation

SimVX is not on PyPI yet: install from source.

Requirements

System Requirements

  • Python 3.14+

  • Vulkan 1.2+ capable GPU and drivers

  • glslc shader compiler (from the Vulkan SDK)

  • One windowing library: GLFW3, SDL3, or PySide6 (any one works: see Windowing Backends)

  • uv: workspace packages resolve only through uv run

Install uv if you don’t have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Per-Platform Setup

Arch / Manjaro

sudo pacman -S vulkan-devel glfw shaderc

Ubuntu / Debian

sudo apt install libvulkan-dev libglfw3-dev glslc

macOS

Install the Vulkan SDK (includes MoltenVK and glslc), then:

brew install glfw

Clone & Install

git clone https://fezzik.dev/fezzik/simvx.git
cd simvx

# Install all workspace packages (editable) into the project venv
uv sync

# Optional: pull in dev tools (pytest, ruff, mypy, black) and/or doc build deps
uv sync --group dev --group docs

To install only a subset of packages editable (e.g. when working on a single package), use the explicit form instead:

uv pip install -e packages/core -e packages/graphics

The two dependency groups defined in the workspace pyproject.toml:

Group

Adds

When you need it

dev

pytest, pytest-cov, mypy, ruff, black

running the test suite or pre-commit checks

docs

sphinx, myst-parser, sphinx-autodoc2, furo

building the documentation locally

Both are optional: you can use SimVX without either.

Native audio extension

Audio playback uses a small C extension (ma_engine) compiled at install time by a PEP 517 build hook (packages/core/build_audio_ext_hook.py). Three install modes control how the build is treated:

Env var

Behaviour at install

Behaviour at runtime

(default)

Tries to compile. On failure (no C compiler, etc.) the install succeeds and prints a stderr WARNING.

If the .so is missing, falls back to the legacy pure-Python mixer with a one-time WARNING.

SIMVX_SKIP_AUDIO_BUILD=1

Skips the compile step entirely. Quiet.

Same legacy fallback with WARNING.

SIMVX_REQUIRE_AUDIO_NATIVE=1

Fails the install if the compile fails. For CI / production pipelines.

Native required: runtime can’t fall back if the file was never built.

 
# Default (best-effort native build)
uv pip install -e packages/core

# Skip the build, accept the legacy mixer
SIMVX_SKIP_AUDIO_BUILD=1 uv pip install -e packages/core

# Hard require: fail loud on missing compiler
SIMVX_REQUIRE_AUDIO_NATIVE=1 uv pip install -e packages/core

Two runtime env vars control the fallback policy:

Env var

Effect

(default)

Native → legacy (with WARNING) → null (with WARNING).

SIMVX_ALLOW_LEGACY_AUDIO=0

Native or AudioBackendUnavailable. No silent degradation.

To rebuild the extension after install without re-running pip:

uv run --with setuptools simvx build-audio

Verify Installation

Check the Vulkan driver:

vulkaninfo --summary

Import-check the packages:

from simvx.core import Node, SceneTree, Vec3, Property
from simvx.graphics import App

Run the core test suite:

uv run --package simvx-core pytest

Next