tilemap-parser 4.2.8__tar.gz → 5.0.1__tar.gz

{tilemap_parser-4.2.8 → tilemap_parser-5.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tilemap-parser
-Version: 4.2.8
+Version: 5.0.1
 Summary: Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime.
 Author: tilemap parser contributors
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -765,6 +765,40 @@ particle_config = ParticleSystemConfig(
 particles = ParticleSystem(particle_config)
 ```
 
+## Physics bodies
+
+A `PhysicsWorld` is a single space holding the tile layer plus solid `Body` objects (static walls, kinematic crates). Attach a `CollisionRunner` to the world once and every move method resolves tiles and bodies through it — no per-call tile arguments.
+
+> Full contract — object↔world↔`move_*`↔tiles↔rendering: see [docs/physics-world.md](docs/physics-world.md) and `examples/physics-crate/main.py`.
+
+```python
+from tilemap_parser import (
+    Body, PhysicsWorld, CollisionRunner, RectangleShape,
+    TilemapData, TilesetCollision, CollisionCache,
+)
+
+cache = CollisionCache()
+tileset = cache.get_tileset_collision("data/collision/tileset.collision.json")
+world = PhysicsWorld.from_map(game_data, tileset)   # adopts tile_size / render_scale
+
+crate = Body(RectangleShape(width=16, height=16), x=320, y=480, mode="kinematic")
+world.add_body(crate)
+
+runner = CollisionRunner.from_world(world)          # or runner.attach(world)
+```
+
+Pushable crates are just kinematic bodies moved with an explicit velocity (gravity is skipped when `velocity=` is given):
+
+```python
+# player pressed against the crate -> hand the player's vx over
+crate.vx = player.vx
+result = runner.move_grounded(crate, None, None, dt, velocity=(crate.vx, 0))
+if result.hit_wall_x:
+    crate.vx = 0  # crate stopped against a tile wall or another body
+```
+
+`Body` accepts primitive shapes only (`RectangleShape`, `CircleShape`, `CapsuleShape`); use `MapObject` for polygon solids. Collision pairs honor both sides' `collision_layer` / `collision_mask`, and bodies are landing surfaces for platformer step-up (small crates are climbed, tall ones block like walls).
+
 ## Links
 
 - **Docs**: [https://deepwiki.com/FluffyBrudy/tilemap-parser](https://deepwiki.com/FluffyBrudy/tilemap-parser)

{tilemap_parser-4.2.8 → tilemap_parser-5.0.1}/README.md

@@ -66,6 +66,40 @@ particle_config = ParticleSystemConfig(
 particles = ParticleSystem(particle_config)
 ```
 
+## Physics bodies
+
+A `PhysicsWorld` is a single space holding the tile layer plus solid `Body` objects (static walls, kinematic crates). Attach a `CollisionRunner` to the world once and every move method resolves tiles and bodies through it — no per-call tile arguments.
+
+> Full contract — object↔world↔`move_*`↔tiles↔rendering: see [docs/physics-world.md](docs/physics-world.md) and `examples/physics-crate/main.py`.
+
+```python
+from tilemap_parser import (
+    Body, PhysicsWorld, CollisionRunner, RectangleShape,
+    TilemapData, TilesetCollision, CollisionCache,
+)
+
+cache = CollisionCache()
+tileset = cache.get_tileset_collision("data/collision/tileset.collision.json")
+world = PhysicsWorld.from_map(game_data, tileset)   # adopts tile_size / render_scale
+
+crate = Body(RectangleShape(width=16, height=16), x=320, y=480, mode="kinematic")
+world.add_body(crate)
+
+runner = CollisionRunner.from_world(world)          # or runner.attach(world)
+```
+
+Pushable crates are just kinematic bodies moved with an explicit velocity (gravity is skipped when `velocity=` is given):
+
+```python
+# player pressed against the crate -> hand the player's vx over
+crate.vx = player.vx
+result = runner.move_grounded(crate, None, None, dt, velocity=(crate.vx, 0))
+if result.hit_wall_x:
+    crate.vx = 0  # crate stopped against a tile wall or another body
+```
+
+`Body` accepts primitive shapes only (`RectangleShape`, `CircleShape`, `CapsuleShape`); use `MapObject` for polygon solids. Collision pairs honor both sides' `collision_layer` / `collision_mask`, and bodies are landing surfaces for platformer step-up (small crates are climbed, tall ones block like walls).
+
 ## Links
 
 - **Docs**: [https://deepwiki.com/FluffyBrudy/tilemap-parser](https://deepwiki.com/FluffyBrudy/tilemap-parser)

{tilemap_parser-4.2.8 → tilemap_parser-5.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tilemap-parser"
-version = "4.2.8"
+version = "5.0.1"
 description = "Standalone parser/loader for tilemap-editor JSON maps, sprite animations, and collision detection runtime."
 readme = "README.md"
 requires-python = ">=3.10"

{tilemap_parser-4.2.8 → tilemap_parser-5.0.1}/src/tilemap_parser/runtime/__init__.py

@@ -1,5 +1,7 @@
 from .camera import Camera
 from .animation_player import AnimationPlayer, SpriteAnimationSet
+from .body import Body
+from .world import PhysicsWorld
 from .collision_cache import (
     CollisionCache,
     clear_collision_cache,
@@ -11,18 +13,12 @@ from .collision_cache import (
     load_tileset_collision,
 )
 from .map_object import MapObject, load_map_objects
-from .tile_collision import (
-    CollisionResult,
-    CollisionRunner,
-    ICollidableSprite,
-    MovementMode,
-    rect_vs_tilemap,
-)
-from .protocols import ICollidable
+from .movement import CollisionResult, CollisionRunner, MovementMode
+from .polygon_query import rect_vs_tilemap
+from .protocols import ICollidable, ICollidableObject, ICollidableSprite
 from .map_loader import TilemapData, load_map
-from .object_collision import (
+from .collision import (
     CollisionHit,
-    ICollidableObject,
     ObjectCollisionManager,
     check_collision,
 )
@@ -42,6 +38,7 @@ from .particles import (
 __all__ = [
     "AnimationPlayer",
     "AreaNode",
+    "Body",
     "Camera",
     "CollisionCache",
     "CollisionHit",
@@ -72,6 +69,7 @@ __all__ = [
     "ParticleEmitterNode",
     "ParticleRenderer",
     "ParticleSystem",
+    "PhysicsWorld",
     "rect_vs_tilemap",
     "SpriteBatchRenderer",
     "clear_texture_caches",

tilemap_parser-5.0.1/src/tilemap_parser/runtime/body.py

@@ -0,0 +1,198 @@
+"""Physics bodies authored into a :class:`~.world.PhysicsWorld`.
+
+A :class:`Body` is the authoring surface for a solid in the world.  It owns
+a single primitive collision shape (rectangle, circle, or capsule — polygon
+shapes stay in the ``MapObject`` lane) plus its position and velocity, and
+participates in collision detection through the same
+``ICollidableObject`` contract as :class:`~.map_object.MapObject`
+(owner-local shape, ``obj.x + vertex`` applied once by the narrowphase).
+
+Bodies are NOT self-moving.  ``mode == "kinematic"`` marks a body the game
+moves explicitly each frame (e.g. a crate pushed with ``move_grounded``);
+``mode == "static"`` marks a body that never moves (e.g. scenery, furniture).
+Neither mode implies physics-engine dynamics — velocity is scripted, Godot
+``StaticBody2D`` / ``CharacterBody2D`` style.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional, Tuple
+
+from ..parser.collision import (
+    CapsuleShape,
+    CircleShape,
+    CollisionPolygon,
+    RectangleShape,
+)
+
+BodyMode = str  # "static" | "kinematic"
+
+BODY_MODES = ("static", "kinematic")
+
+BodyShape = RectangleShape | CircleShape | CapsuleShape
+
+
+class Body:
+    """A solid body with a single primitive collision shape."""
+
+    __slots__ = (
+        "collision_layer",
+        "collision_mask",
+        "collision_shape",
+        "game_id",
+        "mode",
+        "on_ground",
+        "vx",
+        "vy",
+        "x",
+        "y",
+    )
+
+    def __init__(
+        self,
+        collision_shape: BodyShape,
+        x: float = 0.0,
+        y: float = 0.0,
+        *,
+        vx: float = 0.0,
+        vy: float = 0.0,
+        mode: BodyMode = "static",
+        collision_layer: int = 1,
+        collision_mask: int = 0xFFFFFFFF,
+        game_id: str = "",
+    ):
+        """
+        Create a body.
+
+        Args:
+            collision_shape: Primitive shape (RectangleShape, CircleShape,
+                or CapsuleShape).  Polygon shapes are not supported on
+                bodies — use :class:`MapObject` for polygon solids.
+            x: World X position of the shape origin (top-left / center
+                per shape offset semantics).
+            y: World Y position.
+            vx: X velocity (for kinematic bodies).
+            vy: Y velocity (for kinematic bodies).
+            mode: ``"static"`` (never moves) or ``"kinematic"`` (moved
+                explicitly by the game).
+            collision_layer: Layer this body is on (default 1).
+            collision_mask: Layers this body collides with (default all).
+            game_id: Optional label for debugging.
+        """
+        if not isinstance(collision_shape, (RectangleShape, CircleShape, CapsuleShape)):
+            raise TypeError(
+                "Body requires a primitive shape (RectangleShape, CircleShape, "
+                f"or CapsuleShape), got {type(collision_shape).__name__}"
+            )
+        if mode not in BODY_MODES:
+            raise ValueError(
+                f"mode must be one of {BODY_MODES}, got {mode!r}"
+            )
+        self.collision_shape = collision_shape
+        self.x = x
+        self.y = y
+        self.vx = vx
+        self.vy = vy
+        self.mode = mode
+        self.collision_layer = collision_layer
+        self.collision_mask = collision_mask
+        self.game_id = game_id
+        self.on_ground = False
+
+    def __repr__(self) -> str:
+        return (
+            f"Body(shape={type(self.collision_shape).__name__}, x={self.x}, "
+            f"y={self.y}, mode={self.mode!r}, game_id={self.game_id!r})"
+        )
+
+    # ------------------------------------------------------------------
+    # Geometry helpers used by the movement resolver
+    # ------------------------------------------------------------------
+
+    def top_y_at(self, world_x: float) -> Optional[float]:
+        """Return the top-surface world Y of this body at *world_x*, or None.
+
+        Only the top surface is sampled — bodies are never one-way, but the
+        resolver only needs the topmost surface for ground landing.
+        """
+        shape = self.collision_shape
+        if isinstance(shape, RectangleShape):
+            left = self.x + shape.offset[0]
+            if left <= world_x <= left + shape.width:
+                return self.y + shape.offset[1]
+            return None
+
+        if isinstance(shape, CircleShape):
+            cx = self.x + shape.offset[0]
+            cy = self.y + shape.offset[1]
+            return _circle_top_y(cx, cy, shape.radius, world_x)
+
+        # CapsuleShape — vertical segment (top cap center, radius, height)
+        px = self.x + shape.offset[0]
+        py = self.y + shape.offset[1]
+        return _circle_top_y(px, py, shape.radius, world_x)
+
+    def as_polygon(self) -> CollisionPolygon:
+        """World-space polygon approximation of this body's shape.
+
+        Used only by slide-mode normal computation (the tile resolver works
+        on polygon edges).  Circles/capsules are approximated with enough
+        edges that the closest-edge normal is visually exact.
+        """
+        shape = self.collision_shape
+        if isinstance(shape, RectangleShape):
+            left = self.x + shape.offset[0]
+            top = self.y + shape.offset[1]
+            return CollisionPolygon(
+                vertices=[
+                    (left, top),
+                    (left + shape.width, top),
+                    (left + shape.width, top + shape.height),
+                    (left, top + shape.height),
+                ]
+            )
+
+        if isinstance(shape, CircleShape):
+            cx = self.x + shape.offset[0]
+            cy = self.y + shape.offset[1]
+            return CollisionPolygon(
+                vertices=_ngon(cx, cy, shape.radius, 16)
+            )
+
+        # Capsule — top cap semicircle, implicit side edges, bottom cap
+        px = self.x + shape.offset[0]
+        py = self.y + shape.offset[1]
+        bx = px
+        by = py + shape.height
+        r = shape.radius
+        steps = 4
+        verts: list[Tuple[float, float]] = []
+        # Top cap — left (pi) to right (0) through the top (3pi/2 = up)
+        for k in range(steps + 1):
+            a = math.pi + (math.pi * k / steps)
+            verts.append((px + r * math.cos(a), py + r * math.sin(a)))
+        # Bottom cap — right (0) to left (pi) through the bottom (pi/2 = down)
+        for k in range(steps + 1):
+            a = math.pi * k / steps
+            verts.append((bx + r * math.cos(a), by + r * math.sin(a)))
+        return CollisionPolygon(vertices=verts)
+
+
+def _circle_top_y(cx: float, cy: float, radius: float, world_x: float) -> Optional[float]:
+    """Top-surface Y of a circle at *world_x* (upper semicircle), or None."""
+    dx = world_x - cx
+    if abs(dx) > radius:
+        return None
+    return cy - math.sqrt(radius * radius - dx * dx)
+
+
+def _ngon(cx: float, cy: float, radius: float, edges: int) -> list[Tuple[float, float]]:
+    """Vertices of a regular polygon approximating a circle."""
+    return [
+        (
+            cx + radius * math.cos(2 * math.pi * i / edges),
+            cy + radius * math.sin(2 * math.pi * i / edges),
+        )
+        for i in range(edges)
+    ]

tilemap_parser-5.0.1/src/tilemap_parser/runtime/collision/__init__.py

@@ -0,0 +1,10 @@
+"""Object-to-object collision package.
+
+Shape-level narrowphase lives in :mod:`shapes`, hit results and pair
+queries in :mod:`hit`, and the spatial-grid manager in :mod:`manager`.
+"""
+
+from .hit import CollisionHit, check_collision, should_collide
+from .manager import ObjectCollisionManager
+
+__all__ = ["CollisionHit", "ObjectCollisionManager", "check_collision", "should_collide"]

tilemap_parser-5.0.1/src/tilemap_parser/runtime/collision/hit.py

@@ -0,0 +1,150 @@
+"""Collision hit results and pair queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..protocols import ICollidableObject
+from ...utils.geometry import CollisionInfo, aabb_overlap, get_shape_aabb
+from .shapes import _check_pair, _combined_aabb, _get_shapes
+
+
+@dataclass(slots=True)
+class CollisionHit:
+    """Result of a collision detection between two objects."""
+
+    object_a: ICollidableObject
+    object_b: ICollidableObject
+    normal: tuple[float, float]  # Direction to separate (from A to B)
+    depth: float  # Penetration depth
+
+    def resolve(self) -> None:
+        """Separate both objects by half the depth along the collision normal."""
+        sep_x = self.normal[0] * self.depth * 0.5
+        sep_y = self.normal[1] * self.depth * 0.5
+        self.object_a.x -= sep_x
+        self.object_a.y -= sep_y
+        self.object_b.x += sep_x
+        self.object_b.y += sep_y
+
+    def slide_velocity(self, vx: float, vy: float) -> tuple[float, float]:
+        """Project velocity along the collision surface (slide response).
+
+        Removes the component of (vx, vy) that is along *self.normal*,
+        leaving only the tangential component.  Intended for the moving
+        object passed as *object_a* — when that object moves into
+        *object_b* the approach component is stripped so the object slides
+        along the surface instead of penetrating.
+
+        If the velocity is already parallel to the surface or points away
+        from *object_b* the original velocity is returned unchanged.
+
+        Args:
+            vx: X component of velocity (object_a's velocity)
+            vy: Y component of velocity
+
+        Returns:
+            (slide_x, slide_y) — velocity projected onto the surface
+        """
+        dot = vx * self.normal[0] + vy * self.normal[1]
+        if dot > 0:
+            return (vx - self.normal[0] * dot, vy - self.normal[1] * dot)
+        return (vx, vy)
+
+    def involves(self, obj: ICollidableObject) -> bool:
+        """Check if this hit involves the given object."""
+        return self.object_a is obj or self.object_b is obj
+
+    def other(self, obj: ICollidableObject) -> ICollidableObject:
+        """Get the other object in this hit pair. Raises ValueError if obj is not part of the hit."""
+        if self.object_a is obj:
+            return self.object_b
+        if self.object_b is obj:
+            return self.object_a
+        raise ValueError("Object is not part of this collision hit")
+
+def should_collide(
+    obj_a: ICollidableObject,
+    obj_b: ICollidableObject,
+) -> bool:
+    """
+    Check if two objects should collide based on layers.
+
+    Uses mutual agreement: BOTH objects must want to collide.
+    This prevents asymmetric filtering issues.
+    """
+    a_layer = getattr(obj_a, "collision_layer", 1)
+    a_mask = getattr(obj_a, "collision_mask", 0xFFFFFFFF)
+    b_layer = getattr(obj_b, "collision_layer", 1)
+    b_mask = getattr(obj_b, "collision_mask", 0xFFFFFFFF)
+
+    # CRITICAL: AND for mutual agreement (not OR)
+    return (a_mask & b_layer) != 0 and (b_mask & a_layer) != 0
+
+
+# Backward compat alias
+_should_collide = should_collide
+
+def check_collision(
+    obj_a: ICollidableObject,
+    obj_b: ICollidableObject,
+) -> Optional[CollisionHit]:
+    """
+    Check if two objects collide.
+
+    Pipeline:
+        1. Layer filtering
+        2. Broadphase AABB rejection
+        3. Narrowphase geometry dispatch
+        4. Return CollisionHit or None
+
+    Supports multi-shape objects (those with a ``collision_shapes``
+    attribute).  When both objects have a single shape the behaviour
+    is identical to previous versions.
+    """
+    # 1. Layer filter
+    if not should_collide(obj_a, obj_b):
+        return None
+
+    # 2. Broadphase — use combined AABB when an object has multiple shapes
+    shapes_a = _get_shapes(obj_a)
+    shapes_b = _get_shapes(obj_b)
+
+    if len(shapes_a) == 1:
+        aabb_a = get_shape_aabb(obj_a.x, obj_a.y, shapes_a[0])
+    else:
+        aabb_a = _combined_aabb(obj_a.x, obj_a.y, shapes_a)
+
+    if len(shapes_b) == 1:
+        aabb_b = get_shape_aabb(obj_b.x, obj_b.y, shapes_b[0])
+    else:
+        aabb_b = _combined_aabb(obj_b.x, obj_b.y, shapes_b)
+
+    if not aabb_overlap(aabb_a, aabb_b):
+        return None
+
+    # 3. Narrowphase — iterate all shape pairs, keep the deepest
+    deepest: Optional[CollisionInfo] = None
+
+    for shape_a in shapes_a:
+        for shape_b in shapes_b:
+            pair_aabb_a = get_shape_aabb(obj_a.x, obj_a.y, shape_a)
+            pair_aabb_b = get_shape_aabb(obj_b.x, obj_b.y, shape_b)
+            if not aabb_overlap(pair_aabb_a, pair_aabb_b):
+                continue
+
+            info = _check_pair(obj_a, obj_b, shape_a, shape_b, pair_aabb_a, pair_aabb_b)
+            if info is not None and (deepest is None or info.depth > deepest.depth):
+                deepest = info
+
+    if deepest is None:
+        return None
+
+    return CollisionHit(
+        object_a=obj_a,
+        object_b=obj_b,
+        normal=deepest.normal,
+        depth=deepest.depth,
+    )
+

tilemap_parser-5.0.1/src/tilemap_parser/runtime/collision/manager.py

@@ -0,0 +1,184 @@
+"""Spatial-grid object collision manager."""
+
+from __future__ import annotations
+
+import warnings
+from math import floor, isfinite
+from typing import Dict, Iterable, Iterator, List, Optional, Set, Tuple
+
+from ..protocols import ICollidableObject
+from ...utils.geometry import get_shape_aabb
+from .hit import CollisionHit, check_collision
+from .shapes import _combined_aabb, _get_shapes
+
+
+class ObjectCollisionManager:
+    """
+    Manages collision detection for multiple objects.
+
+    Features:
+        - Add / remove objects
+        - All-vs-all and one-vs-all queries
+        - Layer filtering
+
+    Uses a uniform-grid spatial broadphase for all-vs-all queries
+    (rebuilt per query) and a linear scan for single-object queries.
+    """
+
+    def __init__(
+        self,
+        objects: Optional[Iterable[ICollidableObject]] = None,
+        *,
+        cell_size: float = 128.0,
+    ) -> None:
+        if not isfinite(cell_size) or cell_size <= 0:
+            raise ValueError("cell_size must be a finite positive number")
+
+        self.objects: List[ICollidableObject] = []
+        self.cell_size = float(cell_size)
+        if objects is not None:
+            for obj in objects:
+                self.add_object(obj)
+
+    def __len__(self) -> int:
+        """Return the number of objects currently managed."""
+        return len(self.objects)
+
+    def __iter__(self) -> Iterator[ICollidableObject]:
+        """Iterate over managed objects in insertion order."""
+        return iter(self.objects)
+
+    def __contains__(self, obj: object) -> bool:
+        """Return True if the exact object instance is managed."""
+        return any(existing is obj for existing in self.objects)
+
+    def _find_object_index(self, obj: ICollidableObject) -> int:
+        for index, existing in enumerate(self.objects):
+            if existing is obj:
+                return index
+        return -1
+
+    def add_object(self, obj: ICollidableObject) -> None:
+        """Add an object to the collision system."""
+        if self._find_object_index(obj) != -1:
+            warnings.warn(
+                f"Object {obj} is already in the collision manager, skipping.",
+                UserWarning,
+                stacklevel=2,
+            )
+            return
+        self.objects.append(obj)
+
+    def remove_object(self, obj: ICollidableObject) -> None:
+        """Remove an object from the collision system."""
+        index = self._find_object_index(obj)
+        if index == -1:
+            warnings.warn(
+                f"Object {obj} is not in the collision manager, skipping.",
+                UserWarning,
+                stacklevel=2,
+            )
+            return
+        del self.objects[index]
+
+    def clear(self) -> None:
+        """Remove all objects from the collision system."""
+        self.objects.clear()
+
+    def _cells_for_aabb(
+        self,
+        aabb: tuple[float, float, float, float],
+    ) -> Iterator[Tuple[int, int]]:
+        left, top, right, bottom = aabb
+        min_cell_x = floor(left / self.cell_size)
+        max_cell_x = floor(right / self.cell_size)
+        min_cell_y = floor(top / self.cell_size)
+        max_cell_y = floor(bottom / self.cell_size)
+
+        for cell_y in range(min_cell_y, max_cell_y + 1):
+            for cell_x in range(min_cell_x, max_cell_x + 1):
+                yield (cell_x, cell_y)
+
+    def _object_aabb(
+        self,
+        obj: ICollidableObject,
+    ) -> tuple[float, float, float, float]:
+        shapes = _get_shapes(obj)
+        if len(shapes) == 1:
+            return get_shape_aabb(obj.x, obj.y, shapes[0])
+        return _combined_aabb(obj.x, obj.y, shapes)
+
+    def _build_spatial_index(
+        self,
+    ) -> tuple[Tuple[ICollidableObject, ...], Dict[Tuple[int, int], List[int]]]:
+        objects = tuple(self.objects)
+        grid: Dict[Tuple[int, int], List[int]] = {}
+
+        for index, obj in enumerate(objects):
+            for cell in self._cells_for_aabb(self._object_aabb(obj)):
+                grid.setdefault(cell, []).append(index)
+
+        return objects, grid
+
+    def _candidate_indices(
+        self,
+        obj: ICollidableObject,
+        grid: Dict[Tuple[int, int], List[int]],
+    ) -> Set[int]:
+        candidates: Set[int] = set()
+        for cell in self._cells_for_aabb(self._object_aabb(obj)):
+            candidates.update(grid.get(cell, ()))
+        return candidates
+
+    def check_all_collisions(self) -> List[CollisionHit]:
+        """
+        Check every potentially colliding pair.
+
+        Returns a list of CollisionHit for all colliding pairs.
+        Each pair appears at most once (i, j) with j > i.
+        """
+        objects, grid = self._build_spatial_index()
+        hits: List[CollisionHit] = []
+
+        for i, obj in enumerate(objects):
+            candidate_indices = self._candidate_indices(obj, grid)
+            for j in sorted(candidate_indices):
+                if j <= i:
+                    continue
+                hit = check_collision(objects[i], objects[j])
+                if hit is not None:
+                    hits.append(hit)
+        return hits
+
+    def check_object(self, obj: ICollidableObject) -> List[CollisionHit]:
+        """
+        Check one object against all others using a linear scan.
+
+        The queried object does not need to be managed. If it is managed,
+        comparison with itself is skipped by identity.
+        """
+        hits: List[CollisionHit] = []
+        for other in self.objects:
+            if other is obj:
+                continue
+            hit = check_collision(obj, other)
+            if hit is not None:
+                hits.append(hit)
+        return hits
+
+    def check_object_first(self, obj: ICollidableObject) -> Optional[CollisionHit]:
+        """
+        Check one object against all others and return the first collision hit.
+
+        Iterates managed objects in insertion order. The queried object
+        does not need to be managed; if it is managed, comparison with
+        itself is skipped by identity.
+        """
+        for other in self.objects:
+            if other is obj:
+                continue
+            hit = check_collision(obj, other)
+            if hit is not None:
+                return hit
+        return None
+