Metadata-Version: 2.4
Name: SimVX-Physics-Jolt
Version: 0.0.0.dev1496+gc464d742
Summary: Optional 3D physics backend for SimVX, backed by the Jolt Physics engine (CFFI over joltc).
Project-URL: Homepage, https://simvx.com
Project-URL: Source, https://fezzik.dev/Fezzik/simvx
Author-email: SimVX Team <simvx@simvx.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_LICENSES.md
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: cffi>=1.17
Requires-Dist: simvx-core==0.0.0.dev1496+gc464d742
Description-Content-Type: text/markdown

# SimVX-Physics-Jolt

An **optional, opt-in 3D physics backend** for [SimVX](https://simvx.com),
backed by the [Jolt Physics](https://github.com/jrouwe/JoltPhysics) engine
through a CFFI binding over the [joltc](https://github.com/amerkoleci/joltc)
C ABI.

> **Status: scaffold.** This package currently ships only the distribution
> skeleton and the backend-discovery wiring. The vendored native sources, the
> CMake-driven build hook, and the `JoltPhysics` implementation of the engine's
> 3D physics contract land in later steps.

## Opt-in, 3D-only

- **Explicit opt-in only.** Installing this package makes the `"jolt"` backend
  name-addressable and auto-discoverable, but it does **not** change SimVX's
  default 3D backend. Jolt is used only when you select it on purpose:

  ```python
  PhysicsRoot(backend="jolt")          # per-node override, or
  ```
  ```json
  // .simvx/config.json (project-wide)
  {"general": {"physics_backend": "jolt"}}
  ```

  This differs from the miniaudio / pymunk "installed -> used" model: a 3D
  physics swap is gameplay-affecting, so it must be a deliberate choice.

- **3D-only.** Jolt is a 3D engine. A 2D scene falls through to the pure-Python
  builtin backend (or `pymunk` if that optional package is installed).

## Installation model

- **sdist-from-source is the default, supported path.** The pinned Jolt + joltc
  sources are vendored under `vendor/`, so the source distribution is always
  buildable offline. Building requires a C/C++ toolchain and CMake (>= 3.16).

- **Any shipped Linux wheel is experimental.** A prebuilt wheel must force a
  conservative SIMD baseline (no AVX2; SSE4.2 floor) or it will `SIGILL` on
  older CPUs. Prefer building from source for your own machine.

- Build behaviour is controlled by environment variables (mirroring the core
  audio extension):
  - `SIMVX_SKIP_JOLT_BUILD=1`: skip the native build entirely.
  - `SIMVX_REQUIRE_JOLT_NATIVE=1`: fail the install if the native build fails
    (for CI / production, where silent fallback is unacceptable).

## Licences

- This package: see the repository's `LICENSE`.
- Jolt Physics (`vendor/`): MIT, Copyright 2021 Jorrit Rouwe.
- joltc (`vendor/`): MIT.
