Source code for simvx.core.physics.capability

"""Capability gate: the small, dimension-agnostic feature-advertisement enum.

Role
----
The strict Tier-1 :class:`~simvx.core.physics.world.PhysicsWorld` ABC is the
**parity contract**: every backend implements the *same* rigid-body surface, so
a node never branches on which backend it got. A handful of features, however,
are genuinely backend-specific and cannot be faked by the pure-Python builtin
tier (cross-platform bit-exact determinism, vehicle constraints, soft bodies).
Those are advertised, not promised: a Tier-3 node queries
:meth:`PhysicsWorld.capabilities` and degrades / refuses if the resolved backend
does not list the :class:`Capability` it needs.

This is deliberately a *small* additive enum + one method, NOT an audio-style
Protocol-facet split of the whole seam. The seam stays a single strict ABC; the
capability set is the only place backend tiers diverge in what they claim.
``Capability`` is dimension-agnostic (shared by the 2D and 3D seams) and lives in
its own module so both ``world.py`` and ``world2d.py`` import it without a cycle.
"""

from __future__ import annotations

from enum import StrEnum




class Capability(StrEnum):
    """A Tier-3-only feature a backend may advertise via ``capabilities()``.

    The builtin pure-Python backend advertises NONE of these: it is an honest
    Tier-1 rigid-body solver. An optional native backend (Jolt, pymunk) lists
    only the capabilities it actually honours. A node needing one of these MUST
    check ``Capability.X in world.capabilities()`` first; the seam never silently
    pretends to support a capability it lacks.

    Members:
        DETERMINISTIC: Cross-platform bit-exact stepping (e.g. a Jolt build
            compiled with ``JPH_CROSS_PLATFORM_DETERMINISTIC``). Needed for
            lockstep netcode / replays; the builtin backend's float maths is
            reproducible on one machine but not bit-identical across platforms.
        VEHICLES: Specialised vehicle constraints (wheeled / tracked raycast
            vehicles). Not expressible with the basic joint set.
        SOFT_BODY: Deformable soft-body / cloth simulation. Outside the
            rigid-body seam entirely.
    """

    DETERMINISTIC = "deterministic"
    VEHICLES = "vehicles"
    SOFT_BODY = "soft_body"



__all__ = ["Capability"]