Installation

pip install --pre simvx

Pre-alpha. SimVX publishes development releases only (0.0.0.devN) and is under active development; the API changes between builds. Once stable versions ship to PyPI, development builds continue on pypi.simvx.com.

Ways to install

Source

Command

PyPI (recommended)

pip install --pre simvx

Latest development build

pip install --pre simvx --extra-index-url https://pypi.simvx.com/

From source

git clone https://git.simvx.com/simvx/simvx.git && cd simvx && uv sync

Install into a virtual environment (python3.14 -m venv .venv, then activate it); many Linux systems refuse a system-wide pip install. Without Python 3.14, uv venv --python 3.14 downloads it. From a source checkout, prefix commands with uv run; Building from source covers it.

Requirements

Who

Needs

Everyone

Python 3.14+, and a GPU driver with Vulkan 1.2+

A source checkout

uv, and glslc to compile the engine’s shaders

A game with its own GLSL

glslc on PATH (see Shader compiler)

pip supplies everything else, including the window library: the glfw wheel bundles GLFW.

Platforms

Platform

Status

Linux x86_64

Tested

Linux aarch64

Built, untested; pip builds miniaudio from source, which needs a C compiler and the Python headers (sudo apt install build-essential python3-dev)

Windows x86_64

Built, untested

macOS x86_64 and arm64 (MoltenVK)

Built, untested; audio uses the Python mixer

Vulkan driver

System

Install

Debian, Ubuntu

sudo apt install libvulkan1 mesa-vulkan-drivers, or NVIDIA’s driver

Fedora

sudo dnf install vulkan-loader mesa-vulkan-drivers, or NVIDIA’s driver

Arch, Manjaro

sudo pacman -S vulkan-icd-loader plus vulkan-radeon, vulkan-intel or nvidia-utils

Windows

your GPU vendor’s current driver (NVIDIA, AMD or Intel), which includes the Vulkan loader

macOS

the LunarG Vulkan SDK, which supplies MoltenVK, with System Global Installation selected in the installer

Check the install

simvx-preflight

simvx-preflight checks Python, the Vulkan driver and your GPUs, glslc, the window library and the installed SimVX packages. On a missing piece it exits non-zero and prints the command that installs it. Then run the program in the Quickstart, or an example (below).

Troubleshooting

Symptom

What to do

simvx-preflight reports no Vulkan loader

Install the driver for your system from the table above.

The loader is found but reports no device

The loader is there without a driver behind it: install your GPU vendor’s Vulkan driver.

A virtual machine or WSL reports no device

The guest needs a Vulkan driver of its own. Check its GPU support, or run on the host.

Your own shader fails on its first frame

Install glslc (below); the error names the shader.

pip says externally-managed-environment

Install into a virtual environment (see Ways to install).

Anything else

Run simvx-preflight and include its output in an issue.

The example library

pip install --pre "simvx[examples]"

simvx examples list                       # every installed example, grouped by tier
simvx examples list physics               # search ids, titles, descriptions and tags
simvx examples run tutorials_pong
simvx examples copy tutorials_pong --to ~/games/my-pong

copy puts the example, its assets and its licence in a directory you own. Edit the copy: the installed library is replaced on every upgrade. Each port of a third-party game carries its own licence in its ATTRIBUTION.md, which copy brings along.

Shader compiler

The engine’s own shaders and the shipped examples need no compiler: the wheels ship them compiled. A game’s own GLSL (a ShaderMaterial or a PostProcessEffect) compiles with glslc the first time it is drawn.

System

Install

Debian, Ubuntu

sudo apt install glslc

Fedora

sudo dnf install glslc

Arch, Manjaro

sudo pacman -S shaderc

macOS

brew install shaderc, or the LunarG Vulkan SDK

Windows

the LunarG Vulkan SDK, which puts glslc on PATH

No Python package provides it. Players of an exported game do not need it: every export compiles the game’s shaders into precompiled_shaders/ beside its entry script.

Compiled shaders are cached in $SIMVX_SHADER_CACHE_DIR, else [rendering] shader_cache_dir in simvx.toml, else $XDG_CACHE_HOME/simvx/shaders (~/Library/Caches/simvx/shaders on macOS, %LOCALAPPDATA%\simvx\shaders on Windows).

Accelerators

pip install --pre simvx also installs these native packages on the platforms their wheels cover:

Package

Adds

Without it

simvx-audio-miniaudio

mixing, spatialisation and bus effects in C, off the GIL

audio mixes in Python, with higher latency and no bus effects (see Audio)

simvx-textures-basis

loading UASTC .ktx2 textures

loading a UASTC texture raises ValueError naming the package to install

simvx-physics-jolt

the Jolt 3D physics backend (see Physics Backends)

"jolt" cannot be selected; the default backend is unaffected

Next steps