pyforge3d 2.1.0__tar.gz → 2.2.0__tar.gz

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyforge3d
-Version: 2.1.0
+Version: 2.2.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Rust
 Classifier: Intended Audience :: Developers
@@ -46,7 +46,7 @@ Provides-Extra: docs
 Provides-Extra: render
 Provides-Extra: rl
 License-File: LICENSE
-Summary: Pure-Python 3D physics game engine — fast like native, beautiful like simulation.
+Summary: Pure-Python 3D physics game engine — own dynamics, own rules, no compromises.
 Keywords: game-engine,physics,simulation,3d,rigid-body,collision,rendering,robotics,reinforcement-learning,numpy,jax
 Author-email: iruki <me@iruki.dev>
 Requires-Python: >=3.12
@@ -59,7 +59,7 @@ Project-URL: Repository, https://github.com/iruki-dev/forge3d
 
 # forge3d
 
-> **Pure-Python 3D game engine — easy like pygame, beautiful like simulation.**
+> **Pure-Python 3D physics game engine — own dynamics, own rules, no compromises.**
 
 [![PyPI version](https://img.shields.io/pypi/v/pyforge3d.svg)](https://pypi.org/project/pyforge3d/)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/README.md

@@ -1,6 +1,6 @@
 # forge3d
 
-> **Pure-Python 3D game engine — easy like pygame, beautiful like simulation.**
+> **Pure-Python 3D physics game engine — own dynamics, own rules, no compromises.**
 
 [![PyPI version](https://img.shields.io/pypi/v/pyforge3d.svg)](https://pypi.org/project/pyforge3d/)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/pyproject.toml

@@ -6,8 +6,8 @@ build-backend = "maturin"
 
 [project]
 name = "pyforge3d"
-version = "2.1.0"
-description = "Pure-Python 3D physics game engine — fast like native, beautiful like simulation."
+version = "2.2.0"
+description = "Pure-Python 3D physics game engine — own dynamics, own rules, no compromises."
 readme = "README.md"
 license = { file = "LICENSE" }
 requires-python = ">=3.12"
@@ -103,13 +103,15 @@ addopts   = "-q --tb=short"
 line-length    = 100
 target-version = "py312"
 src            = ["src"]
+exclude        = ["archive", "demos"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
 ignore = ["B008", "SIM118"]
 
 [tool.ruff.lint.per-file-ignores]
-"tests/**" = ["E501"]
+"tests/**"          = ["E501"]
+"apps/**"           = ["E501", "E701", "E702", "B905"]
 
 # ── Type-check ────────────────────────────────────────────────────────────────
 

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/__init__.py

@@ -1,6 +1,6 @@
 """forge3d — pure-Python 3D game engine.
 
-"Fast like native, beautiful like simulation."
+"Pure-Python 3D physics game engine — own dynamics, own rules, no compromises."
 Coordinate system: z-up, SI units (metres, kg, seconds).
 
 Minimal example (14 lines)::
@@ -103,7 +103,7 @@ from forge3d.editor import EditorApp, PlayState
 from forge3d.errors import Forge3dError, PhysicsError, RenderError, ValidationError
 from forge3d.events import CollisionEvent, CollisionHandler
 from forge3d.facade import Body, Material, Shape, World
-from forge3d.input import Input, InputBuilder, Key
+from forge3d.input import Input, InputBuilder, Key, ScriptedInput
 from forge3d.io.world_snapshot import StateRecorder
 
 # Particle system (P31)
@@ -121,7 +121,7 @@ from forge3d.scene import Prefab, SceneManager, SceneNode
 from forge3d.ui import Canvas, DebugPanel, HierarchyPanel, InspectorPanel, UISystem
 from forge3d.viewer import Viewer
 
-__version__ = "2.1.0"
+__version__ = "2.1.1"
 
 # ── API 안정성 선언 ───────────────────────────────────────────────────────────
 # Stable (v3까지 Breaking change 없음):
@@ -158,6 +158,7 @@ __all__ = [
     "Input",
     "InputBuilder",
     "Key",
+    "ScriptedInput",
     # Camera
     "OrbitCamera",
     "FollowCamera",

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/animation/ik_fabrik.py

@@ -1,6 +1,7 @@
 """FABRIK IK 솔버 — Forward And Backward Reaching Inverse Kinematics.
 
-참고: Aristidou & Lasenby (2011), "FABRIK: A fast, iterative solver for the Inverse Kinematics problem"
+참고: Aristidou & Lasenby (2011),
+"FABRIK: A fast, iterative solver for the Inverse Kinematics problem"
 """
 
 from __future__ import annotations

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/animation/system.py

@@ -33,11 +33,9 @@ class AnimationSystem(System):
 
             # AnimationPlayer가 있으면 체인 위치 읽기
             try:
-                player = ew.get_component(e, AnimationPlayer)  # type: ignore[assignment]
+                anim_player: AnimationPlayer = ew.get_component(e, AnimationPlayer)
             except KeyError:
                 continue
-
-            anim_player: AnimationPlayer = player
             joint_positions = anim_player.skeleton.joint_positions()
             if len(joint_positions) < 2:
                 continue

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/app.py

@@ -1,6 +1,6 @@
 """forge3d App — high-level game-loop abstraction.
 
-Provides a decorator-driven API similar to popular game frameworks::
+Provides a decorator-driven API::
 
     import forge3d as f3d
 
@@ -39,10 +39,10 @@ class App:
 
     Parameters
     ----------
-    title     : Window title (shown in windowed mode).
+    title     : Window title.
     width     : Render width in pixels.
     height    : Render height in pixels.
-    fps       : Target frames per second; also the physics step rate.
+    fps       : Physics step rate and target render rate.
     gravity   : World gravity vector (x, y, z) in m/s².
 
     Examples
@@ -66,6 +66,11 @@ class App:
         height: int = 720,
         fps: float = 60.0,
         gravity: Any = (0.0, 0.0, -9.81),
+        substeps: int = 2,
+        shadow_resolution: int = 0,
+        sky_color: tuple | None = None,
+        show_grid: bool = False,
+        max_dt: float = 1 / 25,
     ) -> None:
         from forge3d.facade import World
 
@@ -75,6 +80,11 @@ class App:
         self._height = height
         self._fps = float(fps)
         self._dt = 1.0 / self._fps
+        self._substeps = substeps
+        self._shadow_resolution = shadow_resolution
+        self._sky_color = sky_color
+        self._show_grid = show_grid
+        self._max_dt = max_dt
 
         self._on_start: Callable | None = None
         self._on_update: Callable | None = None
@@ -132,52 +142,56 @@ class App:
     # ── Run ───────────────────────────────────────────────────────────────────
 
     def run(self, max_frames: int | None = None) -> None:
-        """Start the game loop.
+        """Open a window and start the game loop.
 
-        Initialises the viewer, fires :meth:`on_start`, then loops:
-        1. Build :class:`~forge3d.input.Input` snapshot
-        2. Call :meth:`on_update` with ``(world, dt, inp)``
+        Fires ``on_start`` once, then each frame:
+
+        1. Read input from the OS window (keyboard / mouse).
+        2. Call ``on_update(world, dt, inp)``.
         3. ``world.step(dt)``
         4. ``viewer.draw()``
-        5. Fire :meth:`on_render` if registered
-        6. Advance frame; stop when ``max_frames`` reached or window closed
+        5. Call ``on_render(world, viewer)``.
+
+        The loop ends when the window is closed, ESC is pressed, or
+        ``max_frames`` frames have been rendered.
 
         Parameters
         ----------
-        max_frames : Maximum frames to render before stopping automatically.
-                     ``None`` (default) runs until the window is closed or
-                     the default headless limit is reached.
+        max_frames : Stop after this many frames.  ``None`` (default) runs
+                     until the user closes the window.
         """
-        from forge3d.input import _InputBuilder
         from forge3d.viewer import Viewer
 
-        # Fire on_start
         if self._on_start is not None:
             _call_flexible(self._on_start, self._world)
 
+        kw: dict[str, Any] = {}
+        if self._sky_color is not None:
+            kw["sky_color"] = self._sky_color
         viewer = Viewer(
             self._world,
+            title=self._title,
             width=self._width,
             height=self._height,
+            fps=int(self._fps),
             max_frames=max_frames,
+            shadow_resolution=self._shadow_resolution,
+            show_grid=self._show_grid,
+            **kw,
         )
-        inp_builder = _InputBuilder()
 
         while viewer.is_open:
-            inp = inp_builder.build()
+            inp = viewer.input
 
             if self._on_update is not None:
                 _call_flexible(self._on_update, self._world, self._dt, inp)
 
-            self._world.step(self._dt)
-
+            self._world.step(self._dt, substeps=self._substeps)
             viewer.draw()
 
             if self._on_render is not None:
                 _call_flexible(self._on_render, self._world, viewer)
 
-            inp_builder.end_frame()
-
         viewer.close()
 
     def __repr__(self) -> str:
@@ -194,6 +208,10 @@ def _call_flexible(func: Callable, *positional: Any) -> Any:
     ``fn(world, dt, inp)`` interchangeably — missing args are omitted.
     Works with regular functions, lambdas, and bound methods.
     """
+    # Determine arg count from signature — only this part can fail for builtins.
+    # The function call itself is NOT wrapped in try/except so that errors raised
+    # inside the user's callback (e.g. wrong kwargs, missing imports) propagate
+    # immediately instead of being mistaken for an arg-count mismatch.
     try:
         sig = inspect.signature(func)
         n = len(
@@ -207,12 +225,12 @@ def _call_flexible(func: Callable, *positional: Any) -> Any:
                 )
             ]
         )
-        # If a parameter has VAR_POSITIONAL (*args), pass everything
         has_var_positional = any(
             p.kind == inspect.Parameter.VAR_POSITIONAL for p in sig.parameters.values()
         )
-        if has_var_positional:
-            return func(*positional)
-        return func(*positional[:n])
+        call_args = positional if has_var_positional else positional[:n]
     except (ValueError, TypeError):
-        return func(*positional)
+        # inspect.signature failed (e.g. C extension) — pass all args
+        call_args = positional
+
+    return func(*call_args)

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/audio/clip.py

@@ -69,7 +69,7 @@ def _load_wav_stdlib(path: Path) -> tuple[np.ndarray, int]:
         sr = wf.getframerate()
         raw = wf.readframes(n_frames)
 
-    dtype_map = {1: np.int8, 2: np.int16, 4: np.int32}
+    dtype_map: dict[int, type[np.signedinteger]] = {1: np.int8, 2: np.int16, 4: np.int32}
     dtype = dtype_map.get(sampwidth, np.int16)
     data = np.frombuffer(raw, dtype=dtype).astype(np.float32)
     # 정규화

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/camera.py

@@ -167,6 +167,187 @@ class OrbitCamera:
             fov_deg=self.fov_deg,
         )
 
+    @property
+    def forward_azimuth(self) -> float:
+        """Azimuth the camera is *looking toward* (azimuth + 180°, mod 360).
+
+        Useful as a "player forward" heading for camera-relative movement::
+
+            yaw_deg = cam.forward_azimuth
+            fwd = (cos(radians(yaw_deg)), sin(radians(yaw_deg)), 0)
+        """
+        return (self.azimuth + 180.0) % 360.0
+
+    def handle_input(
+        self,
+        inp: Any,
+        dt: float,
+        *,
+        rotate_button: int = 1,
+        mouse_sensitivity: float = 0.25,
+        rotate_key_left: str = "q",
+        rotate_key_right: str = "e",
+        pitch_key_up: str = "r",
+        pitch_key_down: str = "f",
+        key_deg_per_s: float = 130.0,
+        scroll_zoom: bool = True,
+        min_distance: float = 1.0,
+        max_distance: float = 50.0,
+        min_elevation: float = -89.0,
+        max_elevation: float = 89.0,
+    ) -> OrbitCamera:
+        """Process one frame of keyboard / mouse input and update the camera.
+
+        Designed to replace per-game boilerplate camera-rig update logic.
+        Call once per frame before :meth:`to_snapshot`::
+
+            cam.handle_input(inp, dt).follow(player_pos, dt=dt).occlude(world)
+            viewer.set_camera(cam.to_snapshot())
+
+        Parameters
+        ----------
+        inp             : :class:`~forge3d.input.Input` or :class:`~forge3d.input.ScriptedInput`.
+        dt              : Frame delta-time in seconds.
+        rotate_button   : Mouse button held to orbit (default 1 = right).
+        mouse_sensitivity: Degrees per pixel for mouse drag.
+        rotate_key_left : Key to rotate left (default ``'q'``).
+        rotate_key_right: Key to rotate right (default ``'e'``).
+        pitch_key_up    : Key to pitch up (default ``'r'``).
+        pitch_key_down  : Key to pitch down (default ``'f'``).
+        key_deg_per_s   : Rotation speed in degrees/s for key-driven orbit.
+        scroll_zoom     : If True (default), scroll wheel zooms.
+        min_distance    : Minimum zoom distance in metres.
+        max_distance    : Maximum zoom distance in metres.
+        min_elevation   : Elevation clamp lower bound (degrees).
+        max_elevation   : Elevation clamp upper bound (degrees).
+
+        Returns ``self`` for method chaining.
+        """
+        # Mouse drag rotate
+        if inp.mouse_button(rotate_button):
+            dx, dy = inp.mouse_delta()
+            self.rotate(d_azimuth=-dx * mouse_sensitivity, d_elevation=dy * mouse_sensitivity)
+
+        # Key-driven rotate
+        k = key_deg_per_s * dt
+        if inp.key_held(rotate_key_left):
+            self.rotate(d_azimuth=k)
+        if inp.key_held(rotate_key_right):
+            self.rotate(d_azimuth=-k)
+        if inp.key_held(pitch_key_up):
+            self.rotate(d_elevation=k * 0.6)
+        if inp.key_held(pitch_key_down):
+            self.rotate(d_elevation=-k * 0.6)
+
+        # Clamp elevation
+        self.elevation = float(np.clip(self.elevation, min_elevation, max_elevation))
+
+        # Scroll zoom
+        if scroll_zoom:
+            sd = inp.scroll_delta()
+            if sd:
+                self.distance = float(
+                    np.clip(
+                        self.distance * (1.0 - sd * 0.1),
+                        min_distance,
+                        max_distance,
+                    )
+                )
+
+        return self
+
+    def follow(
+        self,
+        target: Any,
+        head_height: float = 1.2,
+        smooth_hz: float = 10.0,
+        dt: float = 0.0,
+    ) -> OrbitCamera:
+        """Smoothly move the camera target toward *target* + *head_height*.
+
+        Replaces the common per-frame ``smooth_target`` lerp pattern that
+        third-person games need.  Call once per frame before :meth:`to_snapshot`.
+
+        Parameters
+        ----------
+        target      : World position to track — usually ``player.position``.
+        head_height : Vertical offset added to *target* (default 1.2 m).
+        smooth_hz   : Smoothing frequency in Hz — higher = snappier.
+        dt          : Frame delta-time; pass 0 for instant snap.
+
+        Returns ``self`` for method chaining::
+
+            cam.follow(player.position, dt=dt).occlude(world)
+            viewer.set_camera(cam.to_snapshot())
+        """
+        import math
+
+        goal = np.asarray(target, dtype=float) + np.array([0.0, 0.0, head_height])
+        alpha = 1.0 - math.exp(-smooth_hz * dt) if dt > 0.0 and smooth_hz > 0.0 else 1.0
+        self.target = self.target + (goal - self.target) * alpha
+        return self
+
+    def occlude(
+        self,
+        world: Any,
+        terrain_sampler: Any = None,
+        min_distance: float = 1.6,
+        layer_mask: int = 0x0001,
+        terrain_steps: int = 16,
+        terrain_clearance: float = 0.35,
+    ) -> OrbitCamera:
+        """Pull the camera distance inward to avoid geometry occlusion.
+
+        Raycasts against physics bodies and (optionally) marches the eye ray
+        against a terrain height sampler.  Sets ``self.distance`` to the safe
+        distance and returns ``self`` for chaining.
+
+        Parameters
+        ----------
+        world            : :class:`~forge3d.facade.World` to raycast against.
+        terrain_sampler  : Callable ``(x, y) → z`` for terrain height (e.g.
+                           ``heightfield.height_at`` or your own function).
+                           Pass ``None`` to skip terrain marching — when the
+                           world has heightfields and raycasts already hit them
+                           this is usually not needed.
+        min_distance     : Minimum eye-to-target distance (m).
+        layer_mask       : Collision layers included in the occlusion raycast.
+        terrain_steps    : Number of steps for the terrain march.
+        terrain_clearance: Camera is pulled in when closer than this to terrain.
+
+        Returns ``self``::
+
+            cam.follow(player.position, dt=dt).occlude(world)
+            viewer.set_camera(cam.to_snapshot())
+        """
+        eye_dir = self.position - self.target
+        eye_len = float(np.linalg.norm(eye_dir))
+        if eye_len < 1e-9:
+            return self
+
+        u = eye_dir / eye_len
+        dist = self.distance
+
+        # Raycast against bodies
+        hits = world.raycast_all(self.target, u, max_dist=dist, layer_mask=layer_mask)
+        for hit in hits:
+            if hit.body is not None:
+                dist = min(dist, max(min_distance, float(hit.distance) - 0.4))
+                break
+
+        # Optional terrain height-function march
+        if terrain_sampler is not None:
+            for k in range(1, terrain_steps + 1):
+                t = dist * k / terrain_steps
+                p = self.target + u * t
+                h_terrain = float(terrain_sampler(float(p[0]), float(p[1])))
+                if float(p[2]) < h_terrain + terrain_clearance:
+                    dist = max(min_distance, t - 0.5)
+                    break
+
+        self.distance = max(min_distance, dist)
+        return self
+
     def __repr__(self) -> str:
         return (
             f"OrbitCamera(target={self.target.round(2).tolist()}, "

{pyforge3d-2.1.0 → pyforge3d-2.2.0}/src/forge3d/character.py

@@ -50,6 +50,7 @@ class CharacterController:
         height: float,
         radius: float,
         ground_layer_mask: int = 0xFFFF,
+        ground_check_hz: float = 60.0,
     ) -> None:
         self._world = world
         self.body = body
@@ -57,7 +58,21 @@ class CharacterController:
         self._radius = float(radius)
         self._ground_layer_mask = ground_layer_mask
         self._grounded = False
-        self._vertical_vel = 0.0  # m/s, used for jump/glide tracking
+        self._vertical_vel = 0.0
+
+        # Throttle ground-detection raycast. At 10 Hz (bots) this cuts the
+        # per-move cost from ~1 ms to ~0.017 ms with no gameplay difference.
+        self._ground_check_interval = 1.0 / max(1.0, float(ground_check_hz))
+        self._ground_check_timer = 0.0
+
+        # Jump cooldown prevents infinite jumping when the capsule is still
+        # close to the ground in the frame right after a jump.
+        self._jump_cooldown: float = 0.0
+
+        # Platform riding: track which body we're standing on and its last position
+        # so we can apply its displacement to ourselves each frame.
+        self._ground_body_id: int | None = None  # None → terrain / nothing
+        self._ground_body_last_pos: Any | None = None  # np.ndarray
 
     # ── State queries ─────────────────────────────────────────────────────────
 
@@ -91,6 +106,9 @@ class CharacterController:
     ) -> None:
         """Apply horizontal movement toward *direction* at *speed* m/s.
 
+        Also carries the character on moving platforms automatically — no
+        manual delta-passing needed.
+
         Parameters
         ----------
         direction : (3,) movement vector (only x/y components used unless z != 0).
@@ -98,6 +116,8 @@ class CharacterController:
         speed     : Maximum movement speed in m/s.
         dt        : Frame delta-time in seconds.
         """
