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 r158, and is regularly updated with new features and bug fixes.

Importing three.js objects

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';

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

If you are using packages that depend on three, override in package.json to use threepipe as the three dependency.

{
  "dependencies": {
    "three": "./node_modules/threepipe/",
    "threepipe": "^0.0.52"
  },
  "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,
        }),
    ]
})