@threlte/extras

<InstancedSprite>

The <InstancedSprite> component allows you to efficiently spawn large numbers of animated sprites in your scene and update each instance using the useInstancedSprite hook, or with a <Instance> component available through a slot prop.

You can find an example of a more complex scene here.

<InstancedSprite>

To use the <InstancedSprite> you must provide it with sprite metadata and a texture. While we recommend utilizing the buildSpritesheet() utility for this purpose, you are also free to implement your own custom solution, provided it meets the component’s input requirements.

Other than it’s own props, <InstanedSprite/> extends and accepts all properties of Three.js instanced mesh, such as castShadow, frustumCulled etc.

<InstancedSprite
  bind:ref
  {spritesheet}
  count={500}
  playmode={'FORWARD'}
  fps={9}
  billboarding
  hueShift={{ h: 1.5, s: 0.9, v: 1 }}
  randomPlaybackOffset={2000}
  castShadow
/>

Required props

Optional props

You create and update instances in three ways:

1. Utilizing the useInstancedSprite() hook (recommended approach).
2. Using the <Instance> component offered through a slot prop.
3. Directly with the underlying class using the ref binding.

useInstancedSprite

The hook has to be used in a child component of <InstancedSprite> and returns an object with following properties:

• count: Total number of instances.
• updatePosition(id: number, position: Vector3Tuple, scale?: Vector2Tuple): A utility function for updating an instance’s position and scale.
• animationMap: A writable store (Writable<Map<string, number>>) that maps animation names to their corresponding IDs. Animation names are useful to have for setting a random animation from a pool etc. The IDs are reserved for more advanced usecases.
• sprite: Provides direct access to the InstancedSpriteMesh, enabling updates to instance properties such as animations, billboarding, and play mode.

import { useInstancedSprite } from '@threlte/extras'

const hook = useInstancedSprite()
// it's useful to immediately destructure it like this
const { updatePosition, count, animationMap, sprite } = useInstancedSprite()

// Examples of using the InstancedSpriteMesh API:

// play animation on instance id 0 - loops by defualt
sprite.play('IdleBackward').at(0)
// play animation without looping
sprite.play('RunLeft', false).at(1)
// play animation backwards with looping
sprite.play('RunLeft', true, 'REVERSE').at(2)

// mesh.play is a utility that combines the use of these functions:
// animation by name
sprite.animation.setAt(0, 'RunBackward')
// looping y/n
sprite.loop.setAt(0, false)
// animation direction - FORWARD (default) / REVERSE / PAUSE
sprite.playmode.setAt(0, 'REVERSE')

// billboarding
sprite.billboarding.setAll(true)
sprite.billboarding.setAt(0, true)

Typescript support

The useInstancedSprite hook supports typing for autocompletion of animation names:

type AnimationNames = 'walk' | 'run' | 'idle' | 'fly'
const { updatePosition, count, animationMap, sprite } = useInstancedSprite<AnimationNames>()

<Instance>

Instance is a slot prop component that is used to update sprite instances properties. You can gain access to it with the Instance snippet prop on InstancedSprite component. Then put it as a child component. The only required property is id. It also has position of type Vector3Tuple prop and scale of type Vector2Tuple.

Other than this, it as other properties that you can find in the InstancedSpriteMesh, so: animationName, playmode, billboarding, offset, loop, flipX, flipY, frameId. Read more about them in the InstancedSpriteMesh section

The <Instance> component serves as a declarative alternative to useInstancedSprite hook to dynamically update the properties of sprite instances within the InstancedSprite component. You can access through the Instance snippet prop.

Example: Set a position, scale and flipX for every instance.

<InstancedSprite
  count={10000}
  {spritesheet}
