`simvx.core.physics.backends`¶

Precedence (most specific wins)¶

An explicit PhysicsRoot(backend=...) override on the node.
The project / App-level physics_backend setting (GeneralConfig, .simvx/config.json).
An auto-discovered installed native backend package.
The pure-Python :class:~simvx.core.physics.builtin.BuiltinPhysics default.

Only the resolution lives here; the consumers (PhysicsRoot and the tree’s default world) call :func:resolve_world_factory / :func:resolve_world_factory_2d to get a ready-to-call :data:~simvx.core.physics.root.WorldFactory for the chosen backend. This keeps backend choice out of the resolution walk in root.py (which only finds which world a node belongs to, never which kind).

Auto-discovery seam (arm 3)¶

There is no native backend yet (Jolt / pymunk are future work), so the auto-discovery arm resolves to Builtin today. It is nonetheless the single, real plug point a future backend registers through, mirroring the engine’s miniaudio “installed -> used” model: a native package, on import, calls

func:: register_backend (e.g. from its __init__ or a simvx.physics.backends entry point) to add itself to :data:_REGISTRY; once registered it is both auto-discoverable (arm 3) and addressable by name (arm 2 / arm 1). Until one exists, the registry holds only "builtin" and every arm collapses to Builtin.

Backend selection: the single place a physics backend is chosen.

Module Contents¶

Classes¶

BackendEntry

A registered physics backend: its name + 3D / 2D world factories.

Functions¶

`register_backend`	Register a physics backend so it is name-addressable and auto-discoverable.
`resolve_backend_name`	Resolve the backend NAME by precedence: explicit > setting > auto > builtin.
`resolve_world_factory`	Return the 3D :data:`WorldFactory` for the resolved backend.
`resolve_world_factory_2d`	Return the 2D :data:`WorldFactory2D` for the resolved backend.

Data¶

`log`
`BUILTIN`
`__all__`

API¶

simvx.core.physics.backends.log¶: ‘getLogger(…)’

simvx.core.physics.backends.BUILTIN¶: ‘builtin’

class simvx.core.physics.backends.BackendEntry[source]¶

A registered physics backend: its name + 3D / 2D world factories.

A native backend registers one of these via :func:register_backend. A backend may support only one dimension; the missing factory is None and resolution for that dimension falls through to Builtin (with a warning) rather than failing, so a 3D-only native backend never breaks a 2D scene.

Attributes: name: The token used in physics_backend config / PhysicsRoot(backend=). world_factory: Builds a 3D world for a given gravity, or None. world_factory_2d: Builds a 2D world for a given gravity, or None. native: True for an installed native backend (auto-discoverable), False for the always-present Builtin (never auto-selected over a native one; it is the final fallback).

name: str¶: None

world_factory: simvx.core.physics.root.WorldFactory | None¶: None

world_factory_2d: simvx.core.physics.root.WorldFactory2D | None¶: None

native: bool¶: True

simvx.core.physics.backends.register_backend(entry: simvx.core.physics.backends.BackendEntry) → None[source]¶

The single plug point for a future native backend (Jolt, pymunk): the native package calls this on import to add itself, mirroring miniaudio’s “installed -> used” model. Re-registering the same name replaces the entry (idempotent for re-import). "builtin" is reserved as the fallback name.

Args: entry: The :class:BackendEntry to register.

Raises: ValueError: If entry.name is "builtin" (reserved) or empty.

simvx.core.physics.backends.resolve_backend_name(explicit: str | None, setting: str | None) → str[source]¶

Resolve the backend NAME by precedence: explicit > setting > auto > builtin.

Args: explicit: A PhysicsRoot(backend=...) override, or None if unset. setting: The project/App physics_backend config value, or None / empty if unset.

Returns: The resolved backend name (a key of :data:_REGISTRY). An explicit / setting value that names an unknown backend logs a warning and falls back to the next arm (auto, then Builtin) rather than raising: a missing optional native backend degrades to Builtin, it does not crash the game.

simvx.core.physics.backends.resolve_world_factory(explicit: str | None = None) → simvx.core.physics.root.WorldFactory[source]¶

Return the 3D :data:WorldFactory for the resolved backend.

Applies the full precedence (explicit > project setting > auto > Builtin) and returns the chosen backend’s 3D factory. If the chosen backend has no 3D factory (a 2D-only native backend), falls back to Builtin’s 3D factory.

Args: explicit: A PhysicsRoot(backend=...) override, or None.

Returns: A callable (gravity: Vec3) -> PhysicsWorld.

simvx.core.physics.backends.resolve_world_factory_2d(explicit: str | None = None) → simvx.core.physics.root.WorldFactory2D[source]¶

Return the 2D :data:WorldFactory2D for the resolved backend.

2D sibling of :func:resolve_world_factory. Falls back to Builtin’s 2D factory when the chosen backend has no 2D factory (a 3D-only native backend).

Args: explicit: A PhysicsRoot2D(backend=...) override, or None.

Returns: A callable (gravity: Vec2) -> Physics2DWorld.

simvx.core.physics.backends.__all__¶: [‘BUILTIN’, ‘BackendEntry’, ‘register_backend’, ‘resolve_backend_name’, ‘resolve_world_factory’, ‘re…

simvx.core.physics.backends¶