troika-three-utils

What is troika-three-utils?

The troika-three-utils package provides a collection of utility functions and classes to simplify common tasks when working with Three.js, a popular 3D library for JavaScript. These utilities help with tasks such as geometry manipulation, shader management, and scene graph operations.

What are troika-three-utils's main functionalities?

Geometry Utilities

This feature allows you to merge multiple geometries into a single geometry. This can be useful for optimizing performance by reducing the number of draw calls.

const { mergeBufferGeometries } = require('troika-three-utils');
const geometry1 = new THREE.BoxGeometry(1, 1, 1);
const geometry2 = new THREE.SphereGeometry(0.5, 32, 32);
const mergedGeometry = mergeBufferGeometries([geometry1, geometry2]);

Shader Utilities

This feature allows you to create a derived material from an existing material, adding custom shaders and uniforms. This is useful for creating complex visual effects without having to write a new material from scratch.

const { createDerivedMaterial } = require('troika-three-utils');
const baseMaterial = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
const derivedMaterial = createDerivedMaterial(baseMaterial, {
  uniforms: {
    time: { value: 0 }
  },
  vertexShader: 'varying float vTime; void main() { vTime = time; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }',
  fragmentShader: 'varying float vTime; void main() { gl_FragColor = vec4(vTime, 0.0, 0.0, 1.0); }'
});

Scene Graph Utilities

This feature provides a utility to traverse the scene graph, applying a callback function to each object. This can be useful for operations like searching for specific objects or applying transformations.

const { traverseScene } = require('troika-three-utils');
const scene = new THREE.Scene();
const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial());
scene.add(mesh);
traverseScene(scene, (object) => {
  console.log(object);
});

0

README

Troika Three.js Utilities

This package provides various utilities for working with Three.js, particularly having to do with shaders. It is used by Troika 3D, but has no dependencies itself other than Three.js, so it can be used outside the Troika framework.

Installation

Get it from NPM:

npm install troika-three-utils

You will also need to install a compatible version of Three.js; see the notes in the Troika 3D Readme for details.

Provided Utilities

Several utilities are provided; for a full list follow the imports in index.js to their source files, where each is documented in JSDoc comments.

Some of the most useful ones are:

createDerivedMaterial()

Source code with JSDoc

One of the most powerful things about Three.js is its excellent set of built-in materials. They provide many features like physically-based reflectivity, shadows, texture maps, fog, and so on, building the very complex shaders behind the scenes.

But sometimes you need to do something custom in the shaders, such as move around the vertices, or change the colors or transparency of certain pixels. You could use a ShaderMaterial but then you lose all the built-in features. The experimental NodeMaterial seems promising but doesn't appear to be ready as a full replacement.

The onBeforeCompile hook lets you intercept the shader code and modify it, but in practice there are quirks to this that make it difficult to work with, not to mention the complexity of forming regular expressions to inject your custom shader code in the right places.

Troika's createDerivedMaterial(baseMaterial, options) utility handles all that complexity, letting you "extend" a built-in Material's shaders via a declarative interface. The resulting material is prototype-chained to the base material so it picks up changes to its properties. It has methods for generating depth and distance materials so your shader modifications can be reflected in shadow maps. Derived materials may themselves be derived from recursively for composability.

Here's a simple example that injects an auto-incrementing elapsed uniform holding the current time, and uses that to transform the vertices in a wave pattern.

import { createDerivedMaterial} from 'troika-three-utils'
import { Mesh, MeshStandardMaterial, PlaneBufferGeometry } from 'three'

const baseMaterial = new MeshStandardMaterial({color: 0xffcc00})
const customMaterial = createDerivedMaterial(
  baseMaterial,
  {
    timeUniform: 'elapsed',
    vertexTransform: `
      float waveAmplitude = 0.1
      float waveX = uv.x * PI * 4.0 - mod(elapsed / 300.0, PI2);
      float waveZ = sin(waveX) * waveAmplitude;
      normal.xyz = normalize(vec3(-cos(waveX) * waveAmplitude, 0.0, 1.0));
      position.z += waveZ;
    `
  }
)
const mesh = new Mesh(
  new PlaneBufferGeometry(1, 1, 64, 1),
  customMaterial
)
mesh.customDepthMaterial = customMaterial.getDepthMaterial() //for shadows

You can also declare custom uniforms and defines, inject fragment shader code to modify the output color, etc. See the JSDoc in DerivedMaterial.js for full details.

BezierMesh

Source code with JSDoc Online example Online example using InstancedUniformsMesh

This creates a cylindrical mesh and bends it along a 3D cubic bezier path between two points, in a custom derived vertex shader. This is useful for visually connecting objects in 3D space with a line that has thickness to it.

import { BezierMesh } from 'troika-three-utils'

const bezier = new BezierMesh()
bezier.pointA.set(-0.3, 0.4, -0.3)
bezier.controlA.set(0.7, 0.6, 0.4)
bezier.controlB.set(-0.6, -0.6, -0.6)
bezier.pointB.set(0.7, 0, -0.7)
bezier.radius = 0.01
scene.add(bezier)

InstancedUniformsMesh

NOTE: InstancedUniformsMesh has been moved to its own three-instanced-uniforms-mesh package.

Changelog

0.38.1 (2021-02-03)

Bug Fixes

• hoist vertexTransform defs to top of the shader to prevent errors in chained derivations (889ed38)
• update to support up to Three r125 (4edff04)
• three-instanced-uniforms-mesh: prevent creation of multiple derived geometries (94a7f67)
• three-instanced-uniforms-mesh: the derived material is now prototype-chained to its base (bf45d01)
• troika-worker-utils: properly track open requests count (a01d903)
• make derived material's customProgramCacheKey function writable (10289dd)
• troika-three-text: prevent copy() from sharing geometry between instances (8c3ba2d)
• add new text props to UI blocks (a2d631f)