Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

troika-three-utils

protectwise1.7mMIT0.52.4

Various utilities related to Three.js

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

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

0.52.4 (2025-04-02)

Bug Fixes

  • error in Three r175 with custom(Depth|Distance)Material not having setters (78e00b5), closes #357

0.52.0 (2024-11-11)

Note: Version bump only for package troika-three-utils

0.51.0 (2024-11-10)

Note: Version bump only for package troika-three-utils

0.50.3 (2024-11-01)

Bug Fixes

  • Error in derived materials in Three r170 (2402026)

0.50.0 (2024-10-11)

Bug Fixes

  • troika-three-utils: add colorspace_fragment (introduced in Three r154) to the list of fragment shaders to process in upgradeShaders() (#325) (9169ebf)
  • change JSDoc for createDerivedMaterial params to be optional (#307) (6969e85)

Features

  • troika-three-utils: add isDerivedFrom method to derived materials (a4a2fcd)

0.49.0 (2023-10-08)

Note: Version bump only for package troika-three-utils

0.48.0 (2023-09-09)

Note: Version bump only for package troika-three-utils

0.47.2 (2023-05-15)

Bug Fixes

  • troika-three-utils: pass renderer argument to base material's onBeforeCompile (3a23a8e)
  • troika-three-utils: vertexTransform now handles MAP_UV token introduced in Three r152 (d8c32ed)

0.47.0 (2022-12-15)

Bug Fixes

  • Remove incomplete ShaderFloatArray utility to fix build (ddf712a)

Features

  • raise three min version to r125 and fix BufferGeometry references (#225) (f2ef803)

0.46.0 (2022-03-05)

Note: Version bump only for package troika-three-utils

0.45.0 (2022-01-02)

Bug Fixes

  • createDerivedMaterial: propagate the base material's customProgramCacheKey (9c8c6b1)

0.44.0 (2021-11-14)

Note: Version bump only for package troika-three-utils

0.43.0 (2021-09-20)

Bug Fixes

  • InstancedUniformsMesh: reuse same derived material instance when uniform names change (bd7cea6), closes #154

0.42.0 (2021-05-17)

Features

  • open up 'three' peer dependency to include future versions (d4a5b23)

0.41.0 (2021-04-19)

Features

  • update support up to threejs r127 (5b512f0)

0.40.0 (2021-02-28)

Note: Version bump only for package troika-three-utils

0.39.0 (2021-02-15)

Bug Fixes

  • restore compatibility with three versions <0.113.0 by copying MathUtils.generateUUID (35856b5)

0.38.1 (2021-02-03)

Bug Fixes

  • hoist vertexTransform defs to top of the shader to prevent errors in chained derivations (889ed38)
  • make derived material's customProgramCacheKey function writable (10289dd)
  • update to support up to Three r125 (4edff04)

0.38.0 (2021-01-24)

Features

  • move InstancedUniformsMesh to its own three-instanced-uniforms-mesh package (f623b1f)

0.37.0 (2021-01-18)

Features

  • add InstancedUniformsMesh class for setting shader uniforms per instance (5fd4d79)

0.36.0 (2020-12-04)

Note: Version bump only for package troika-three-utils

0.35.0 (2020-11-16)

Note: Version bump only for package troika-three-utils

0.34.0 (2020-10-19)

Note: Version bump only for package troika-three-utils

0.33.1 (2020-10-02)

Note: Version bump only for package troika-three-utils

0.33.0 (2020-10-02)

Bug Fixes

  • add "sideEffects":false to package.json files to assist treeshaking (61109b2)
  • add PURE annotations to make troika-three-text treeshakeable (8e76b5c)
  • remove redundant "browser" and defunct "jsnext:main" fields from package.json files (0abec40)

Features

  • troika-three-utils: add chained option to createDerivedMaterial (2bfaa9c)

0.32.0 (2020-09-16)

Bug Fixes

0.31.0 (2020-08-11)

Bug Fixes

  • move Three.js peerDependency from troika-3d to troika-three-utils (96b6fc8)

0.30.0 (2020-07-16)

Note: Version bump only for package troika-three-utils

0.29.0 (2020-07-06)

Bug Fixes

  • troika-three-utils: fix program switching when double-deriving materials (89ed2f8)

0.28.1 (2020-06-17)

Bug Fixes

  • troika-3d-text: don't dispose derived materials on base material switch (3d88475), closes #59

Performance Improvements

  • troika-three-utils: increase chance of program reuse in createDerivedMaterial (56daf65), closes #59

0.28.0 (2020-06-09)

Note: Version bump only for package troika-three-utils

0.27.0 (2020-06-02)

Note: Version bump only for package troika-three-utils

0.26.0 (2020-05-24)

Note: Version bump only for package troika-three-utils

0.25.0 (2020-05-19)

Note: Version bump only for package troika-three-utils

0.24.0 (2020-04-27)

Bug Fixes

  • troika-three-utils: allow use of the timeUniform within glsl functions (7354b9e)

0.23.0 (2020-04-16)

Bug Fixes

  • troika-three-utils: fragmentColorTransform is now inserted prior to postprocessing chunks (97cd9ac), closes #20

0.22.0 (2020-04-02)

Note: Version bump only for package troika-three-utils

0.21.0 (2020-03-27)

Features

  • examples: beziers: add instanceable version of the beziers, and add point light option (0739f4d)
  • troika-three-utils: added new options for createDerivedMaterial (d67bb4a)
  • troika-three-utils: derived shadow material uniforms are now synced automatically (7843f23)

0.20.0 (2020-03-16)

Note: Version bump only for package troika-three-utils

0.19.0 (2020-02-28)

Note: Version bump only for package troika-three-utils

0.18.0 (2020-02-21)

Note: Version bump only for package troika-three-utils