+        self._update_ground(dt)
+
         d = np.asarray(direction, dtype=float)
         norm = np.linalg.norm(d[:2])
         if norm > 1e-9:
@@ -108,7 +128,6 @@ class CharacterController:
             cur = self.body.velocity.copy()
             cur[:2] = target_vel[:2]
             self.body.set_velocity(cur)
-        self._update_ground(dt)
 
     def jump(self, impulse: float = 5.0) -> None:
         """Apply an upward velocity impulse if grounded.
@@ -117,11 +136,61 @@ class CharacterController:
         ----------
         impulse : Upward speed added in m/s (think: initial jump velocity).
         """
-        if self._grounded:
+        if self._grounded and self._jump_cooldown <= 0.0:
             vel = self.body.velocity.copy()
             vel[2] = float(impulse)
             self.body.set_velocity(vel)
             self._grounded = False
+            self._jump_cooldown = 0.40  # 400 ms before the next jump is allowed
+
+    def move_camera_relative(
+        self,
+        inp: Any,
+        cam: Any,
+        speed: float,
+        dt: float,
+        *,
+        forward_key: str = "w",
+        back_key: str = "s",
+        left_key: str = "a",
+        right_key: str = "d",
+    ) -> np.ndarray:
+        """Move relative to the camera's facing direction.
+
+        Eliminates the boilerplate yaw-angle → forward/right vector pattern that
+        every third-person game repeats.  Returns the world-space move vector
+        (useful for updating a ``facing`` direction)::
+
+            move = cc.move_camera_relative(inp, cam, speed=7.2, dt=dt)
+
+        Parameters
+        ----------
+        inp         : :class:`~forge3d.input.Input` or
+                      :class:`~forge3d.input.ScriptedInput`.
+        cam         : :class:`~forge3d.camera.OrbitCamera` — only its
+                      ``forward_azimuth`` property is used.
+        speed       : Horizontal movement speed in m/s.
+        dt          : Frame delta-time in seconds.
+        forward_key : Key for forward movement (default ``'w'``).
+        back_key    : Key for backward movement (default ``'s'``).
+        left_key    : Key for left movement (default ``'a'``).
+        right_key   : Key for right movement (default ``'d'``).
+
+        Returns
+        -------
+        np.ndarray
+            The (3,) world-space move vector (zero if no input).
+        """
+        import math
+
+        yaw = math.radians(float(cam.forward_azimuth))
+        fwd = np.array([math.cos(yaw), math.sin(yaw), 0.0])
+        right = np.array([math.sin(yaw), -math.cos(yaw), 0.0])
+        mx = inp.axis(left_key, right_key)
+        my = inp.axis(back_key, forward_key)
+        move = fwd * my + right * mx
+        self.move(direction=tuple(move), speed=speed, dt=dt)
+        return move
 
     def glide(self, target_fall_speed: float = -1.5, dt: float = 1 / 60) -> None:
         """Reduce falling speed to *target_fall_speed* for a glide effect.
@@ -141,16 +210,67 @@ class CharacterController:
     # ── Internal ──────────────────────────────────────────────────────────────
 
     def _update_ground(self, dt: float) -> None:
-        """Update is_grounded via downward raycast."""
+        """Update is_grounded via downward raycast (throttled + jump-cooldown aware).
+
+        Also applies platform displacement: if the body we were standing on
+        has moved since the last check, we teleport ourselves by the same delta.
+        """
+        # Decrement jump cooldown unconditionally every call
+        if self._jump_cooldown > 0.0:
+            self._jump_cooldown = max(0.0, self._jump_cooldown - dt)
+            self._grounded = False
+            self._ground_body_id = None
+            self._ground_body_last_pos = None
+            return
+
+        self._ground_check_timer += dt
+        if self._ground_check_timer < self._ground_check_interval:
+            # Apply stored platform delta even between checks
+            self._apply_platform_delta()
+            return
+        self._ground_check_timer = 0.0
+
+        # Apply platform delta from last frame before updating ground state
+        self._apply_platform_delta()
+
         pos = self.body.position
         ray_len = self._height / 2.0 + self._radius + self._GROUND_RAY_EXTRA
         hit = self._world.raycast(
             origin=pos,
             direction=(0.0, 0.0, -1.0),
             max_dist=ray_len,
+            layer_mask=self._ground_layer_mask,
         )
         self._grounded = hit is not None
 
+        # Track which body (or terrain) we're on for platform riding
+        if hit is not None and hit.body is not None:
+            self._ground_body_id = hit.body._id
+            self._ground_body_last_pos = hit.body.position.copy()
+        else:
+            # Terrain hit (body is None) or no hit
+            self._ground_body_id = None
+            self._ground_body_last_pos = None
+
+    def _apply_platform_delta(self) -> None:
+        """If standing on a moving body, carry ourselves with it."""
+        if self._ground_body_id is None or self._ground_body_last_pos is None:
+            return
+        body = self._world._bodies.get(self._ground_body_id)
+        if body is None:
+            self._ground_body_id = None
+            self._ground_body_last_pos = None
+            return
+        try:
+            current_pos = body.position
+            delta = current_pos - self._ground_body_last_pos
+            if np.linalg.norm(delta) > 1e-6:
+                self.body.set_position(self.body.position + delta)
+            self._ground_body_last_pos = current_pos.copy()
+        except Exception:
+            self._ground_body_id = None
+            self._ground_body_last_pos = None
+
     def __repr__(self) -> str:
         pos = self.position
         g = "grounded" if self._grounded else "airborne"