Using Vanilla Three.js code in Threepipe

Threepipe is built on top of three.js, so most vanilla three.js code should work without any issues.

However, since threepipe uses a fork of three.js, it is bundled within the package instead of being a separate dependency. This means you can use threepipe as a drop-in replacement for three.js in many cases.

The three.js fork is updated till r160, and is regularly updated with new features and bug fixes.

Importing three.js objects

Importing objects from three.js can be done normally when using a modern bundler like vite 5+ on node 22+. In all other cases(import-maps, other bundlers etc), objects can be imported from threepipe instead of three, or three can be aliased to threepipe. Follow this guide for that.

Classes, types, constants, and functions from three.js can be imported from threepipe in the same way as you would import from three. With npm modules -

import { Scene, PerspectiveCamera, WebGLRenderer, Mesh, BoxGeometry, MeshBasicMaterial } from 'threepipe';

TIP

In many cases, threepipe provides an extended class as an alternative to the original three.js class. These extended classes provide additional features and methods that are not available in the original three.js classes and provide better experience with typescript and autocomplete. It's not necessary to use these extended classes, and standard ones would work fine, but they are recommended for better experience.

Some examples are -

• MeshPhysicalMaterial, MeshStandardMaterial -> PhysicalMaterial
• MeshBasicMaterial -> UnlitMaterial
• Mesh2 -> Mesh
• BufferGeometry2 -> BufferGeometry

See also - GeometryGeneratorPlugin, Object3DGeneratorPlugin to generate 3d objects, lights, cameras, geometries along with schema and UI configuration.

Check more here

Read the Viewer API guide for more details on classes provided by threepipe.

Using THREE. style

You can use the THREE. style code in Threepipe, but you need to import the necessary classes from threepipe instead of three.

With npm modules -

import * as THREE from 'threepipe';

With UMD modules -

<script>window.THREE = window.threepipe</script>

With import map -

<script async src="https://unpkg.com/[email protected]/dist/es-module-shims.js"></script>
<script type="importmap">
{
    "imports": {
        "three": "https://unpkg.com/threepipe/dist/index.mjs",
        "threepipe": "https://unpkg.com/threepipe/dist/index.mjs"
    }
}
</script>

Using packages that depend on three

Packages that depend on three and use the correct module resolution settings will work out of the box with threepipe.

Any modules that support newer versions of three.js should also work fine in most cases, but if you encounter issues with the npm modules, peerDependency version conflict etc, it is possible to override the three dependency, or set alias in rollup or vite config.

Overriding three module

Overriding in package.json -

{
  "overrides": {
    "three": "$three"
  }
}

If using vite, add a plugin to replace three import to threepipe in your vite.config.js(or rollup)

import {defineConfig} from 'vite'
import replace from '@rollup/plugin-replace';

export default defineConfig({
    plugins: [
        replace({
            'from \'three\'': 'from \'threepipe\'',
            'from \'three/examples/jsm/loaders/GLTFLoader.js\'': 'from \'threepipe\'',
            'from \'three/examples/jsm/postprocessing/Pass.js\'': 'from \'threepipe\'',
            'from \'three/examples/jsm/utils/BufferGeometryUtils.js\'': 'from \'threepipe\'',
            // add more that are being used
            
            // 'from \'three/examples/jsm/.*\'': 'from \'threepipe\'', // Note - regex doesnt work...
            delimiters: ['', ''],
            preventAssignment: true,
        }),
        replace({ // this is added to throw an error, in that case, add it to above
            'from \'three/': 'from \'unknown/',
            delimiters: ['', ''],
            preventAssignment: true,
        }),
    ]
})