pyforge3d 1.0.0__py3-none-any.whl

forge3d/__init__.py

@@ -0,0 +1,105 @@
+"""forge3d — pure-Python 3D game engine.
+
+"Easy like pygame, beautiful like simulation."
+Coordinate system: z-up, SI units (metres, kg, seconds).
+
+Minimal example (14 lines)::
+
+    import forge3d as f3d
+
+    world = f3d.World(gravity=(0, 0, -9.81))
+    world.add_ground()
+    box = world.add_box(size=(1, 1, 1), position=(0, 0, 5), mass=1.0)
+    viewer = f3d.Viewer(world, max_frames=90)
+    while viewer.is_open:
+        world.step(dt=1 / 60)
+        viewer.draw()
+    print(f"Box final z = {box.position[2]:.2f} m")
+
+App-style game loop::
+
+    app = f3d.App("My World")
+
+    @app.on_start
+    def setup(world):
+        world.add_ground()
+        global ball
+        ball = world.add_sphere(position=(0, 0, 5))
+
+    @app.on_update
+    def update(world, dt, inp):
+        if inp.key_pressed(f3d.Key.SPACE):
+            world.apply_impulse(ball, (0, 0, 8))
+
+    app.run()
+
+Load a 3D model::
+
+    from forge3d.io import load_obj
+    mesh = load_obj("assets/models/cube.obj")
+    body = world.add_mesh(mesh, position=(0, 0, 3), mass=1.0)
+
+Public API:
+    App       — game-loop abstraction (on_start, on_update, on_render)
+    World     — physics world with scene construction helpers
+    Body      — handle to a simulated rigid body
+    Shape     — shape descriptor (box, sphere, capsule, mesh)
+    Material  — surface appearance (PBR: color, roughness, metallic, texture)
+    Viewer    — realtime render loop + Input access
+    Recorder  — capture simulation to video / image sequence
+    Input     — per-frame keyboard/mouse state snapshot
+    Key       — keyboard key name constants
+    OrbitCamera   — orbit-around-target camera controller
+    FollowCamera  — smooth body-tracking camera controller
+"""
+
+from __future__ import annotations
+
+from forge3d.app import App
+from forge3d.errors import Forge3dError, PhysicsError, RenderError, ValidationError
+from forge3d.backend import backend_name as _backend_name  # noqa: F401
+from forge3d.camera import FollowCamera, OrbitCamera
+from forge3d.constraints import JointHandle
+from forge3d.collision.layers import CollisionLayer
+from forge3d.events import CollisionEvent, CollisionHandler
+from forge3d.facade import Body, Material, Shape, World
+from forge3d.input import Input, Key
+from forge3d.io.world_snapshot import StateRecorder
+from forge3d.recorder import Recorder
+from forge3d.viewer import Viewer
+
+__version__ = "1.0.0"
+__all__ = [
+    # Core
+    "World",
+    "Body",
+    "Shape",
+    "Material",
+    # Joints
+    "JointHandle",
+    # Events
+    "CollisionEvent",
+    "CollisionHandler",
+    # Collision layers
+    "CollisionLayer",
+    # Serialization
+    "StateRecorder",
+    # Game loop
+    "App",
+    # Input
+    "Input",
+    "Key",
+    # Camera
+    "OrbitCamera",
+    "FollowCamera",
+    # Output
+    "Viewer",
+    "Recorder",
+    # Errors
+    "Forge3dError",
+    "ValidationError",
+    "PhysicsError",
+    "RenderError",
+    # Version
+    "__version__",
+]

forge3d/app.py

