Animated Model

load a rigged glTF and play its skeletal animation.

▶ Run in browser

Tags: 3d animation gltf skeletal

Auto-downloads the Khronos Fox sample on first run. Fox is a small rigged, skinned model that ships three baked animation clips (Survey, Walk, Run); this viewer imports it with import_gltf, drives its skeleton with an AnimationPlayer, and orbits a Camera3D around it under a key/fill light rig plus a WorldEnvironment so the motion is well-lit on web and desktop.

Asset references use the canonical Resource(package, name) form, which resolves through importlib.resources. The Fox directory beside this file is a real Python package (it carries an empty __init__.py); we add that assets directory to sys.path so the package is importable however the demo is launched.

The Khronos Fox sample is third-party and is not part of the installed library; if it is not beside this file it is fetched once into $XDG_CACHE_HOME/simvx/example-assets/. The model is CC0-1.0 and its rigging, animation and glTF conversion are CC-BY-4.0; see assets/ATTRIBUTION.md for the credit those terms require.

What it demonstrates

• Importing a rigged, skinned glTF model with import_gltf

• Locating the imported skeleton and its baked SkeletalAnimationClips

• Driving the skeleton with an AnimationPlayer and switching clips live

• A WorldEnvironment (procedural sky + ambient) for consistent lighting

• A responsive, anchored UI overlay with touch-friendly clip and zoom buttons

Controls: Left-click drag: orbit camera Scroll wheel / on-screen +/- buttons: zoom in/out N / on-screen clip buttons: switch animation clip (Survey / Walk / Run) Space / on-screen Pause button: pause or resume the animation Escape: quit

Usage: uv run python examples/features/3d/animated_model.py uv run python examples/features/3d/animated_model.py –test # headless self-check

Source

"""Animated Model: load a rigged glTF and play its skeletal animation.

# /// simvx
# tags = ["3d", "animation", "gltf", "skeletal"]
# web = { root = "AnimatedModel", width = 800, height = 600, responsive = true }
# ///

Auto-downloads the Khronos Fox sample on first run. Fox is a small rigged,
skinned model that ships three baked animation clips (Survey, Walk, Run);
this viewer imports it with ``import_gltf``, drives its skeleton with an
``AnimationPlayer``, and orbits a Camera3D around it under a key/fill light
rig plus a WorldEnvironment so the motion is well-lit on web and desktop.

Asset references use the canonical ``Resource(package, name)`` form, which
resolves through ``importlib.resources``. The ``Fox`` directory beside this file
is a real Python package (it carries an empty ``__init__.py``); we add that
``assets`` directory to ``sys.path`` so the package is importable however the
demo is launched.

The Khronos Fox sample is third-party and is not part of the installed library;
if it is not beside this file it is fetched once into
``$XDG_CACHE_HOME/simvx/example-assets/``. The model is CC0-1.0 and its rigging,
animation and glTF conversion are CC-BY-4.0; see ``assets/ATTRIBUTION.md`` for
the credit those terms require.

## What it demonstrates
  - Importing a rigged, skinned glTF model with ``import_gltf``
  - Locating the imported skeleton and its baked SkeletalAnimationClips
  - Driving the skeleton with an ``AnimationPlayer`` and switching clips live
  - A WorldEnvironment (procedural sky + ambient) for consistent lighting
  - A responsive, anchored UI overlay with touch-friendly clip and zoom buttons

Controls:
    Left-click drag: orbit camera
    Scroll wheel / on-screen +/- buttons: zoom in/out
    N / on-screen clip buttons: switch animation clip (Survey / Walk / Run)
    Space / on-screen Pause button: pause or resume the animation
    Escape: quit

Usage:
    uv run python examples/features/3d/animated_model.py
    uv run python examples/features/3d/animated_model.py --test   # headless self-check
"""

import math
import os
import sys
import urllib.request
from pathlib import Path

# Make ``examples/features/3d/assets`` importable so ``Resource("Fox", ...)``
# resolves to the package next door, mirroring how a game project ships its
# own assets dir on ``sys.path``.
_ASSETS_PARENT = (Path(__file__).parent / "assets").resolve()
if str(_ASSETS_PARENT) not in sys.path:
    sys.path.insert(0, str(_ASSETS_PARENT))

