omi-physics 0.1.0__tar.gz

omi_physics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike C. Fletcher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omi_physics-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include setup.py
+recursive-include src/omi_physics *.pyx *.pxd py.typed
+recursive-include docs *.md
+recursive-include tests *.py

omi_physics-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: omi_physics
+Version: 0.1.0
+Summary: Renderer-agnostic real-time rigid-body physics on the OMI glTF physics model
+Author-email: "Mike C. Fletcher" <mcfletch@vrplumber.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mcfletch/omi_physics
+Project-URL: Repository, https://github.com/mcfletch/omi_physics
+Project-URL: Documentation, https://github.com/mcfletch/omi_physics/tree/main/docs
+Keywords: physics,rigid-body,collision,simulation,OMI,glTF,numpy,game,3D
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: C
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Provides-Extra: gl
+Requires-Dist: PyOpenGL>=4.0.0a1; extra == "gl"
+Provides-Extra: gltest
+Requires-Dist: PyOpenGL>=4.0.0a1; extra == "gltest"
+Requires-Dist: glfw>=2.0; extra == "gltest"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Provides-Extra: dev
+Requires-Dist: Cython>=3.0; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: omi_physics[gltest,test]; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+Dynamic: license-file
+
+# omi_physics
+
+A renderer-agnostic, real-time **rigid-body physics engine** for Python, built
+natively on the [OMI glTF physics](https://github.com/omigroup/gltf-extensions)
+data model. State lives in flat NumPy arrays, the whole step pipeline is
+vectorized, and optional compiled Cython accelerators drop in transparently for
+the hot paths (the contact solver and box/sphere collision).
+
+- **NumPy is the only hard dependency.** No graphics library is required to
+  simulate.
+- **PyOpenGL is optional** — used solely by the experimental GPU compute backend
+  (`omi_physics.glcompute`).
+- **Deterministic** on the CPU backend: the same inputs produce the same
+  trajectory, run to run.
+- **Fast**: sweep-and-prune broadphase, SAT/GJK narrowphase, an island-parallel
+  sequential-impulse solver, sleeping, and a background-threaded simulation loop
+  that overlaps with a consumer's render/IO thread.
+
+> ⚠️ **This code is largely LLM-written.** It has a test suite and the CPU
+> backend is deterministic, but it comes with **no guarantees** of correctness,
+> accuracy, or fitness for any purpose (see [`LICENSE`](LICENSE), MIT). Review it
+> before relying on it for anything that matters.
+
+## Install
+
+```bash
+pip install omi_physics            # core engine (NumPy only)
+pip install "omi_physics[gl]"      # + PyOpenGL for the GPU compute backend
+```
+
+Prebuilt wheels ship the compiled accelerators, so no C compiler is needed. A
+source install without a compiler still works — the engine falls back to the
+identical pure-NumPy code paths.
+
+## Quick start
+
+```python
+import numpy as np
+from omi_physics import PhysicsWorld, model
+
+world = PhysicsWorld(gravity=model.Gravity(gravity=9.81, direction=(0, -1, 0)))
+
+# A static ground box and a dynamic box that falls onto it.
+ground = world.add_shape(model.Shape.box((20, 1, 20)))
+box    = world.add_shape(model.Shape.box((1, 1, 1)))
+wood   = world.add_material(model.Material())
+
+world.add_body(model.Motion(type=model.STATIC),
+               collider=model.Collider(shape=ground, physicsMaterial=wood),
+               position=(0, 0, 0))
+falling = world.add_body(model.Motion(type=model.DYNAMIC, mass=1.0),
+                         collider=model.Collider(shape=box, physicsMaterial=wood),
+                         position=(0, 5, 0))
+
+for _ in range(120):                       # 2 seconds at 60 Hz
+    world.step(1 / 60)
+
+print(world.position[falling])             # resting on the ground
+```
+
+> The exact `add_body`/`add_shape` signatures are the source of truth in
+> [`world.py`](src/omi_physics/world.py); see the tests for worked examples.
+
+### Off-thread simulation
+
+`ThreadedSimulation` steps the world on a daemon thread and publishes an
+immutable pose snapshot each tick. A renderer reads the latest snapshot every
+frame without ever blocking on the solver:
+
+```python
+from omi_physics.threaded import ThreadedSimulation
+
+sim = ThreadedSimulation(world, sim_hz=120)
+sim.start()
+# ... each render frame:
+snapshot, version = sim.latest()           # (position, axis_angle, awake, dynamic)
+# ... on shutdown:
+sim.stop()
+```
+
+## How it works
+
+One `world.step(dt)` runs this fixed-timestep pipeline over the world's
+structure-of-arrays state:
+
+```mermaid
+flowchart LR
+    A[integrate forces<br/>gravity · damping · drag] --> B[refit AABBs]
+    B --> C[broadphase<br/>sweep & prune]
+    C --> D[narrowphase<br/>SAT · GJK/EPA]
+    D --> E[solver<br/>sequential impulse]
+    E --> F[joints]
+    F --> G[integrate positions]
+    G --> H[sleeping]
+```
+
+The data model is OMI glTF physics (`model.Shape`, `Motion`, `Collider`,
+`Material`, `Joint`, ...), so scenes round-trip to and from glTF documents
+(`omi_physics.omi_gltf`). See [`docs/`](docs/) for a deep dive:
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — components, layering, and how
+  they fit together.
+- [`docs/PIPELINE.md`](docs/PIPELINE.md) — the step pipeline stage by stage, with
+  the data that flows between stages.
+- [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md) — the OMI data model and the
+  structure-of-arrays world state.
+- [`docs/ACCELERATORS.md`](docs/ACCELERATORS.md) — the Cython accelerators and the
+  pure-Python fallback contract.
+
+## Working on omi_physics
+
+```bash
+git clone https://github.com/mcfletch/omi_physics
+cd omi_physics
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"          # editable install, builds the accelerators
+pytest                            # run the test suite
+```
+
+Handy commands:
+
+```bash
+# Rebuild the accelerators in place after editing a .pyx
+python setup.py build_ext --inplace
+
+# Force the pure-Python fallback (delete the compiled modules)
+rm -f src/omi_physics/*.so
+
+# Type-check and lint
+mypy src/omi_physics
+ruff check src tests
+```
+
+The accelerators are a **pure speedup**: every `.pyx` has an identical NumPy/
+Python implementation the engine uses when the compiled module is absent. Tests
+must pass in both configurations (with and without the `.so` files present).
+
+## Layout
+
+```
+src/omi_physics/        the engine (importable as omi_physics)
+  model.py              OMI glTF physics data model
+  world.py              PhysicsWorld — structure-of-arrays state + step()
+  backend.py            NumpyBackend / GPU backend selection
+  glcompute.py          optional GL 4.3 compute integration backend (needs PyOpenGL)
+  broadphase.py         sweep-and-prune + dynamic AABB tree
+  collide.py            SAT box-box, sphere tests (vectorized)
+  gjk.py                GJK/EPA for convex shapes
+  narrowphase.py        contact generation, routes to accelerators
+  solver.py             island-parallel sequential-impulse contact solver
+  joints.py             point / distance / hinge constraints and motors
+  character.py          kinematic character controller
+  cookery.py / hull.py  shape cooking (convex hulls, trimeshes)
+  omi_gltf.py           read/write OMI physics from glTF documents
+  threaded.py           ThreadedSimulation — background-thread stepping
+  _solver_native.pyx    Cython contact solver accelerator
+  _collide_native.pyx   Cython collision accelerator
+tests/                  pytest suite (pure NumPy; GPU-parity tests skip w/o GL)
+docs/                   deep-dive documentation (Markdown + Mermaid)
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

omi_physics-0.1.0/README.md

@@ -0,0 +1,164 @@
+# omi_physics
+
+A renderer-agnostic, real-time **rigid-body physics engine** for Python, built
+natively on the [OMI glTF physics](https://github.com/omigroup/gltf-extensions)
+data model. State lives in flat NumPy arrays, the whole step pipeline is
+vectorized, and optional compiled Cython accelerators drop in transparently for
+the hot paths (the contact solver and box/sphere collision).
+
+- **NumPy is the only hard dependency.** No graphics library is required to
+  simulate.
+- **PyOpenGL is optional** — used solely by the experimental GPU compute backend
+  (`omi_physics.glcompute`).
+- **Deterministic** on the CPU backend: the same inputs produce the same
+  trajectory, run to run.
+- **Fast**: sweep-and-prune broadphase, SAT/GJK narrowphase, an island-parallel
+  sequential-impulse solver, sleeping, and a background-threaded simulation loop
+  that overlaps with a consumer's render/IO thread.
+
+> ⚠️ **This code is largely LLM-written.** It has a test suite and the CPU
+> backend is deterministic, but it comes with **no guarantees** of correctness,
+> accuracy, or fitness for any purpose (see [`LICENSE`](LICENSE), MIT). Review it
+> before relying on it for anything that matters.
+
+## Install
+
+```bash
+pip install omi_physics            # core engine (NumPy only)
+pip install "omi_physics[gl]"      # + PyOpenGL for the GPU compute backend
+```
+
+Prebuilt wheels ship the compiled accelerators, so no C compiler is needed. A
+source install without a compiler still works — the engine falls back to the
+identical pure-NumPy code paths.
+
+## Quick start
+
+```python
+import numpy as np
+from omi_physics import PhysicsWorld, model
+
+world = PhysicsWorld(gravity=model.Gravity(gravity=9.81, direction=(0, -1, 0)))
+
+# A static ground box and a dynamic box that falls onto it.
+ground = world.add_shape(model.Shape.box((20, 1, 20)))
+box    = world.add_shape(model.Shape.box((1, 1, 1)))
+wood   = world.add_material(model.Material())
+
+world.add_body(model.Motion(type=model.STATIC),
+               collider=model.Collider(shape=ground, physicsMaterial=wood),
+               position=(0, 0, 0))
+falling = world.add_body(model.Motion(type=model.DYNAMIC, mass=1.0),
+                         collider=model.Collider(shape=box, physicsMaterial=wood),
+                         position=(0, 5, 0))
+
+for _ in range(120):                       # 2 seconds at 60 Hz
+    world.step(1 / 60)
+
+print(world.position[falling])             # resting on the ground
+```
+
+> The exact `add_body`/`add_shape` signatures are the source of truth in
+> [`world.py`](src/omi_physics/world.py); see the tests for worked examples.
+
+### Off-thread simulation
+
+`ThreadedSimulation` steps the world on a daemon thread and publishes an
+immutable pose snapshot each tick. A renderer reads the latest snapshot every
+frame without ever blocking on the solver:
+
+```python
+from omi_physics.threaded import ThreadedSimulation
+
+sim = ThreadedSimulation(world, sim_hz=120)
+sim.start()
+# ... each render frame:
+snapshot, version = sim.latest()           # (position, axis_angle, awake, dynamic)
+# ... on shutdown:
+sim.stop()
+```
+
+## How it works
+
+One `world.step(dt)` runs this fixed-timestep pipeline over the world's
+structure-of-arrays state:
+
+```mermaid
+flowchart LR
+    A[integrate forces<br/>gravity · damping · drag] --> B[refit AABBs]
+    B --> C[broadphase<br/>sweep & prune]
+    C --> D[narrowphase<br/>SAT · GJK/EPA]
+    D --> E[solver<br/>sequential impulse]
+    E --> F[joints]
+    F --> G[integrate positions]
+    G --> H[sleeping]
+```
+
+The data model is OMI glTF physics (`model.Shape`, `Motion`, `Collider`,
+`Material`, `Joint`, ...), so scenes round-trip to and from glTF documents
+(`omi_physics.omi_gltf`). See [`docs/`](docs/) for a deep dive:
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — components, layering, and how
+  they fit together.
+- [`docs/PIPELINE.md`](docs/PIPELINE.md) — the step pipeline stage by stage, with
+  the data that flows between stages.
+- [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md) — the OMI data model and the
+  structure-of-arrays world state.
+- [`docs/ACCELERATORS.md`](docs/ACCELERATORS.md) — the Cython accelerators and the
+  pure-Python fallback contract.
+
+## Working on omi_physics
+
+```bash
+git clone https://github.com/mcfletch/omi_physics
+cd omi_physics
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"          # editable install, builds the accelerators
+pytest                            # run the test suite
+```
+
+Handy commands:
+
+```bash
+# Rebuild the accelerators in place after editing a .pyx
+python setup.py build_ext --inplace
+
+# Force the pure-Python fallback (delete the compiled modules)
+rm -f src/omi_physics/*.so
+
+# Type-check and lint
+mypy src/omi_physics
+ruff check src tests
+```
+
+The accelerators are a **pure speedup**: every `.pyx` has an identical NumPy/
+Python implementation the engine uses when the compiled module is absent. Tests
+must pass in both configurations (with and without the `.so` files present).
+
+## Layout
+
+```
+src/omi_physics/        the engine (importable as omi_physics)
+  model.py              OMI glTF physics data model
+  world.py              PhysicsWorld — structure-of-arrays state + step()
+  backend.py            NumpyBackend / GPU backend selection
+  glcompute.py          optional GL 4.3 compute integration backend (needs PyOpenGL)
+  broadphase.py         sweep-and-prune + dynamic AABB tree
+  collide.py            SAT box-box, sphere tests (vectorized)
+  gjk.py                GJK/EPA for convex shapes
+  narrowphase.py        contact generation, routes to accelerators
+  solver.py             island-parallel sequential-impulse contact solver
+  joints.py             point / distance / hinge constraints and motors
+  character.py          kinematic character controller
+  cookery.py / hull.py  shape cooking (convex hulls, trimeshes)
+  omi_gltf.py           read/write OMI physics from glTF documents
+  threaded.py           ThreadedSimulation — background-thread stepping
+  _solver_native.pyx    Cython contact solver accelerator
+  _collide_native.pyx   Cython collision accelerator
+tests/                  pytest suite (pure NumPy; GPU-parity tests skip w/o GL)
+docs/                   deep-dive documentation (Markdown + Mermaid)
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

omi_physics-0.1.0/docs/ACCELERATORS.md

@@ -0,0 +1,85 @@
+# Accelerators
+
+The two hot stages — the contact **solver** and box/sphere **collision** — have
+optional Cython implementations that compile to native code. They are a **pure
+speedup**: when the compiled module is present the engine uses it; when it is
+absent the engine runs an identical NumPy/Python implementation and produces the
+same results. Nothing else in the code changes.
+
+| Accelerator | Replaces | Used by |
+| --- | --- | --- |
+| `_solver_native.pyx` | sequential-impulse inner loops (constraint prep, warm start, velocity + position iterations) | `solver.py` |
+| `_collide_native.pyx` | SAT box-box (with Sutherland–Hodgman clipping), sphere-sphere, sphere-box | `narrowphase.py` |
+
+## The fallback contract
+
+Each consumer imports its accelerator inside a `try` / `except ImportError`, sets
+the module to `None` on failure, and guards every call site:
+
+```python
+# solver.py
+try:
+    from . import _solver_native as _native   # compiled Cython inner loops
+except ImportError:
+    _native = None
+...
+if _native is not None and hasattr(_native, 'prepare_and_solve'):
+    self._solve_native_full(world, contacts)   # native path
+else:
+    ...                                        # identical NumPy/Python path
+```
+
+```mermaid
+flowchart TD
+    CALL[stage runs] --> Q{compiled module<br/>importable?}
+    Q -->|yes| N[native path<br/>_solver_native / _collide_native]
+    Q -->|no| P[pure NumPy / Python path]
+    N --> R[result]
+    P --> R
+    R --> SAME([same numbers, either way])
+```
+
+The `hasattr` check is deliberate: it means a partially-built or older accelerator
+missing a given entry point still degrades to the Python path for that call rather
+than crashing.
+
+## Why these two, and how they stay honest
+
+Integration and broadphase are already whole-array NumPy operations — they are as
+fast as they are going to get without leaving Python, and there is little to gain
+from native code. The solver and narrow phase are different: they are inherently
+**per-contact, sequential** work (Gauss–Seidel resolves each contact reading the
+velocities the previous contact just wrote), which NumPy cannot vectorize away. So
+those are the loops worth compiling.
+
+Because both paths must agree, the accelerators are **differential-tested**: the
+test suite exercises the same scenes with and without the compiled modules and
+asserts the trajectories match. When you change a `.pyx`, keep its Python twin in
+lockstep and run the suite both ways:
+
+```bash
+pytest                            # with the compiled .so present
+rm -f src/omi_physics/*.so
+pytest                            # pure-Python fallback
+python setup.py build_ext --inplace   # rebuild
+```
+
+## Building
+
+The accelerators build from source via `setup.py`, which cythonizes the `.pyx`
+files (falling back to shipped `.c` if Cython is unavailable) and **never fails
+the install** — a missing compiler just leaves the pure-Python path in place:
+
+```mermaid
+flowchart LR
+    PYX[".pyx source"] -->|Cython present| C[".c"]
+    C -->|C compiler present| SO[".so compiled module"]
+    PYX -.->|no Cython, shipped .c| C
+    C -.->|no compiler| FB[skip → pure-Python fallback]
+    SO --> WHEEL[wheel ships the .so]
+```
+
+Prebuilt wheels (built in CI with `cibuildwheel`) carry the compiled `.so` for
+each supported Python and platform, plus the `.pyx` sources so a source install
+can still rebuild. End users therefore get native speed with no compiler; source
+installs without a toolchain still work, only slower.

omi_physics-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,99 @@
+# Architecture
+
+`omi_physics` is a rigid-body engine whose state lives in flat NumPy arrays and
+whose simulation runs as a fixed-timestep pipeline of vectorized stages. Nothing
+in the core touches a graphics library; a renderer (or a network layer, or a
+head-less test) sits *outside* and reads poses back each frame.
+
+## Layers
+
+```mermaid
+flowchart TD
+    subgraph consumer["Consumer (your app) — outside omi_physics"]
+        R[renderer / game loop / test]
+    end
+
+    subgraph api["Public API"]
+        W[PhysicsWorld<br/>world.py]
+        TS[ThreadedSimulation<br/>threaded.py]
+        M[model.py<br/>OMI data model]
+        G[omi_gltf.py<br/>glTF read/write]
+    end
+
+    subgraph pipeline["Step pipeline"]
+        BK[backend.py<br/>Numpy / GPU]
+        BP[broadphase.py]
+        NP[narrowphase.py]
+        CO[collide.py · gjk.py]
+        SV[solver.py]
+        JO[joints.py]
+        TR[triggers.py]
+        SL[sleeping]
+    end
+
+    subgraph accel["Optional accelerators"]
+        SN[_solver_native.pyx]
+        CN[_collide_native.pyx]
+    end
+
+    subgraph opt["Optional GL (PyOpenGL)"]
+        GC[glcompute.py]
+    end
+
+    R -->|step / latest| W
+    R --> TS
+    TS --> W
+    W --> M
+    G <--> M
+    W --> BK
+    BK --> BP
+    BP -->|solid pairs| NP --> SV --> JO --> SL
+    BP -->|trigger pairs| TR
+    TR -->|enter/exit events| W
+    NP --> CO
+    SV -. uses when present .-> SN
+    NP -. uses when present .-> CN
+    BK -. GPU backend .-> GC
+```
+
+The arrows into the accelerators are dashed because they are **optional**: when
+the compiled modules are absent, the same stages run their pure-NumPy code. GL is
+similarly optional — only `glcompute.py` imports PyOpenGL, and only when a caller
+explicitly selects the GPU backend.
+
+## Modules
+
+| Module | Responsibility |
+| --- | --- |
+| `model.py` | The OMI glTF physics data model: `Shape`, `Motion`, `Collider`, `Trigger`, `Material`, `CollisionFilter`, `Gravity`, `Joint`. Immutable dataclasses. |
+| `world.py` | `PhysicsWorld` — the structure-of-arrays state and the `step(dt)` that advances it. Source of truth for the simulation. |
+| `mathutil.py` | Quaternion / matrix helpers, batched (`quat_integrate`, `quat_to_axis_angle`, `quat_to_matrix`, `cross3`). |
+| `backend.py` | The compute-backend surface. `NumpyBackend` is the CPU path; `select_backend()` picks CPU vs GPU. |
+| `glcompute.py` | `GLComputeBackend` — per-body integration as GL 4.3 compute shaders. Requires PyOpenGL; falls back to NumPy. |
+| `broadphase.py` | Sweep-and-prune plus a dynamic AABB tree; produces candidate overlapping pairs. |
+| `collide.py` | Vectorized SAT box-box and sphere tests producing contact manifolds. |
+| `gjk.py` | GJK/EPA for general convex shapes. |
+| `narrowphase.py` | Turns broadphase pairs into contacts; routes box/sphere pairs to `_collide_native` when present. |
+| `solver.py` | Island-parallel sequential-impulse contact solver with warm starting; routes to `_solver_native` when present. |
+| `joints.py` | Point, distance, and hinge constraints and angular motors. |
+| `triggers.py` | Non-solid trigger volumes and enter/exit events. |
+| `character.py` | A kinematic character controller (walking, stepping, slopes). |
+| `cookery.py`, `hull.py` | Shape "cooking": convex hull / trimesh preparation. |
+| `omi_gltf.py` | Read OMI physics bodies out of a glTF document and write them back. |
+| `threaded.py` | `ThreadedSimulation` — runs `step()` on a daemon thread, publishes snapshots. |
+
+## Design principles
+
+- **Structure-of-arrays, not array-of-structs.** Every per-body quantity is one
+  contiguous NumPy column, so each stage is a whole-array operation over the
+  awake bodies rather than a Python loop. This is what makes the CPU path fast
+  and what makes a future full-GPU residency plausible.
+- **Renderer-agnostic core.** The world never imports a scene graph or a GL
+  binding. Consumers read `world.position` / `world.orientation` (or a
+  `ThreadedSimulation` snapshot) and draw however they like.
+- **Accelerators are a pure speedup.** Each `.pyx` mirrors a NumPy/Python
+  implementation exactly; the engine imports the compiled module when present and
+  is otherwise unchanged. See [ACCELERATORS.md](ACCELERATORS.md).
+- **Deterministic on CPU.** The NumPy backend is float64 and order-stable, so a
+  scene replays identically. The GPU backend is float32 and matches only within
+  tolerance — a deliberate trade for scale.