Instance

The Instance class represents a single particle system with its own shaders, geometry, and attributes. You don’t instantiate this class directly—it’s created by calling renderer.add().

Instance Settings

When you call renderer.add(), you pass an InstanceProps object that configures the particle instance.

vertex

string

GLSL vertex shader source code. This shader determines the position and appearance of each particle.

Example

attribute vec3 aPosition;
attribute vec3 aOffset;
uniform mat4 uProjectionMatrix;
uniform mat4 uModelMatrix;
uniform mat4 uViewMatrix;

void main() {
  vec3 position = aPosition + aOffset;
  gl_Position = uProjectionMatrix * uModelMatrix * uViewMatrix * vec4(position, 1.0);
  gl_PointSize = 2.0;
}

fragment

string

GLSL fragment shader source code. This shader determines the color of each particle.

Example

precision mediump float;

void main() {
  gl_FragColor = vec4(1.0, 0.5, 0.0, 1.0);
}

uniforms

{ [key: string]: UniformProps }

default:"{}"

Custom uniforms to pass to the shaders. The renderer automatically provides uProjectionMatrix, uModelMatrix, and uViewMatrix.

Example

uniforms: {
  uTime: {
    type: 'float',
    value: [0],
  },
  uColor: {
    type: 'vec3',
    value: [1, 0.5, 0],
  },
}

attributes

AttributeProps[]

default:"[]"

Custom vertex attributes. Each attribute defines data that varies per particle.

Each attribute has these properties:

name

string

required

The attribute name used in the vertex shader (e.g., aOffset, aVelocity).

size

number

required

Number of components per vertex (1 for float, 2 for vec2, 3 for vec3, 4 for vec4).

data

(index: number, total: number) => number[]

Function that returns the attribute data for each particle. Called once per particle during initialization.

Example

attributes: [
  {
    name: 'aOffset',
    size: 3,
    data: (i, total) => [
      Math.random() * 2 - 1,
      Math.random() * 2 - 1,
      Math.random() * 2 - 1,
    ],
  },
  {
    name: 'aVelocity',
    size: 3,
    data: (i, total) => [
      (Math.random() - 0.5) * 0.01,
      (Math.random() - 0.5) * 0.01,
      (Math.random() - 0.5) * 0.01,
    ],
  },
]

geometry

GeometryProps

default:"{ vertices: [{ x: 0, y: 0, z: 0 }] }"

The base geometry for each particle. By default, each particle is a single point at the origin.

vertices

Array<{ x: number; y: number; z: number }>

Array of vertex positions. Each particle instance uses this geometry.

normal

Array<{ x: number; y: number; z: number }>

Array of vertex normals. If provided, an aNormal attribute is automatically created.

Example

// Single point (default)
geometry: {
  vertices: [{ x: 0, y: 0, z: 0 }],
}

// Triangle
geometry: {
  vertices: [
    { x: 0, y: 0.1, z: 0 },
    { x: -0.1, y: -0.1, z: 0 },
    { x: 0.1, y: -0.1, z: 0 },
  ],
}

multiplier

number

default:"1"

Number of times to repeat the geometry. This is how you create multiple particles—each particle gets its own copy of the geometry.

Example

// Create 10,000 particles
multiplier: 10000

mode

number

default:"0"

WebGL drawing mode. Use 0 for POINTS, 4 for TRIANGLES, 5 for TRIANGLE_STRIP, etc.

Example

// Points (default)
mode: 0

// Triangles
mode: 4

onRender

(instance: Instance) => void

Optional callback invoked after each frame is rendered. Use this to update uniforms or perform per-frame calculations for this specific instance.

Example

renderer.add('particles', {
  // ... other settings
  onRender: (instance) => {
    instance.uniforms.uTime.value[0] += 0.01;
  },
});

modifiers

{ [attributeName: string]: (data: any, vertexIndex: number, component: number, instance: Instance) => number }

Functions that modify attribute values during buffer creation. Each modifier receives the attribute’s data and returns a modified value.

Example

modifiers: {
  aOffset: (data, i, j, instance) => {
    // Arrange particles in a grid
    const size = Math.sqrt(instance.multiplier);
    if (j === 0) return (i % size) * 0.1 - (size * 0.05);
    if (j === 1) return Math.floor(i / size) * 0.1 - (size * 0.05);
    return 0;
  },
}

Methods

These methods are available on Instance objects, but you typically don’t call them directly.

prepareAttribute()

Prepares a single attribute by generating its buffer data.

prepareAttribute(attribute: AttributeProps): void

attribute

AttributeProps

required

The attribute to prepare with name, size, and optional data function.

This method:

Creates a Float32Array buffer sized for all particles
Calls the attribute’s data function for each particle
Applies any modifiers for the attribute
Stores the buffer data on the attribute
Calls prepareBuffer() to upload to GPU

prepareBuffer()

Creates a WebGL buffer and uploads attribute data to the GPU.

prepareBuffer(attribute: AttributeProps): void

attribute

AttributeProps

required

The attribute with prepared data to upload.

render()

Renders the instance for a single frame.

render(renderUniforms: object): void

renderUniforms

object

required

Shared uniforms from the renderer (projection, view, and model matrices).

This method:

Activates the instance’s shader program
Binds all vertex attribute buffers
Updates all uniforms (shared and instance-specific)
Calls gl.drawArrays() to render
Invokes the onRender callback if defined

destroy()

Cleans up WebGL resources for this instance.

destroy(): void

This method:

Deletes all vertex buffers
Deletes the shader program
Nullifies the WebGL context reference

Properties

Instance objects expose these public properties:

WebGLRenderingContext

The WebGL rendering context.

program

WebGLProgram

The compiled and linked shader program.

uniforms

{ [key: string]: UniformProps }

All uniforms for this instance, including shared renderer uniforms.

attributes

AttributeProps[]

All vertex attributes with their buffer data.

buffers

BufferProps[]

WebGL buffer objects for each attribute.

geometry

GeometryProps

The base geometry configuration.

multiplier

number

Number of particles (geometry instances).

mode

number

WebGL drawing mode.

onRender

(instance: Instance) => void

Optional callback invoked after each render. Use this to update uniforms or perform per-frame calculations.

Example: Updating Uniforms

const instance = renderer.add('particles', {
  // ... other settings
  uniforms: {
    uTime: {
      type: 'float',
      value: [0],
    },
  },
});

// Update uniforms each frame
instance.onRender = (instance) => {
  instance.uniforms.uTime.value[0] += 0.01;
};

API

Instance Settings

vertex

Example

fragment

Example

uniforms

Example

attributes

Example

geometry

Example

multiplier

Example

mode

Example

onRender

Example

modifiers

Example

Methods

prepareAttribute()

prepareBuffer()

render()

destroy()

Properties

Example: Updating Uniforms

Build docs developers (and LLMs) love

API

Documentation Index

​Instance Settings

​vertex

​Example

​fragment

​Example

​uniforms

​Example

​attributes

​Example

​geometry

​Example

​multiplier

​Example

​mode

​Example

​onRender

​Example

​modifiers

​Example

​Methods

​prepareAttribute()

​prepareBuffer()

​render()

​destroy()

​Properties

​Example: Updating Uniforms

Build docs developers (and LLMs) love

Instance Settings

vertex

Example

fragment

Example

uniforms

Example

attributes

Example

geometry

Example

multiplier

Example

mode

Example

onRender

Example

modifiers

Example

Methods

prepareAttribute()

prepareBuffer()

render()

destroy()

Properties

Example: Updating Uniforms