simvx.core.physics._shape_owner

Per-resource ownership of backend collision-shape handles.

A Shape / Shape2D resource owns the backend shape it was built into, the same model :class:~simvx.core.resources.Mesh and materials already follow: the handle lives exactly as long as the resource that asked for it, and is released when that resource is collected. One resource can be live in several worlds at once (a scene running a 3D world and a preview world), so the ownership record is a small per-world table rather than a single handle.

Worlds are held WEAKLY. A world that has already been collected has taken its whole shape table with it, so there is nothing to release and nothing to keep alive; holding it strongly would instead make every shape resource pin the world it was ever used in.

Module Contents

Classes

OwnedShapeHandles

The backend handles one shape resource owns, one per world it was built in.

Functions

build_owned

Return resource’s handle in world, building it once on first ask.

API

class simvx.core.physics._shape_owner.OwnedShapeHandles

The backend handles one shape resource owns, one per world it was built in.

Keyed by id(world) for a dict-speed lookup on the build path, with the world’s own weak reference stored alongside so a recycled id can never be mistaken for a live entry: the stored reference is compared against the world being asked about, and a dead world drops its row through the weakref callback the moment it is collected.

Initialization

__slots__

(‘_entries’, ‘weakref’)

get(world: object) → Any | None

Return the handle this resource owns in world, or None.

put(world: object, handle: Any) → None

Record handle as this resource’s handle in world.

release() → None

Destroy every handle this resource owns, in every world still alive.

Runs from the resource’s finaliser, so it must never touch the resource itself. Destroying a handle a body is still built on is safe and deliberate: a backend reaches a body’s geometry through the body’s own record, so the body keeps simulating (see PhysicsWorld.destroy_shape).

simvx.core.physics._shape_owner.build_owned(resource: object, world: object, create: Any) → Any

Return resource’s handle in world, building it once on first ask.

The memo behind the shape contract: a resource asked twice for the same world hands back the same handle, so every body built from one resource shares one backend record however many times the resource is consulted. The first build also arms the finaliser that releases the handles when resource dies.

Args: resource: The shape resource that will own the handle. world: The physics world to build into. create: Zero-argument factory called only on a miss.

Returns: The opaque backend shape handle resource owns in world.