@@ -0,0 +1,219 @@
+"""forge3d App — high-level game-loop abstraction.
+
+Provides a decorator-driven API similar to popular game frameworks::
+
+    import forge3d as f3d
+
+    app = f3d.App("Physics Sandbox")
+    ball = None
+
+    @app.on_start
+    def setup(world: f3d.World) -> None:
+        global ball
+        world.add_ground()
+        ball = world.add_sphere(radius=0.4, position=(0, 0, 6))
+
+    @app.on_update
+    def update(world: f3d.World, dt: float, inp: f3d.Input) -> None:
+        if inp.key_pressed(f3d.Key.SPACE):
+            world.apply_impulse(ball, (0, 0, 8))
+
+    app.run()
+
+Signature flexibility
+---------------------
+``on_start`` callback may accept 0 or 1 argument (the ``World``).
+``on_update`` callback may accept 0, 1 (world), 2 (world, dt), or
+3 (world, dt, inp) arguments — missing arguments are simply not passed.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+class App:
+    """High-level forge3d application with a managed physics + render loop.
+
+    Parameters
+    ----------
+    title     : Window title (shown in windowed mode).
+    width     : Render width in pixels.
+    height    : Render height in pixels.
+    fps       : Target frames per second; also the physics step rate.
+    gravity   : World gravity vector (x, y, z) in m/s².
+
+    Examples
+    --------
+    >>> app = f3d.App("My World", fps=60)
+    >>> @app.on_start
+    ... def setup(world):
+    ...     world.add_ground()
+    ...     world.add_box(position=(0, 0, 5))
+    >>> @app.on_update
+    ... def update(world, dt, inp):
+    ...     if inp.key_held(f3d.Key.W):
+    ...         world.apply_impulse(world.bodies[0], (0, 5*dt, 0))
+    >>> app.run(max_frames=120)  # doctest: +SKIP
+    """
+
+    def __init__(
+        self,
+        title: str = "forge3d",
+        width: int = 1280,
+        height: int = 720,
+        fps: float = 60.0,
+        gravity: Any = (0.0, 0.0, -9.81),
+    ) -> None:
+        from forge3d.facade import World
+
+        self._world: World = World(gravity=gravity)
+        self._title = title
+        self._width = width
+        self._height = height
+        self._fps = float(fps)
+        self._dt = 1.0 / self._fps
+
+        self._on_start: Callable | None = None
+        self._on_update: Callable | None = None
+        self._on_render: Callable | None = None
+
+    # ── Properties ────────────────────────────────────────────────────────────
+
+    @property
+    def world(self) -> Any:
+        """The managed :class:`~forge3d.facade.World` instance."""
+        return self._world
+
+    @property
+    def fps(self) -> float:
+        """Target frames per second."""
+        return self._fps
+
+    @fps.setter
+    def fps(self, value: float) -> None:
+        if value <= 0:
+            raise ValueError(f"fps must be positive, got {value}")
+        self._fps = float(value)
+        self._dt = 1.0 / self._fps
+
+    # ── Decorator callbacks ───────────────────────────────────────────────────
+
+    def on_start(self, func: Callable) -> Callable:
+        """Register a callback called once before the game loop begins.
+
+        Signature: ``fn()`` or ``fn(world)``
+        """
+        self._on_start = func
+        return func
+
+    def on_update(self, func: Callable) -> Callable:
+        """Register a callback called every frame, before :meth:`World.step`.
+
+        Signature: one of:
+        - ``fn()``
+        - ``fn(world)``
+        - ``fn(world, dt)``
+        - ``fn(world, dt, inp)``
+        """
+        self._on_update = func
+        return func
+
+    def on_render(self, func: Callable) -> Callable:
+        """Register a callback called after :meth:`Viewer.draw` each frame.
+
+        Signature: ``fn()`` or ``fn(world)`` or ``fn(world, viewer)``
+        """
+        self._on_render = func
+        return func
+
+    # ── Run ───────────────────────────────────────────────────────────────────
+
+    def run(self, max_frames: int | None = None) -> None:
+        """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)``
+        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
+
+        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.
+        """
+        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)
+
+        viewer = Viewer(
+            self._world,
+            width=self._width,
+            height=self._height,
+            max_frames=max_frames,
+        )
+        inp_builder = _InputBuilder()
+
+        while viewer.is_open:
+            inp = inp_builder.build()
+
+            if self._on_update is not None:
+                _call_flexible(self._on_update, self._world, self._dt, inp)
+
+            self._world.step(self._dt)
+
+            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:
+        return (
+            f"App(title={self._title!r}, "
+            f"{self._width}×{self._height}, "
+            f"fps={self._fps:.0f})"
+        )
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _call_flexible(func: Callable, *positional: Any) -> Any:
+    """Call *func* with as many leading positional args as its signature allows.
+
+    This lets users write ``fn(world)``, ``fn(world, dt)``, or
+    ``fn(world, dt, inp)`` interchangeably — missing args are omitted.
+    Works with regular functions, lambdas, and bound methods.
+    """
+    try:
+        sig = inspect.signature(func)
+        n = len([
+            p for p in sig.parameters.values()
+            if p.kind in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ])
+        # 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])
+    except (ValueError, TypeError):
+        return func(*positional)

forge3d/backend.py

@@ -0,0 +1,118 @@
+"""Backend abstraction: numpy ↔ jax.
+
+Select via environment variable before process start:
+    ENGINE_BACKEND=numpy  (default)
+    ENGINE_BACKEND=jax
+
+Engine code imports names from here:
+    from forge3d.backend import xp, jit, vmap, set_at, new_prng_key, split_key, rand_uniform
+
+xp   — numpy or jax.numpy module
+jit  — jax.jit or no-op decorator
+vmap — jax.vmap or loop-based fallback
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+from typing import Any
+
+import numpy as _np
+
+_BACKEND: str = os.environ.get("ENGINE_BACKEND", "numpy")
+
+# Declare so static analysis sees these names regardless of which branch runs.
+xp: Any
+jit: Any
+vmap: Any
+
+
+def backend_name() -> str:
+    """Return the active backend name ('numpy' or 'jax')."""
+    return _BACKEND
+
+
+# ── JAX backend ───────────────────────────────────────────────────────────────
+if _BACKEND == "jax":
+    import jax as _jax
+    import jax.numpy as _jnp
+
+    xp = _jnp
+    jit = _jax.jit
+    vmap = _jax.vmap
+
+    def set_at(arr: Any, idx: Any, val: Any) -> Any:
+        """Return arr with arr[idx] = val — JAX functional update."""
+        return arr.at[idx].set(val)
+
+    def new_prng_key(seed: int = 0) -> Any:
+        return _jax.random.PRNGKey(seed)
+
+    def split_key(key: Any, num: int = 2) -> Any:
+        return _jax.random.split(key, num)
+
+    def rand_uniform(
+        key: Any,
+        shape: tuple[int, ...],
+        low: float = 0.0,
+        high: float = 1.0,
+    ) -> Any:
+        return _jax.random.uniform(key, shape=shape, minval=low, maxval=high)
+
+# ── NumPy backend ─────────────────────────────────────────────────────────────
+elif _BACKEND == "numpy":
+    xp = _np
+
+    def jit(fn: Any, **_: Any) -> Any:  # type: ignore[misc]
+        """No-op decorator: functions run eagerly under NumPy."""
+        return fn
+
+    def vmap(  # type: ignore[misc]
+        fn: Any,
+        in_axes: int = 0,
+        out_axes: int = 0,
+    ) -> Any:
+        """Loop-based vmap fallback: maps fn over axis-0 of all inputs."""
+
+        @functools.wraps(fn)
+        def _wrapped(*args: Any) -> Any:
+            n: int = args[0].shape[0]
+            results = [fn(*[a[i] for a in args]) for i in range(n)]
+            if not results:
+                return _np.array([])
+            if isinstance(results[0], tuple):
+                return tuple(_np.stack([r[j] for r in results]) for j in range(len(results[0])))
+            return _np.stack(results)
+
+        return _wrapped
+
+    def set_at(arr: Any, idx: Any, val: Any) -> Any:  # type: ignore[misc]
+        """Return a copy of arr with arr[idx] replaced by val."""
+        out = _np.array(arr, copy=True)
+        out[idx] = val
+        return out
+
+    def new_prng_key(seed: int = 0) -> Any:  # type: ignore[misc]
+        """Create a uint32[2] key compatible with JAX PRNG conventions."""
+        return _np.array([seed, 0], dtype=_np.uint32)
+
+    def split_key(key: Any, num: int = 2) -> Any:  # type: ignore[misc]
+        """Split key into num independent keys (deterministic, sequential seeds)."""
+        return _np.stack(
+            [_np.array([int(key[0]) + i, int(key[1])], dtype=_np.uint32) for i in range(num)]
+        )
+
+    def rand_uniform(  # type: ignore[misc]
+        key: Any,
+        shape: tuple[int, ...],
+        low: float = 0.0,
+        high: float = 1.0,
+    ) -> Any:
+        rng = _np.random.default_rng(int(key[0]))
+        return rng.uniform(low=low, high=high, size=shape)
+
+else:
+    raise ValueError(
+        f"Unknown ENGINE_BACKEND={_BACKEND!r}. Set the environment variable to 'numpy' or 'jax'."
+    )

