Initial project import

node_modules/troika-three-utils/docs/BezierMesh.md

@@ -0,0 +1,57 @@
+# BezierMesh
+
+This is a Three.js object which bends a cylindrical mesh along a 3D cubic bezier path between two points. This is useful for drawing nicely curved lines in 3D space, where the lines have thickness.
+
+Rather than assembling a BufferGeometry on the CPU, BezierMesh bends the tube on the GPU in a custom derived vertex shader. This makes it very good for situations where the line's endpoints and control points change over time. They can even be animated every frame without penalty.
+
+It can also have any `material` assigned to it, so it can have lighting, textures, etc. like any other mesh. It will automatically upgrade that material behind the scenes to apply the extra vertex shader transformation. 
+
+- _[Source code with JSDoc](https://github.com/protectwise/troika/blob/master/packages/troika-three-utils/src/BezierMesh.js)_
+
+- _[Online example](https://troika-examples.netlify.com/#bezier3d)_
+
+  ![Example 1](../../../docs/troika-three-utils/images/beziers1.png)
+
+- _[Online example using InstancedUniformsMesh](https://ibyou.csb.app/)_
+
+  ![Example 2](../../../docs/troika-three-utils/images/beziers2.png)
+
+## Usage:
+
+```js
+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)
+```
+
+## Supported Properties:
+
+### `pointA`
+A Vector3 holding the position of the first endpoint.
+
+### `controlA`
+A Vector3 holding the position of the first control point.
+
+### `controlB`
+A Vector3 holding the position of the second control point.
+
+### `pointB`
+A Vector3 holding the position of the second endpoint.
+
+### `radius`
+A number defining the radius of the tube.
+
+### `dashArray`
+An array of two numbers, defining the length of "on" and "off" parts of a dashed line style. Each number is a 0-1 ratio of the entire path's length. (Actually this is the `t` length used as input to the cubic bezier function, not its visible length.)
+
+> Note that the dashes will appear like a hollow tube, not solid; this will be more apparent on thicker tubes.
+
+### `dashOffset`
+A numeric offset of where the dash starts. You can animate this to make the dashes move.
+

node_modules/troika-three-utils/docs/createDerivedMaterial.md

@@ -0,0 +1,49 @@
+# Three.js Derived Materials
+
+**How to use Troika's `createDerivedMaterial` utility to extend existing Three.js materials with custom shader code**
+
+_[Source code with JSDoc](https://github.com/protectwise/troika/blob/master/packages/troika-three-utils/src/DerivedMaterial.js)_
+
+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](https://threejs.org/docs/#api/en/materials/ShaderMaterial) but then you lose all the built-in features. The experimental [NodeMaterial](https://www.donmccurdy.com/2019/03/17/three-nodematerial-introduction/) seems promising but doesn't appear to be ready as a full replacement.
+
+The [onBeforeCompile](https://threejs.org/docs/#api/en/materials/Material.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 can be 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. 
+
+Lastly, you can create a derived material from _another derived material_, and so on. This enables composable patterns where you can piece in small bits of shader logic one at a time.
+
+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.
+
+```js
+import { createDerivedMaterial} from 'troika-three-utils'
+import { Mesh, MeshStandardMaterial, PlaneGeometry } from 'three'
+
+const baseMaterial = new MeshStandardMaterial({color: 0xffcc00})
+const customMaterial = createDerivedMaterial(
+  baseMaterial,
+  {
+    timeUniform: 'elapsed',
+    // Add GLSL to tweak the vertex... notice this modifies the `position`
+    // and `normal` attributes, which is normally not possible!
+    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 PlaneGeometry(1, 1, 64, 1),
+  customMaterial
+)
+
+// to enable directional light shadows:
+mesh.castShadow = true
+mesh.customDepthMaterial = customMaterial.getDepthMaterial()
+```
+
+You can also declare custom `uniforms` and `defines`, inject fragment shader code to modify the output color, etc. See the JSDoc in the [DerivedMaterial.js source code](https://github.com/protectwise/troika/blob/master/packages/troika-three-utils/src/DerivedMaterial.js) for full details.