from simvx.core import (  # noqa: E402
    AnchorPreset,
    AnimationPlayer,
    Button,
    Camera3D,
    Colour,
    DirectionalLight3D,
    HBoxContainer,
    Input,
    InputMap,
    Key,
    Label,
    MeshInstance3D,
    MouseButton,
    Node,
    Panel,
    Resource,
    Skeleton,
    Vec2,
    WorldEnvironment,
)
from simvx.graphics import App  # noqa: E402

# One canonical handle per asset. Construction is lazy: the underlying file is
# not touched until ``.path`` is accessed.
FOX_GLTF = Resource("Fox", "Fox.gltf")
FOX_BIN = Resource("Fox", "Fox.bin")
FOX_TEXTURE = Resource("Fox", "Texture.png")

# Khronos glTF-Sample-Assets raw URLs.
_BASE_URL = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets" "/main/Models/Fox/glTF"
_DOWNLOAD_TARGETS = [FOX_GLTF, FOX_BIN, FOX_TEXTURE]

# Clip to play first. The Fox sample ships "Survey", "Walk" and "Run"; Run is
# the liveliest cycle. Falls back to whatever clips exist if names ever change.
_PREFERRED_CLIP = "Run"

# Zoom limits and step (world units along the orbit radius).
_ZOOM_MIN, _ZOOM_MAX = 120.0, 900.0
_ZOOM_STEP = 60.0

# Overlay geometry: gap between a bar and the viewport edge, padding inside a
# bar, and the spacing an HBoxContainer leaves between buttons.
_GUTTER, _BAR_PAD, _BTN_GAP = 12.0, 6.0, 6.0


def _download_assets() -> None:
    """Fetch the Fox contents if they are not already available.

    Writes into a per-user cache rather than beside this file, so it works from
    a read-only install. The cache directory is put on ``sys.path`` so the
    ``Resource`` lookup above finds it exactly as it finds a checkout copy.
    """
    if all((_ASSETS_PARENT / "Fox" / r.name).exists() for r in _DOWNLOAD_TARGETS):
        return
    cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
    asset_dir = cache / "simvx" / "example-assets" / "Fox"
    asset_dir.mkdir(parents=True, exist_ok=True)
    (asset_dir / "__init__.py").touch()
    if str(asset_dir.parent) not in sys.path:
        sys.path.insert(0, str(asset_dir.parent))
    for resource in _DOWNLOAD_TARGETS:
        dest = asset_dir / resource.name
        if dest.exists():
            continue
        url = f"{_BASE_URL}/{resource.name}"
        print(f"Downloading {resource.name}...")
        urllib.request.urlretrieve(url, dest)


