simvx.core.physics.query

Role

The seam (:class:~simvx.core.physics.world.PhysicsWorld) is node-agnostic: its queries return opaque body HANDLES (and seam-level RaycastHit / Contact keyed by handle). :class:PhysicsQuery is the thin node-facing wrapper that maps those handles back to scene nodes (via the tree’s register_physics_node registry) and applies node-level filters (exclude= a set of nodes), returning typed :class:RayHit / :class:ShapeHit results (or plain nodes for overlap).

It is constructed fresh per node.physics access (cold path; see Node.physics) bound to (world, node_map) where node_map is the per-world handle -> Node weak map. The seam never learns about nodes; all handle->node mapping happens here.

Node-level spatial query API for the new physics seam (Stage R2b).

Module Contents

Classes

RayHit	A node-level raycast result (mapped from the seam’s RaycastHit).
ShapeHit	A node-level shapecast result (mapped from the seam’s Contact).
PhysicsQuery	Node-facing spatial query wrapper over a :class:PhysicsWorld.

Data

__all__

API

simvx.core.physics.query.__all__

[‘RayHit’, ‘ShapeHit’, ‘PhysicsQuery’]

class simvx.core.physics.query.RayHit

A node-level raycast result (mapped from the seam’s RaycastHit).

Distinct from the node-agnostic seam RaycastHit (keyed by a body handle): this carries the resolved scene node, so user code never touches handles. Always truthy, so if hit: reads naturally; a miss is None (falsy).

Attributes: node: The body node the ray hit. point: World-space contact point (Vec3). normal: World-space surface normal at the hit (Vec3, unit length). distance: Distance from the ray origin to point along the ray.

node: simvx.core.physics.nodes.PhysicsBody3D

None

point: simvx.core.math.Vec3

None

normal: simvx.core.math.Vec3

None

distance: float

None

__bool__() → bool

class simvx.core.physics.query.ShapeHit

A node-level shapecast result (mapped from the seam’s Contact).

Mirrors :class:RayHit for a swept-shape query; a miss is None.

Attributes: node: The body node the shape swept into. point: World-space contact point (Vec3). normal: World-space separating normal pointing back toward the cast origin (Vec3, unit length). distance: Time-of-impact distance along the cast direction.

node: simvx.core.physics.nodes.PhysicsBody3D

None

point: simvx.core.math.Vec3

None

normal: simvx.core.math.Vec3

None

distance: float

None

class simvx.core.physics.query.PhysicsQuery(world: simvx.core.physics.world.PhysicsWorld, node_map: weakref.WeakValueDictionary[simvx.core.physics.world.BodyHandle, simvx.core.node.Node] | None)

Node-facing spatial query wrapper over a :class:PhysicsWorld.

Bound to one world and that world’s handle -> Node map. Exposes

Meth:

raycast / :meth:raycast_all / :meth:shapecast / :meth:overlap with typed results and keyword-only mask / exclude / distance filters. Constructed fresh per node.physics access; bind it locally if a hot loop wants to avoid the per-call construction.

node_map may be None (no bodies registered in this world yet); then every hit maps to None and is dropped, so queries against an empty world return None / [] rather than raising.

Initialization

__slots__

(‘_world’, ‘_node_map’)

raycast(origin: simvx.core.math.Vec3, direction: simvx.core.math.Vec3, *, distance: float = math.inf, mask: int = 4294967295, exclude: set[simvx.core.node.Node] | None = None) → simvx.core.physics.query.RayHit | None

Cast a ray, return the nearest non-excluded hit, or None.

With no exclude the seam’s single-nearest :meth:raycast is used directly. With exclude (the nearest hit might be an excluded node) it falls back to :meth:raycast_all and returns the first non-excluded hit, so an excluded body never shadows a farther real one.

Args: origin: Ray origin (Vec3). direction: Ray direction (Vec3); need not be normalised. distance: Maximum ray distance (default unbounded). mask: Query layer mask (matched against each body’s layer). exclude: Optional set of nodes to ignore (e.g. {self}).

Returns: The nearest :class:RayHit, or None on miss / all-excluded.

raycast_all(origin: simvx.core.math.Vec3, direction: simvx.core.math.Vec3, *, distance: float = math.inf, mask: int = 4294967295, exclude: set[simvx.core.node.Node] | None = None) → list[simvx.core.physics.query.RayHit]

Cast a ray, return ALL non-excluded hits sorted by distance.

Drops hits whose handle is unmapped (transient/destroyed body) or whose node is in exclude.

Args: origin: Ray origin (Vec3). direction: Ray direction (Vec3); need not be normalised. distance: Maximum ray distance (default unbounded). mask: Query layer mask. exclude: Optional set of nodes to ignore.

Returns: List of :class:RayHit, ascending by distance (empty on miss).

shapecast(shape: simvx.core.physics.shapes.Shape, origin: simvx.core.math.Vec3, direction: simvx.core.math.Vec3, *, distance: float = math.inf, mask: int = 4294967295, exclude: set[simvx.core.node.Node] | None = None) → simvx.core.physics.query.ShapeHit | None

Sweep a shape resource along a ray, return the earliest-TOI hit.

The wrapper owns building the transient seam shape handle from the

Class:

Shape resource, keeping the public API node-level (the user passes geometry, never an opaque handle).

A swept shape needs a bounded sweep length, so unlike :meth:raycast distance must be FINITE (the substepped basic-tier cast cannot size an unbounded sweep); pass an explicit distance.

Args: shape: A :class:Shape resource (SphereShape3D / BoxShape3D). origin: Cast origin (Vec3). direction: Cast direction (Vec3); need not be normalised. distance: Maximum sweep distance (must be finite). mask: Query layer mask. exclude: Optional set of nodes to ignore.

Returns: The earliest-TOI :class:ShapeHit, or None on miss / excluded / unmapped.

overlap(shape: simvx.core.physics.shapes.Shape, transform: object, *, mask: int = 4294967295, exclude: set[simvx.core.node.Node] | None = None) → list[simvx.core.physics.nodes.PhysicsBody3D]

Return all bodies a static shape overlaps at transform.

Returns plain nodes (not typed hits): an overlap has no single point / normal / distance (design S9). Drops unmapped and excluded handles.

Args: shape: A :class:Shape resource. transform: World pose to place the shape at (same flexible forms the seam accepts: Transform3D / Vec3 / (pos, rot)). mask: Query layer mask. exclude: Optional set of nodes to ignore.

Returns: List of overlapping body nodes (empty if none / all dropped).