Skip to content

feat(gltf): support independently animated scenegraph instances - #2991

Draft
ibgreen-openai wants to merge 3 commits into
masterfrom
codex/gltf-independent-instances
Draft

feat(gltf): support independently animated scenegraph instances#2991
ibgreen-openai wants to merge 3 commits into
masterfrom
codex/gltf-independent-instances

Conversation

@ibgreen-openai

Copy link
Copy Markdown
Collaborator

Goals

  • Let several scenegraph consumers independently animate the same immutable, postprocessed glTF asset without introducing a parallel skeleton, animation mixer, material system, or glTF loader.
  • Make the resulting scene and animator directly usable by deck.gl-style getScene / getAnimator integrations.
  • Keep independent node transforms, clip selection, phase, playback speed, crossfades, skin palettes, morph buffers, material-pointer state, and resource ownership correct on both WebGL and WebGPU.

Changes

  • Add public createGLTFAnimationInstances, GLTFAnimationInstances, GLTFAnimationInstance, and typed creation/selection options to @luma.gl/gltf.
  • Reuse the existing createScenegraphsFromGLTF, GLTFAnimator, engine AnimationMixer, GLTFSkinController, and canonical morph-target path for every isolated character.
  • Support independently positioned roots; named source nodes; clip selection and crossfades; normalized clip phases and absolute seconds; pause/play, reverse/speed, and once/repeat/ping-pong looping; safe removal and idempotent disposal.
  • Keep authored source accessors/images immutable and shared while giving every character its own mutable scenegraph, materials, mixer actions, joint matrices, and packed morph vertex buffers.
  • Automatically delegate to the scenegraph-owned resource lifecycle when available, keeping the companion shared-resource-cache foundation independently mergeable.
  • Add a substantial dedicated API guide, glTF documentation tab/sidebar, cross-navigation, fixture-backed regressions, and live browser rendering tests.

Verification

  • Cross-package strict TypeScript project-reference build: node_modules/.bin/tspc -b modules/*/tsconfig.json --pretty false.
  • 172 Node tests across 34 suites covering glTF, ANARI, engine animation, and experimental rendering.
  • Dedicated SimpleSkin.gltf, AnimatedMorphCube.glb, and AnimatedColorsCube.glb regressions prove independent roots, source immutability, skin palettes, GPU buffer bytes, material pointers, clip transitions, timing, pause/reverse, and safe disposal.
  • Real headless Chromium hardware Metal WebGL + WebGPU draws two simultaneous independently skinned characters and two independently morphed characters; the same coverage also passes SwiftShader software WebGL + WebGPU.
  • Additional untracked local verification using CC0 RobotExpressive.glb: 14 named clips, three simultaneous Dance/Running/Walking characters, two independent 43-joint palettes per character, facial morph targets, an actual 50/50 Dance→Wave crossfade, and safe surviving-instance destruction. The external robot asset is not vendored by this PR.
  • Full production Docusaurus build succeeds and indexes 474 documentation pages; generated route, tab/sidebar, and internal links verified.
  • Scoped Biome formatting/lint and git diff --check pass.
  • The legacy repository pre-commit script cannot run in the existing installation because injected YARN_NO_PROXY is rejected by its installed Yarn configuration; equivalent strict build, 172 tests, both native/software GPU runs, and the complete documentation build were run explicitly before committing. The normal organizational pre-push hook remained enabled.

Architecture / Ownership

  • All new runtime ownership stays in @luma.gl/gltf; existing rendering, interpolation, shaders, and retained-object packages remain unchanged.
  • Shared source asset data does not imply one instanced GPU draw: independently deformed poses currently remain separate render groups on both backends. Shared GPU texture caching belongs to the independently mergeable asset-resource lifecycle PR, not this manager.
  • Targets master directly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants