Metadata-Version: 2.4
Name: SimVX
Version: 0.0.0.dev1496+gc464d742
Summary: A simulation and visualization framework
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSE-ADDENDUM.md
License-File: LICENSE-EXCEPTION.md
Requires-Python: >=3.14
Requires-Dist: simvx-ai==0.0.0.dev1496+gc464d742
Requires-Dist: simvx-core==0.0.0.dev1496+gc464d742
Requires-Dist: simvx-editor==0.0.0.dev1496+gc464d742
Requires-Dist: simvx-graphics==0.0.0.dev1496+gc464d742
Requires-Dist: simvx-ide==0.0.0.dev1496+gc464d742
Requires-Dist: simvx-web==0.0.0.dev1496+gc464d742
Description-Content-Type: text/markdown

# SimVX

[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0%20%2B%20commercial-blue)](https://fezzik.dev/fezzik/simvx/src/branch/main/LICENSE)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)](https://simvx.com/docs/install.html)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000)](https://black.readthedocs.io/)
[![Linter: Ruff](https://img.shields.io/badge/lint-ruff-261230)](https://docs.astral.sh/ruff/)
[![Docs: simvx.com](https://img.shields.io/badge/docs-simvx.com-1f6feb)](https://simvx.com)

<!-- docs-include-start -->

**A game engine in pure Python: node scenes, Vulkan rendering, runs in the browser.**

SimVX gives you a node-based scene tree, signals, animation, audio, UI widgets, physics, and a
GPU-driven Vulkan renderer: all as a clean, idiomatic Python API, with **no second language to
learn**. The visual editor and the integrated IDE are themselves built using the
engine. Scenes are authored and saved as ordinary `.py` files, and any game can be exported to a
single self-contained WebGPU HTML page that runs in the browser.

[![A PBR-lit 3D scene rendered by SimVX](https://simvx.com/assets/showcase/3d_ibl.png)](https://simvx.com/docs/examples/index.html)

## Why SimVX

- **Pure Python.** Write game logic, tools, and editor plugins in real Python: use any PyPI package, `pdb`, and your existing toolchain. No custom scripting language.
- **Scenes are Python.** A scene is a `Node` subclass in a `.py` file; the editor round-trips scenes to and from source. No custom scene format. (Save-games use JSON or pickle.)
- **One command to the browser.** `simvx export web game.py` produces a single standalone WebGPU HTML file: the same scene code as the desktop Vulkan build.

## Features

- **Node scene tree**: hierarchy, signals, groups, coroutines, and a `Property` system that is inspector-visible and serialisable.
- **GPU-driven rendering**: a Vulkan forward renderer (multi-draw indirect, PBR, shadows, SSAO, bloom, post-processing) on the desktop; WebGPU in the browser.
- **2D and 3D, one API**: sprites, tilemaps, and 2D lighting alongside PBR meshes, skeletal animation, particles, and physics.
- **Animation & audio**: tweens, sprite sheets, keyframe clips, and state machines; 2D/3D spatial audio with bus routing.
- **UI, editor & IDE**: buttons, sliders, trees, and layout containers, plus a visual scene editor and an engine-native Python IDE, all built on the same widget system.
- **Headless test harness**: render frames without a window, replay input deterministically, and assert on scene state.

## Quick start

Install from source with [uv](https://docs.astral.sh/uv/) (SimVX is not yet on PyPI):

```bash
git clone https://fezzik.dev/fezzik/simvx.git
cd simvx
uv sync
```

Then write a scene: a `Node` subclass is a complete program:

```python
import math

from simvx.core import Camera3D, Material, Mesh, MeshInstance3D, Node
from simvx.graphics import App


class MyGame(Node):
    def on_ready(self):
        cam = self.add_child(Camera3D(position=(0, 5, 10)))
        cam.look_at((0, 0, 0))

        self.cube = self.add_child(MeshInstance3D(
            name="Cube",
            mesh=Mesh.cube(),
            material=Material(colour=(1.0, 0.2, 0.2, 1.0)),
        ))

    def on_update(self, dt):
        self.cube.rotate((0, 1, 0), math.radians(90) * dt)  # 90 degrees/sec


App(width=1280, height=720, title="My Game").run(MyGame())
```

Run it with `uv run python my_game.py` and a window opens with a red cube spinning. Or launch a full game straight away:

```bash
uv run python examples/demos/asteroids2d.py
```

## Where to go next

- **[Examples gallery](https://simvx.com/docs/examples/index.html)**: every demo, most playable right in your browser
- **[Live editor](https://simvx.com/editor.html)**: the full visual editor, no install (beta)
- **[Documentation](https://simvx.com/docs/)**: quickstart, tutorials, and the full API reference
- **[Web export guide](https://simvx.com/docs/web/export.html)**: ship a game as a single HTML file
- **[Source on Gitea](https://fezzik.dev/fezzik/simvx)**: report issues and contribute

<!-- docs-include-end -->

## Installing from source

SimVX is a `uv` workspace of `simvx.*` packages. From a clone of the repository:

```bash
uv sync                          # all packages, editable, in a managed venv
uv sync --group dev --group docs # optional: test tools + docs build deps
```

To install only part of the engine:

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

**Requirements:** Python 3.14+ and a Vulkan 1.2+ capable GPU with current drivers. All Python
dependencies (including GLFW and the shader compiler) are resolved by `uv sync`; a system
`glslc` is only needed if you recompile shaders. Pick a windowing backend (GLFW3, SDL3, or PySide6);
GLFW is the default.

## Building the docs

```bash
uv run --with setuptools --group docs sphinx-build -j6 docs docs/_build/html
```

Then open `docs/_build/html/index.html` in a browser.

## Project structure

```
packages/
  core/       Backend-agnostic engine (nodes, signals, animation, audio, UI, collision, scene I/O)
  graphics/   Vulkan rendering backend (GPU-driven forward renderer)
  web/        Browser runtime and the `simvx export web` static HTML exporter
  editor/     Visual scene editor, built on simvx.core.ui
  ide/        Engine-native Python IDE (LSP, debugger, terminal)
  ai/         LLM / agent layer (provider-agnostic client, in-game brains)
  physics-jolt/  Opt-in native Jolt 3D physics backend (not installed by default)
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md). Development happens on the `dev` branch: **never commit to
`main`**, which is reserved for reviewed, integrated work. Run a package's tests with, for example:

```bash
uv run --package simvx-core pytest
```

## License

SimVX is **dual-licensed**. At a glance, pick the row that matches what you want to do:

| You want to… | Path | Cost | Your obligation |
| --- | --- | --- | --- |
| Open-source your game | AGPL-3.0 | Free | License your game under AGPL-3.0; keep the [NOTICE](./NOTICE) file (no splash required) |
| Ship a game under any licence, including closed-source | [Game-Distribution Exception](./LICENSE-EXCEPTION.md) | Free | Display the "Made with SimVX" splash / watermark |
| Ship closed-source without the splash, privately fork the engine, or use "Official SimVX" branding | [Commercial licence](./COMMERCIAL-LICENSE.md) | Paid | [Contact us](./COMMERCIAL-LICENSE.md) |

Different parts of the repository carry different licences:

- **Engine** (repository root): [AGPL-3.0-or-later](./LICENSE) with
  [Additional Terms](./LICENSE-ADDENDUM.md) (attribution preservation, modified-version marking, no
  trademark grant) and a [Game-Distribution Exception](./LICENSE-EXCEPTION.md) so games built with
  SimVX may use any licence, including proprietary. Modifications to the **engine itself** stay
  copyleft. A [commercial licence](./COMMERCIAL-LICENSE.md) lifts the copyleft on engine
  modifications, removes the "Made with SimVX" splash, and can grant Official SimVX branding and
  support.
- **Examples** (`examples/features`, `examples/tutorials`, `examples/demos`):
  [MIT](./examples/LICENSE), so you may copy them freely into your own projects.
- **Documentation** (`docs/`): prose under CC-BY-4.0, code snippets under MIT
  (see [docs/LICENSE.md](./docs/LICENSE.md)).
- **Ports** (`examples/ports/*`): licensed **per port** as derivative works of the original games;
  see each port's `ATTRIBUTION.md` / `UPSTREAM_LICENSE.md`. Not covered by the engine or examples
  licences.

Redistributions must preserve the [NOTICE](./NOTICE) attribution. "SimVX" and the SimVX logo are
trademarks; see [TRADEMARK.md](./TRADEMARK.md). Contributions are accepted under the
[CLA](./CLA.md), which keeps dual-licensing possible. © 2026 Gabriel Bouffard.