class AnimatedModel(Node):
    def on_ready(self):
        # Input actions MUST be registered here (not in ``main``): the web
        # exporter never calls ``main``, so actions added there are lost.
        InputMap.add_action("quit", [Key.ESCAPE])
        InputMap.add_action("next_clip", [Key.N])
        InputMap.add_action("toggle_pause", [Key.SPACE])

        # Orbit state. The Fox is authored large (it spans ~155 units nose to
        # tail and ~79 tall), so frame its centre from a good distance. A near-
        # side yaw shows it in profile so the running gait is easy to read.
        self._yaw = 85.0
        self._pitch = 10.0
        self._distance = 135.0
        self._auto_rotate = True
        self._target = (0.0, 42.0, 0.0)

        # WorldEnvironment: a procedural sky drives ambient IBL and a raised
        # ambient_light_energy lifts the fill floor. Without this the web
        # backend falls back to a near-black flat ambient (0.03) and the Fox
        # reads almost silhouette; this keeps desktop and web consistently lit.
        self.add_child(
            WorldEnvironment(
                environment_map={"colour": (0.45, 0.55, 0.7)},
                ambient_light_energy=0.9,
            )
        )

        # Camera.
        self._cam = self.add_child(Camera3D(name="Camera", fov=45, near=1.0, far=2000.0))

        # Key light so the skinned mesh is lit as it animates.
        key = DirectionalLight3D(name="KeyLight", intensity=1.6)
        key.look_at((-1.0, -2.0, -1.0))
        self.add_child(key)

        fill = DirectionalLight3D(name="FillLight", intensity=0.4, colour=(0.6, 0.7, 1.0))
        fill.look_at((1.0, -1.0, 2.0))
        self.add_child(fill)

        self._player: AnimationPlayer | None = None
        self._clip_names: list[str] = []
        self._load_model()

        self._build_ui()
        self._update_camera()

    def _load_model(self) -> None:
        from simvx.graphics.assets.scene_import import import_gltf

        # Desktop-only download: ``urllib`` is not available under Pyodide, so
        # browser builds must bundle the assets alongside the game.
        if sys.platform != "emscripten":
            _download_assets()

        # ``Resource.path`` resolves the package handle to a real filesystem
        # path the glTF parser can open; the sibling .bin / .png referenced
        # from inside the .gltf are picked up relative to it automatically.
        model = import_gltf(str(FOX_GLTF.path))
        model.name = "Fox"
        self.add_child(model)

        # The importer attaches the parsed Skeleton to the skinned
        # MeshInstance3D (``node.skeleton``) and hangs the baked clips off the
        # imported root as ``_skeletal_clips``.
        skeleton = self._find_skeleton(model)
        clips = getattr(model, "_skeletal_clips", [])
        if skeleton is None or not clips:
            print("No skeletal animation found in the imported model.")
            return

        # An AnimationPlayer drives the skeleton: each frame it evaluates the
        # active clip and writes per-bone local transforms, then re-poses.
        player = AnimationPlayer(skeleton=skeleton)
        for clip in clips:
            player.add_clip(clip)
        self._clip_names = [c.name for c in clips]
        clip_name = _PREFERRED_CLIP if _PREFERRED_CLIP in self._clip_names else self._clip_names[0]
        player.play(clip_name, loop=True)
        self.add_child(player)
        self._player = player
        print(f"Playing skeletal clip {clip_name!r} ({skeleton.bone_count} bones, {len(clips)} clips).")

    @staticmethod
    def _find_skeleton(root) -> Skeleton | None:
        """Return the first imported node's attached Skeleton, if any."""
        stack = [root]
        while stack:
            node = stack.pop()
            if isinstance(node, MeshInstance3D) and node.skeleton is not None and node.skeleton.bone_count:
                return node.skeleton
            stack.extend(node.children)
        return None

    # ------------------------------------------------------------------ UI ---

    def _build_ui(self) -> None:
        """Anchored, responsive overlay: controls hint + clip/zoom buttons.

        Every top-level Control uses an AnchorPreset plus margins (never an
        absolute position) so the overlay tracks the viewport edges on resize
        and stays usable on web/mobile. The buttons surface touch input, which
        the web runtime delivers as ``MouseButton.LEFT``.
        """
        # Controls hint, top-left.
        hint = Label(
            "Drag: orbit   Scroll/+-: zoom   N: next clip   Space: pause   Esc: quit",
            name="ControlsHint",
        )
        hint.set_anchor_preset(AnchorPreset.TOP_LEFT)
        hint.margin_left = 12.0
        hint.margin_top = 10.0
        hint.font_size = 14.0
        hint.text_colour = Colour.WHITE
        self.add_child(hint)

        btn_w, btn_h = 86.0, 34.0

        # Clip switcher, bottom-left: one Button per clip plus a Pause toggle.
        labels = self._clip_names or [_PREFERRED_CLIP]
        self._clip_buttons: dict[str, Button] = {}
        for name in labels:
            btn = Button(name, name=f"Clip_{name}", on_press=self._make_clip_handler(name))
            btn.size = Vec2(btn_w, btn_h)
            self._clip_buttons[name] = btn
        self._pause_btn = Button("Pause", name="PauseButton", on_press=self._toggle_pause)
        self._pause_btn.size = Vec2(btn_w, btn_h)
        self._add_bar("ClipBar", [*self._clip_buttons.values(), self._pause_btn])

        # Zoom buttons, bottom-right: touch-friendly equivalents of the wheel.
        zoom_in = Button("+", name="ZoomIn", on_press=lambda: self._zoom(-_ZOOM_STEP))
        zoom_out = Button("-", name="ZoomOut", on_press=lambda: self._zoom(_ZOOM_STEP))
        for btn in (zoom_in, zoom_out):
            btn.size = Vec2(40.0, btn_h)
            btn.font_size = 20.0
        self._add_bar("ZoomBar", [zoom_in, zoom_out], right=True)

        self._refresh_clip_buttons()

    def _add_bar(self, name: str, buttons: list[Button], *, right: bool = False) -> None:
        """Anchor a bottom-corner bar and let an HBoxContainer lay its buttons out.

        A BOTTOM_* anchor reads its box size from the margin pairs (width =
        ``margin_right - margin_left``, height = ``margin_bottom - margin_top``),
        so a bar sized to its content sits at the corner with negative margins
        measured back from the bottom edge. The row inside fills the bar, and the
        container does the per-button placement.
        """
        row = HBoxContainer(name=f"{name}Row", children=buttons)
        row.separation = _BTN_GAP
        content = row.get_minimum_size()
        width, height = content.x + 2 * _BAR_PAD, content.y + 2 * _BAR_PAD

        bar = Panel(name=name)
        bar.set_anchor_preset(AnchorPreset.BOTTOM_RIGHT if right else AnchorPreset.BOTTOM_LEFT)
        bar.margin_left = -(width + _GUTTER) if right else _GUTTER
        bar.margin_right = -_GUTTER if right else width + _GUTTER
        bar.margin_top = -(height + _GUTTER)
        bar.margin_bottom = -_GUTTER
        bar.bg_colour = Colour((0.0, 0.0, 0.0, 0.45))
        self.add_child(bar)

        row.set_anchor_preset(AnchorPreset.FULL_RECT)
        row.margin_left = row.margin_top = row.margin_right = row.margin_bottom = _BAR_PAD
        bar.add_child(row)

    def _make_clip_handler(self, name: str):
        return lambda: self._set_clip(name)

    def _set_clip(self, name: str) -> None:
        if self._player is None or name not in self._clip_names:
            return
        self._player.play(name, loop=True)
        self._refresh_clip_buttons()

    def _next_clip(self) -> None:
        if self._player is None or not self._clip_names:
            return
        current = self._player.current_clip
        idx = self._clip_names.index(current) if current in self._clip_names else -1
        self._set_clip(self._clip_names[(idx + 1) % len(self._clip_names)])

    def _toggle_pause(self) -> None:
        if self._player is None:
            return
        if self._player.playing:
            self._player.pause()
        else:
            self._player.resume()
        self._refresh_clip_buttons()

    def _refresh_clip_buttons(self) -> None:
        """Highlight the active clip and reflect play/pause state."""
        if self._player is None:
            return
        active = self._player.current_clip
        for name, btn in self._clip_buttons.items():
            state = Button.VisualState.PRESSED if name == active else None
            btn.set_visual_state_override(state)
        self._pause_btn.text = "Play" if not self._player.playing else "Pause"

    def _zoom(self, delta: float) -> None:
        self._distance = max(_ZOOM_MIN, min(_ZOOM_MAX, self._distance + delta))

    # -------------------------------------------------------------- update ---

    def on_update(self, dt):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return

        if Input.is_action_just_pressed("next_clip"):
            self._next_clip()
        if Input.is_action_just_pressed("toggle_pause"):
            self._toggle_pause()

        if self._auto_rotate:
            self._yaw += 25.0 * dt

        # Left-drag orbit.
        if Input.is_mouse_button_pressed(MouseButton.LEFT):
            delta = Input.mouse_delta
            dx, dy = float(delta.x), float(delta.y)
            if abs(dx) > 0.1 or abs(dy) > 0.1:
                self._auto_rotate = False
                self._yaw -= dx * 0.3
                self._pitch += dy * 0.3
                self._pitch = max(-89.0, min(89.0, self._pitch))

        # Scroll zoom (desktop). On-screen +/- buttons cover touch.
        scroll = Input.scroll_delta
        if scroll[1] != 0.0:
            self._zoom(-scroll[1] * 20.0)

        self._update_camera()

    def _update_camera(self):
        yaw_rad = math.radians(self._yaw)
        pitch_rad = math.radians(self._pitch)
        cp = math.cos(pitch_rad)
        x = self._target[0] + self._distance * cp * math.sin(yaw_rad)
        y = self._target[1] + self._distance * math.sin(pitch_rad)
        z = self._target[2] + self._distance * cp * math.cos(yaw_rad)
        self._cam.position = (x, y, z)
        self._cam.look_at(self._target)