forge3d/camera.py

@@ -0,0 +1,235 @@
+"""forge3d camera controllers.
+
+Controllers compute a :class:`~forge3d.render.snapshot.CameraSnapshot` from
+user-facing parameters (distance, angles, target) and can be driven by
+:class:`~forge3d.input.Input` events each frame.
+
+Usage::
+
+    cam = f3d.OrbitCamera(target=(0, 0, 1), distance=10, elevation=30)
+
+    while viewer.is_open:
+        inp = viewer.input
+        if inp.mouse_button(1):               # right-drag to orbit
+            dx, dy = inp.mouse_delta()
+            cam.rotate(d_azimuth=dx * 0.4, d_elevation=-dy * 0.4)
+        cam.zoom(inp.scroll_delta() * 0.5)
+        viewer.set_camera(cam.to_snapshot())
+        world.step()
+        viewer.draw()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from forge3d.facade import Body
+    from forge3d.render.snapshot import CameraSnapshot
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _normalize(v: np.ndarray) -> np.ndarray:
+    n = np.linalg.norm(v)
+    return v / (n + 1e-12)
+
+
+# ── OrbitCamera ───────────────────────────────────────────────────────────────
+
+
+class OrbitCamera:
+    """Spherical-coordinate camera that orbits a target point.
+
+    The camera is always looking at *target* from a point on a sphere of
+    radius *distance*.  *azimuth* (yaw) rotates around the z-axis;
+    *elevation* (pitch) tilts above/below the horizon.
+
+    Parameters
+    ----------
+    target    : Point the camera looks at, world-frame (x, y, z).
+    distance  : Eye-to-target distance in metres.
+    azimuth   : Horizontal angle in degrees (0 = +x axis).
+    elevation : Vertical angle in degrees above the horizon (clamped ±89°).
+    fov_deg   : Vertical field-of-view in degrees.
+
+    Usage::
+
+        cam = f3d.OrbitCamera(target=(0, 0, 1), distance=8)
+        cam.rotate(d_azimuth=45)         # spin 45° around target
+        cam.zoom(2)                      # move 20% closer (delta > 0 = closer)
+        snap = cam.to_snapshot()
+        viewer.set_camera(snap)
+    """
+
+    def __init__(
+        self,
+        target: Any = (0.0, 0.0, 0.0),
+        distance: float = 10.0,
+        azimuth: float = 45.0,
+        elevation: float = 30.0,
+        fov_deg: float = 45.0,
+    ) -> None:
+        self.target = np.asarray(target, dtype=float)
+        self.distance = max(0.05, float(distance))
+        self.azimuth = float(azimuth)
+        self.elevation = float(np.clip(elevation, -89.0, 89.0))
+        self.fov_deg = float(fov_deg)
+
+    # ── Derived geometry ──────────────────────────────────────────────────────
+
+    @property
+    def position(self) -> np.ndarray:
+        """Current world-space eye position."""
+        az = np.radians(self.azimuth)
+        el = np.radians(self.elevation)
+        x = self.distance * np.cos(el) * np.cos(az)
+        y = self.distance * np.cos(el) * np.sin(az)
+        z = self.distance * np.sin(el)
+        return self.target + np.array([x, y, z])
+
+    @property
+    def _right(self) -> np.ndarray:
+        az = np.radians(self.azimuth)
+        return np.array([-np.sin(az), np.cos(az), 0.0])
+
+    @property
+    def _up_screen(self) -> np.ndarray:
+        fwd = _normalize(self.target - self.position)
+        return _normalize(np.cross(self._right, fwd))
+
+    # ── Manipulation ──────────────────────────────────────────────────────────
+
+    def rotate(self, d_azimuth: float = 0.0, d_elevation: float = 0.0) -> OrbitCamera:
+        """Orbit around the target.
+
+        Parameters
+        ----------
+        d_azimuth   : Azimuth delta in degrees.
+        d_elevation : Elevation delta in degrees (clamped to ±89°).
+        """
+        self.azimuth += d_azimuth
+        self.elevation = float(np.clip(self.elevation + d_elevation, -89.0, 89.0))
+        return self
+
+    def zoom(self, delta: float) -> OrbitCamera:
+        """Adjust distance.
+
+        *delta > 0* moves the camera closer; *delta < 0* moves it farther.
+        The factor is ``distance *= (1 - delta * 0.1)`` so a delta of 1.0
+        reduces distance by 10%.
+
+        Parameters
+        ----------
+        delta : Zoom speed; typically ``Input.scroll_delta()``.
+        """
+        self.distance = max(0.05, self.distance * (1.0 - delta * 0.1))
+        return self
+
+    def set_distance(self, d: float) -> OrbitCamera:
+        """Directly set the eye-to-target distance."""
+        self.distance = max(0.05, float(d))
+        return self
+
+    def pan(self, dx: float, dy: float) -> OrbitCamera:
+        """Translate the *target* point in screen space.
+
+        Useful for middle-mouse-button panning.
+
+        Parameters
+        ----------
+        dx, dy : Pixel offsets in screen space.
+        """
+        pan_speed = self.distance * 0.001
+        self.target += self._right * (-dx * pan_speed) + self._up_screen * (dy * pan_speed)
+        return self
+
+    def look_at(self, target: Any) -> OrbitCamera:
+        """Point the camera at a new target without changing distance."""
+        self.target = np.asarray(target, dtype=float)
+        return self
+
+    # ── Snapshot ──────────────────────────────────────────────────────────────
+
+    def to_snapshot(self) -> CameraSnapshot:
+        """Build a :class:`~forge3d.render.snapshot.CameraSnapshot` from the
+        current orbit state — suitable for :meth:`Viewer.set_camera`.
+        """
+        from forge3d.render.snapshot import CameraSnapshot
+
+        return CameraSnapshot(
+            position=self.position.copy(),
+            target=self.target.copy(),
+            up=np.array([0.0, 0.0, 1.0]),
+            fov_deg=self.fov_deg,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"OrbitCamera(target={self.target.round(2).tolist()}, "
+            f"az={self.azimuth:.1f}°, el={self.elevation:.1f}°, "
+            f"d={self.distance:.2f} m)"
+        )
+
+
+# ── FollowCamera ──────────────────────────────────────────────────────────────
+
+
+class FollowCamera:
+    """Camera that smoothly tracks a :class:`~forge3d.facade.Body`.
+
+    The camera sits at *body.position + offset* and looks at *body.position*.
+    A smoothing factor ``alpha`` low-pass filters position changes
+    (0 = frozen, 1 = instant snap).
+
+    Parameters
+    ----------
+    body    : The :class:`Body` to follow.
+    offset  : Camera offset from the body in world frame (x, y, z).
+    alpha   : Smoothing factor per frame [0, 1].  Default 0.1 (smooth).
+    fov_deg : Vertical field-of-view.
+
+    Usage::
+
+        cam = f3d.FollowCamera(ball, offset=(0, -8, 4), alpha=0.08)
+        # each frame:
+        viewer.set_camera(cam.to_snapshot())
+    """
+
+    def __init__(
+        self,
+        body: Body,
+        offset: Any = (0.0, -8.0, 4.0),
+        alpha: float = 0.1,
+        fov_deg: float = 45.0,
+    ) -> None:
+        self._body = body
+        self.offset = np.asarray(offset, dtype=float)
+        self.alpha = float(np.clip(alpha, 0.0, 1.0))
+        self.fov_deg = float(fov_deg)
+        # Smoothed eye position — initialised to exact value
+        self._eye: np.ndarray = body.position + self.offset
+
+    def to_snapshot(self) -> CameraSnapshot:
+        """Update smoothed position and return a CameraSnapshot."""
+        from forge3d.render.snapshot import CameraSnapshot
+
+        target = self._body.position.copy()
+        desired_eye = target + self.offset
+        self._eye = self._eye + self.alpha * (desired_eye - self._eye)
+
+        return CameraSnapshot(
+            position=self._eye.copy(),
+            target=target,
+            up=np.array([0.0, 0.0, 1.0]),
+            fov_deg=self.fov_deg,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"FollowCamera(body={self._body!r}, "
+            f"offset={self.offset.tolist()}, alpha={self.alpha:.2f})"
+        )

forge3d/collision/__init__.py

@@ -0,0 +1,20 @@
+"""forge3d.collision — narrow-phase collision detection.
+
+Exported helpers:
+    detect_contacts  — main entry point for world.step()
+    gjk              — GJK intersection/distance test
+    gjk_contact      — GJK + EPA: returns (depth, normal) for intersecting pairs
+    ContactPoint     — per-contact data (pos, normal, depth, body indices)
+"""
+
+from forge3d.collision.detection import ContactPoint, detect_contacts
+from forge3d.collision.gjk import gjk, gjk_contact, gjk_distance, gjk_intersect
+
+__all__ = [
+    "ContactPoint",
+    "detect_contacts",
+    "gjk",
+    "gjk_contact",
+    "gjk_distance",
+    "gjk_intersect",
+]