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 on Three.js versions in the Getting Started docs for details.

npm install three

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()

This utility allows you to easily extend existing Three.js materials with your own custom shader code. This is an incredibly powerful tool, and is the secret behind most of Troika's shader-driven tools like troika-three-text, three-instanced-uniforms-mesh, and BezierMesh.

See the createDerivedMaterial documentation page and its source code with JSDoc for details.

BezierMesh

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.

See the BezierMesh documentation page and its source code with JSDoc for details.

InstancedUniformsMesh

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

Changelog

0.51.0 (2024-11-10)

Bug Fixes

• BatchedText: Fix texel read for taller data texture (57f3b0b)
• troika-three-text: Fix error when first character is whitespace #313 (f71679e)

Features

• BatchedText: support fillOpacity, and color now sets the diffuse uniform (8f83424)
• troika-three-text: Add config to disable web worker (86023ec), closes #337
• troika-worker-utils: Add a handle to force running worker modules on main thread (4f8bc13)