def _selftest() -> bool:
    """Headless check: the Fox resolves, imports rigged, and its skeleton moves.

    Two claims, and the second is the one worth guarding. A glTF that imports
    but whose skeleton is never re-posed draws a model frozen in its bind pose,
    which looks like a working import from a screenshot. So the joint matrices
    are read at the first frame and again a second of playback later, and the
    check is that they differ.

    The model is third-party and is not part of the installed library, so this
    needs one of three things: a copy beside this file, a cache warmed by an
    earlier run, or the network. With none of them the question was never put
    to the code, which is what ``Unsupported`` reports.
    """
    from urllib.error import HTTPError, URLError

    import numpy as np

    from simvx.core.testing.selftest import Unsupported
    from simvx.graphics.testing import assert_not_blank, save_png

    try:
        _download_assets()
    except HTTPError:
        # The server answered and refused: the fetch path itself is wrong.
        raise
    except URLError as exc:
        raise Unsupported(
            f"the Fox sample is neither beside this file nor cached, and it cannot be fetched: {exc.reason}"
        ) from exc

    app = App(title="Animated Model: Fox", width=800, height=600, visible=False)
    scene = AnimatedModel(name="AnimatedModel")
    poses: dict[int, np.ndarray] = {}
    LAST = 60  # a second of playback at the fixed headless step

    def on_frame(idx: int, _t: float) -> bool:
        skeleton = scene._find_skeleton(scene)
        if skeleton is not None and idx in (0, LAST):
            poses[idx] = np.array(skeleton.joint_matrices, copy=True)
        return True

    frames = app.run_headless(scene, frames=LAST + 1, on_frame=on_frame, capture_frames=[LAST])
    assert_not_blank(frames[0])
    save_png(frames[0], "/tmp/animated_model_test.png")

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    check(
        "the Resource handle resolves to a file on disk",
        Path(FOX_GLTF.path).is_file(),
        str(FOX_GLTF.path),
    )

    fox = next((child for child in scene.children if child.name == "Fox"), None)
    meshes = []
    if fox is not None:
        stack = [fox]
        while stack:
            node = stack.pop()
            if isinstance(node, MeshInstance3D) and node.mesh is not None:
                meshes.append(node)
            stack.extend(node.children)
    check(
        "import_gltf hangs a model carrying mesh geometry off the viewer",
        fox is not None and bool(meshes),
        f"children: {[c.name for c in scene.children]}, {len(meshes)} mesh instance(s)",
    )

    skeleton = scene._find_skeleton(scene)
    check(
        "the imported mesh comes rigged, with its skeleton attached",
        skeleton is not None and skeleton.bone_count > 0,
        f"{0 if skeleton is None else skeleton.bone_count} bones",
    )
    check(
        "the baked clips are loaded and one of them is playing",
        scene._player is not None and bool(scene._clip_names),
        f"clips {scene._clip_names}",
    )

    moved = 0.0 if len(poses) < 2 else float(np.abs(poses[LAST] - poses[0]).max())
    check(
        "and the AnimationPlayer re-poses the skeleton as it runs",
        moved > 1e-4,
        f"largest joint-matrix change over {LAST} frames is {moved:.4f}",
    )

    print("screenshot: /tmp/animated_model_test.png")
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    if "--test" in sys.argv:
        from simvx.core.testing.selftest import run_selftest

        sys.exit(run_selftest(_selftest))
    App(title="Animated Model: Fox", width=800, height=600).run(AnimatedModel())