Instanced skinned mesh

This repository contains a few classes that allow you to animate a large number of skinned meshes efficiently.

Demo

Demo

Editor

InstancedAnimation

This is an abstraction around the InstancedSkinnedMesh class created by CodyJasonBennett, which is a user-land implementation of this PR. One of the main differences is that this class takes a GLTF object and extracts all the animations and skinned meshes from it, which creates a more convenient API for the user. This is more similar to the default animation system in three.js. Additionally, this class is more high-level and does all the boilerplate for you, so you don't have to update the skinned meshes and bones manually.

Usage

import * as THREE from "three";
import { InstancedAnimation, install } from "three-instanced-animation";

install(THREE);

const instancedAnimation = new InstancedAnimation({
  gltf: gltf,
  count: 100,
});

const instance = {
  position: new THREE.Vector3(0, 0, 0),
  rotation: new THREE.Quaternion(),
  scale: new THREE.Vector3(1, 1, 1),
  animations: [
    {
      time: 0,
      weight: 1,
      animationIndex: 0,
    },
  ],
};

instancedAnimation.addInstance(instance);

function update(deltaTime) {
  instancedAnimation.update(deltaTime); // Updates the currentTime of each instance

  // You can modify the instance properties directly, for example:
  instance.position.x += 1;
}

If you want to manage the animation update rate of each instance yourself, you can use the updateInstance method instead of update.

import { InstancedAnimation } from "three-instanced-animation";

const instancedAnimation = new InstancedAnimation({
  gltf: gltf,
  count: 100,
});

const instance = {
  position: new THREE.Vector3(0, 0, 0),
  rotation: new THREE.Quaternion(),
  scale: new THREE.Vector3(1, 1, 1),
  animations: [
    {
      time: 0,
      weight: 1,
      animationIndex: 0,
    },
  ],
};

instancedAnimation.addInstance(instance);

function update(deltaTime) {
  for (let i = 0; i < instance.animations.length; i++) {
    instance.animations[i].time += deltaTime;
  }

  instancedAnimation.updateInstance(0);
}

ViewSensitiveInstancedAnimator

This is an abstraction around the InstancedAnimation class, which allows you to control the animation update rate based on the distance from the camera and ignore the instances outside the camera's frustum. This is useful for large scenes with many animated objects.

Usage

import { ViewSensitiveInstancedAnimator } from "three-instanced-animation";

const viewSensitiveInstancedAnimator = new ViewSensitiveInstancedAnimator({
  gltf: gltf,
  count: 100,
  camera: camera,
  maxAnimationInterval: 100, // This is the update rate when the instance is at `maxDistance`
  minAnimationInterval: 1000 / 60, // This is the update rate when the instance in front of the camera
  maxDistance: 80, // This is the distance at which the instance will be updated at `maxAnimationInterval`
});

const instance = {
  position: new THREE.Vector3(0, 0, 0),
  rotation: new THREE.Quaternion(),
  scale: new THREE.Vector3(1, 1, 1),
  animations: [
    {
      time: 0,
      weight: 1,
      animationIndex: 0,
    },
  ],
};

viewSensitiveInstancedAnimator.addInstance(instance);

function update(deltaTime) {
  viewSensitiveInstancedAnimator.update(deltaTime);
}