>
  {#snippet children({ Instance })}
    {#each { length: 10000 } as _, i}
      <Instance
        position={[Math.random() * 100, Math.random() * 100, Math.random() * 100]}
        scale={[3, 3]}
        flipX
        id={i}
      />
    {/each}
  {/snippet}
</InstancedSprite>

binding

The InstancedSpriteMesh class is the foundation behind the <InstancedSprite> component, written to enable efficient instancing of animated sprites within a Three.js environment. The <InstancedSprite> component lets you bind to it through ref.

The class extends the capabilities of the troika’s InstancedUniformsMesh. For an in-depth exploration of InstancedSpriteMesh and its features, refer to the documentation available at InstancedSpriteMesh docs.

Spritesheets

SpritesheetMetadata

Object used in buildSpritesheet function has to be compliant with the SpritesheetMetadata type format. This type is structured to accommodate the metadata for one or multiple sprite files within a single spritesheet.

type SpritesheetMetadata = {
  url: string
  type: 'rowColumn' | 'frameSize'
  width: number
  height: number
  animations: {
    name: string
    frameRange: [number, number]
  }[]
}[]

Understanding SpritesheetMetadata

A SpritesheetMetadata is an array, with each entry representing metadata fields for one sprite:

• url: Specifies the path or URL to the sprite image file.
• type: Determines the method of defining the spritesheet dimensions. Type "rowColumn" specifies the layout in terms of rows and columns within the image, and type "frameSize" instead defines the size of each frame, allowing the utility to calculate the layout.
• width and height: Depending on type, these refer to the number of columns and rows ("rowColumn") or the dimensions of a single frame ("frameSize").
• animations: An array detailing the animations, where each animation has a name and a frameRange. The frameRange is a tuple marking the start and end frames of the animation.

Typesafety

For improved developer experience when working with TypeScript, it is strongly recommended to use as const assertion in combination with satisfies SpritesheetMetadata. This approach not only ensures compliance with the SpritesheetMetadata type but also enables autocompletion for animation names within utility functions, which is highly recommended:

buildSpritesheet()

buildSpritesheet() is a utility function for building a final texture and spritesheet object from a provided SpritesheetMetadata object or external source. Each buildSpritesheet method return an Promise that and has to be awaited. Promise returned by each method contains an object with a spritesheet ready for use in <InstancedSprite>.

buildSpritesheet().from(meta: SpritesheetMetadata)

Other than spritesheet promise, it also returns a useInstancedSprite hook. This hook can be enhanced with extra typescript support for autocompletion of animation names as such:

const meta = [
  {
    url: '/textures/sprites/cacodaemon.png',
    type: 'rowColumn',
    width: 8,
    height: 4,
    animations: [
      { name: 'fly', frameRange: [0, 5] },
      { name: 'attack', frameRange: [8, 13] },
      { name: 'idle', frameRange: [16, 19] },
      { name: 'death', frameRange: [24, 31] }
    ]
  }
] as const satisfies SpritesheetMetadata

const result = buildSpritesheet.from<typeof meta>(meta)

buildSpritesheet().fromAseprite(asepriteDataUrl: string, spriteImageUrl: string)

Similar to above, but it parses the Aseprite metadata json into the correct format. Does not provide any additional utilities.

Examples

Multiple animations

const demonSpriteMeta = [
  {
    url: '/textures/sprites/cacodaemon.png',
    type: 'rowColumn',
    width: 8,
    height: 4,
    animations: [
      { name: 'fly', frameRange: [0, 5] },
      { name: 'attack', frameRange: [8, 13] },
      { name: 'idle', frameRange: [16, 19] },
      { name: 'death', frameRange: [24, 31] }
    ]
  }
] as const satisfies SpritesheetMetadata

Multiple files

const goblinSpriteMeta = [
  {
    url: '/textures/sprites/goblin/Attack.png',
    type: 'rowColumn',
    width: 8,
    height: 1,
    animations: [{ name: 'attack', frameRange: [0, 7] }]
  },
  {
    url: '/textures/sprites/goblin/Death.png',
    type: 'rowColumn',
    width: 4,
    height: 1,
    animations: [{ name: 'death', frameRange: [0, 3] }]
  },
  {
    url: '/textures/sprites/goblin/Idle.png',
    type: 'rowColumn',
    width: 4,
    height: 1,
    animations: [{ name: 'idle', frameRange: [0, 3] }]
  }
] as const satisfies SpritesheetMetadata

Static sprites & Atlassing

This component focuses on targetting animated sprites, but it’s possible to use it for static images as well. If each frame of the spritesheet is a separate animation, then it effectively acts as an atlas with named sprites.

The <Tree/> component in the example above does this.

Set autoUpdate={false} on static components and only update it manually with sprite.update(). This has to be done when the InstancedSprite is initiated or when spritesheet or atlas change. If you don’t do it, then the spritesheet will run animation updates each frame to run animations that don’t really exist.