@octanejs/drei 0.0.1

package/src/core/MarchingCubes.three.tsrx

@@ -0,0 +1,125 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame } from '@octanejs/three';
+import { useMemo, useRef, useState } from '@octanejs/three/renderer';
+import { createContext, useContext } from 'octane';
+import * as THREE from 'three';
+import { MarchingCubes as MarchingCubesImpl } from 'three-stdlib';
+
+type MarchingApi = { getParent(): { current: MarchingCubesImpl | null } };
+const MarchingContext = createContext<MarchingApi | null>(null);
+
+function assignRef<T>(ref: ThreeRef<T> | undefined, value: T | null): void {
+	if (Array.isArray(ref)) for (const item of ref) assignRef(item, value);
+	else if (typeof ref === 'function') ref(value);
+	else if (ref && 'current' in ref) ref.current = value;
+}
+
+export type MarchingCubesProps = {
+	resolution?: number;
+	maxPolyCount?: number;
+	enableUvs?: boolean;
+	enableColors?: boolean;
+} & Omit<ThreeElements['group'], 'ref'>;
+
+export function MarchingCubes({
+	resolution = 28,
+	maxPolyCount = 10000,
+	enableUvs = false,
+	enableColors = false,
+	children,
+	ref,
+	...props
+}: MarchingCubesProps & { ref?: ThreeRef<MarchingCubesImpl> }) @{
+	const marchingRef = useRef<MarchingCubesImpl | null>(null);
+	const marchingCubes = useMemo(() => {
+		const Constructor = MarchingCubesImpl as unknown as new (
+			resolution: number,
+			material: THREE.Material,
+			enableUvs: boolean,
+			enableColors: boolean,
+			maxPolyCount: number,
+		) => MarchingCubesImpl;
+		return new Constructor(resolution, null as unknown as THREE.Material, enableUvs, enableColors, maxPolyCount);
+	}, [resolution, maxPolyCount, enableUvs, enableColors]);
+	const api = useMemo<MarchingApi>(() => ({ getParent: () => marchingRef }), []);
+	const mergedRef = useMemo(
+		() => (value: MarchingCubesImpl | null) => { marchingRef.current = value; assignRef(ref, value); },
+		[ref],
+	);
+	useFrame(() => {
+		marchingCubes.update();
+		marchingCubes.reset();
+	}, -1);
+	<primitive object={marchingCubes} ref={mergedRef as any} {...props as any}>
+		<MarchingContext.Provider value={api}>{children}</MarchingContext.Provider>
+	</primitive>
+}
+
+export type MarchingCubeProps = {
+	strength?: number;
+	subtract?: number;
+	color?: THREE.Color;
+} & Omit<ThreeElements['group'], 'ref'>;
+
+export function MarchingCube({
+	strength = 0.5,
+	subtract = 12,
+	color,
+	ref,
+	...props
+}: MarchingCubeProps & { ref?: ThreeRef<THREE.Group> }) @{
+	const api = useContext(MarchingContext);
+	if (!api) throw new Error('MarchingCube must be used inside MarchingCubes.');
+	const parentRef = useMemo(() => api.getParent(), [api]);
+	const cubeRef = useRef<THREE.Group | null>(null);
+	const vector = new THREE.Vector3();
+	const mergedRef = useMemo(
+		() => (value: THREE.Group | null) => { cubeRef.current = value; assignRef(ref, value); },
+		[ref],
+	);
+	useFrame(() => {
+		if (!parentRef.current || !cubeRef.current) return;
+		cubeRef.current.getWorldPosition(vector);
+		parentRef.current.addBall(
+			0.5 + vector.x * 0.5,
+			0.5 + vector.y * 0.5,
+			0.5 + vector.z * 0.5,
+			strength,
+			subtract,
+			color as any,
+		);
+	});
+	<group ref={mergedRef} {...props} />
+}
+
+export type MarchingPlaneProps = {
+	planeType?: 'x' | 'y' | 'z';
+	strength?: number;
+	subtract?: number;
+} & Omit<ThreeElements['group'], 'ref'>;
+
+export function MarchingPlane({
+	planeType: requestedPlaneType = 'x',
+	strength = 0.5,
+	subtract = 12,
+	ref,
+	...props
+}: MarchingPlaneProps & { ref?: ThreeRef<THREE.Group> }) @{
+	const api = useContext(MarchingContext);
+	if (!api) throw new Error('MarchingPlane must be used inside MarchingCubes.');
+	const parentRef = useMemo(() => api.getParent(), [api]);
+	const wallRef = useRef<THREE.Group | null>(null);
+	const planeType = useMemo(
+		() => requestedPlaneType === 'x' ? 'addPlaneX' : requestedPlaneType === 'y' ? 'addPlaneY' : 'addPlaneZ',
+		[requestedPlaneType],
+	);
+	const mergedRef = useMemo(
+		() => (value: THREE.Group | null) => { wallRef.current = value; assignRef(ref, value); },
+		[ref],
+	);
+	useFrame(() => {
+		if (!parentRef.current || !wallRef.current) return;
+		parentRef.current[planeType](strength, subtract);
+	});
+	<group ref={mergedRef} {...props} />
+}

package/src/core/MeshPortalMaterial.three.tsrx

@@ -0,0 +1,103 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { extend, type ComputeFunction, type ThreeElements, type ThreeRef, useFrame, useInstanceHandle, useThree } from '@octanejs/three';
+import { useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, type RefObject } from '@octanejs/three/renderer';
+import type { OctaneNode } from 'octane';
+import * as THREE from 'three';
+import { FullScreenQuad } from 'three-stdlib';
+import { PortalMaterialImpl, type PortalMaterialInstance } from '../materials/PortalMaterial.js';
+import { makeSDFGenerator } from '../materials/makeSDFGenerator.js';
+import { useFBO } from './Fbo.three.tsrx';
+import { RenderTexture } from './RenderTexture.three.tsrx';
+import { useIntersect } from './useIntersect.three.tsrx';
+
+export type PortalProps = Omit<ThreeElements['shaderMaterial'], 'ref'> & {
+	blend?: number; blur?: number; resolution?: number; worldUnits?: boolean; eventPriority?: number;
+	renderPriority?: number; events?: boolean; children?: OctaneNode;
+};
+const PortalMaterialNode = extend(PortalMaterialImpl);
+
+export function MeshPortalMaterial({
+	children, events = undefined, blur = 0, eventPriority = 0, renderPriority = 0, worldUnits = false,
+	resolution = 512, ref: forwardedRef, ...props
+}: PortalProps & { ref?: ThreeRef<PortalMaterialInstance> }) @{
+	const ref = useRef<PortalMaterialInstance | null>(null);
+	const instance = useInstanceHandle(ref);
+	const { scene, gl, size, viewport, setEvents } = useThree();
+	const maskRenderTarget = useFBO(resolution, resolution);
+	const [priority, setPriority] = useState(0);
+	useFrame(() => {
+		const next = ref.current!.blend > 0 ? Math.max(1, renderPriority) : 0;
+		if (priority !== next) setPriority(next);
+	});
+	useEffect(() => { if (events !== undefined) setEvents({ enabled: !events }); }, [events]);
+	const [visible, setVisible] = useState(true);
+	const parent = useIntersect<THREE.Mesh<THREE.BufferGeometry>>(setVisible);
+	useLayoutEffect(() => { parent.current = instance.current?.parent?.object as THREE.Mesh<THREE.BufferGeometry> | null; }, []);
+	useLayoutEffect(() => {
+		if (!parent.current || !blur || ref.current!.sdf !== null) return;
+		const tempMesh = new THREE.Mesh(parent.current.geometry, new THREE.MeshBasicMaterial());
+		const boundingBox = new THREE.Box3().setFromBufferAttribute(tempMesh.geometry.attributes.position as THREE.BufferAttribute);
+		const orthoCam = new THREE.OrthographicCamera(
+			boundingBox.min.x * (1 + 2 / resolution), boundingBox.max.x * (1 + 2 / resolution),
+			boundingBox.max.y * (1 + 2 / resolution), boundingBox.min.y * (1 + 2 / resolution), 0.1, 1000,
+		);
+		orthoCam.position.set(0, 0, 1); orthoCam.lookAt(0, 0, 0);
+		gl.setRenderTarget(maskRenderTarget); (gl as any).render(tempMesh, orthoCam);
+		const sdf = makeSDFGenerator(resolution, resolution, gl as any)(maskRenderTarget.texture);
+		const readSdf = new Float32Array(resolution * resolution); gl.readRenderTargetPixels(sdf, 0, 0, resolution, resolution, readSdf);
+		let min = Infinity; for (let index = 0; index < readSdf.length; index++) if (readSdf[index] < min) min = readSdf[index];
+		ref.current!.size = -min; (ref.current as any).sdf = sdf.texture; gl.setRenderTarget(null);
+	}, [resolution, blur]);
+	useImperativeHandle((forwardedRef ?? null) as any, () => ref.current!);
+	const compute = useCallback<ComputeFunction>((event, state) => {
+		if (!parent.current) return false as any;
+		state.pointer.set((event.offsetX / state.size.width) * 2 - 1, -(event.offsetY / state.size.height) * 2 + 1);
+		state.raycaster.setFromCamera(state.pointer, state.camera);
+		if (ref.current?.blend === 0) {
+			const [intersection] = state.raycaster.intersectObject(parent.current);
+			if (!intersection) { (state.raycaster as any).camera = undefined; return false as any; }
+		}
+	}, []);
+	<PortalMaterialNode ref={ref} blur={blur} blend={0} resolution={[size.width * viewport.dpr, size.height * viewport.dpr]} attach="material" {...props as any}>
+		<RenderTexture attach="map" frames={visible ? Infinity : 0} eventPriority={eventPriority} renderPriority={renderPriority} compute={compute}>
+			{children}
+			<ManagePortalScene events={events} rootScene={scene} priority={priority} material={ref} parent={parent} worldUnits={worldUnits} />
+		</RenderTexture>
+	</PortalMaterialNode>
+}
+
+function ManagePortalScene({ events = undefined, rootScene, material, parent, priority, worldUnits }: {
+	events?: boolean; rootScene: THREE.Scene; material: RefObject<PortalMaterialInstance>; parent: RefObject<THREE.Mesh<THREE.BufferGeometry>>;
+	priority: number; worldUnits: boolean;
+}) @{
+	const scene = useThree((state) => state.scene); const setEvents = useThree((state) => state.setEvents);
+	const buffer1 = useFBO(); const buffer2 = useFBO();
+	useLayoutEffect(() => { scene.matrixAutoUpdate = false; }, []);
+	useEffect(() => { if (events !== undefined) setEvents({ enabled: events }); }, [events]);
+	const [quad, blend] = useMemo(() => {
+		const blend = { value: 0 };
+		const quad = new FullScreenQuad(new THREE.ShaderMaterial({
+			uniforms: { a: { value: buffer1.texture }, b: { value: buffer2.texture }, blend },
+			vertexShader: `varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
+			fragmentShader: `uniform sampler2D a; uniform sampler2D b; uniform float blend; varying vec2 vUv; #include <packing>
+				void main() { vec4 ta = texture2D(a, vUv); vec4 tb = texture2D(b, vUv); gl_FragColor = mix(tb, ta, blend); #include <tonemapping_fragment> #include <colorspace_fragment> }`,
+		}) as any);
+		return [quad, blend] as const;
+	}, []);
+	useFrame((state) => {
+		if (!parent.current) return;
+		if (!worldUnits) {
+			if (priority && material.current?.blend === 1) parent.current.updateWorldMatrix(true, false);
+			scene.matrixWorld.copy(parent.current.matrixWorld);
+		} else scene.matrixWorld.identity();
+		if (priority) {
+			if (material.current!.blend > 0 && material.current!.blend < 1) {
+				blend.value = material.current!.blend;
+				state.gl.setRenderTarget(buffer1); state.gl.render(scene, state.camera);
+				state.gl.setRenderTarget(buffer2); state.gl.render(rootScene, state.camera);
+				state.gl.setRenderTarget(null); quad.render(state.gl as any);
+			} else if (material.current!.blend === 1) state.gl.render(scene, state.camera);
+		}
+	}, priority);
+	null
+}

package/src/core/MeshReflectorMaterial.three.tsrx

@@ -0,0 +1,67 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { extend, type ThreeElements, type ThreeRef, useFrame, useInstanceHandle, useThree } from '@octanejs/three';
+import { useCallback, useImperativeHandle, useMemo, useRef, useState } from '@octanejs/three/renderer';
+import { DepthFormat, DepthTexture, HalfFloatType, LinearFilter, Matrix4, PerspectiveCamera, Plane, UnsignedShortType, Vector3, Vector4, WebGLRenderTarget, type Texture } from 'three';
+import { BlurPass } from '../materials/BlurPass.js';
+import { MeshReflectorMaterialImpl } from '../materials/MeshReflectorMaterial.js';
+
+const MeshReflectorMaterialNode = extend(MeshReflectorMaterialImpl);
+
+export type MeshReflectorMaterialProps = ThreeElements['meshStandardMaterial'] & {
+	resolution?: number; blur?: [number, number] | number; reflectorOffset?: number; mixBlur?: number; mixStrength?: number;
+	minDepthThreshold?: number; maxDepthThreshold?: number; depthScale?: number; depthToBlurRatioBias?: number; mirror?: number;
+	distortion?: number; distortionMap?: Texture; mixContrast?: number;
+};
+
+export function MeshReflectorMaterial({
+	mixBlur = 0, mixStrength = 1, resolution = 256, blur: blurInput = [0, 0], minDepthThreshold = 0.9,
+	maxDepthThreshold = 1, depthScale = 0, depthToBlurRatioBias = 0.25, mirror = 0, distortion = 1,
+	mixContrast = 1, distortionMap, reflectorOffset = 0, ref, ...props
+}: MeshReflectorMaterialProps & { ref?: ThreeRef<MeshReflectorMaterialImpl> }) @{
+	const gl = useThree((state) => state.gl); const camera = useThree((state) => state.camera); const scene = useThree((state) => state.scene);
+	const renderer = gl as any;
+	const blur = Array.isArray(blurInput) ? blurInput : [blurInput, blurInput];
+	const [blurX, blurY] = blur; const hasBlur = blurX + blurY > 0;
+	const materialRef = useRef<MeshReflectorMaterialImpl | null>(null); const instance = useInstanceHandle(materialRef);
+	useImperativeHandle((ref ?? null) as any, () => materialRef.current!, []);
+	const [reflectorPlane] = useState(() => new Plane()); const [normal] = useState(() => new Vector3());
+	const [reflectorWorldPosition] = useState(() => new Vector3()); const [cameraWorldPosition] = useState(() => new Vector3());
+	const [rotationMatrix] = useState(() => new Matrix4()); const [lookAtPosition] = useState(() => new Vector3(0, 0, -1));
+	const [clipPlane] = useState(() => new Vector4()); const [view] = useState(() => new Vector3()); const [target] = useState(() => new Vector3());
+	const [q] = useState(() => new Vector4()); const [textureMatrix] = useState(() => new Matrix4()); const [virtualCamera] = useState(() => new PerspectiveCamera());
+	const beforeRender = useCallback(() => {
+		const parent = instance.current?.parent?.object as any; if (!parent) return;
+		reflectorWorldPosition.setFromMatrixPosition(parent.matrixWorld); cameraWorldPosition.setFromMatrixPosition(camera.matrixWorld);
+		rotationMatrix.extractRotation(parent.matrixWorld); normal.set(0, 0, 1).applyMatrix4(rotationMatrix);
+		reflectorWorldPosition.addScaledVector(normal, reflectorOffset); view.subVectors(reflectorWorldPosition, cameraWorldPosition);
+		if (view.dot(normal) > 0) return;
+		view.reflect(normal).negate().add(reflectorWorldPosition); rotationMatrix.extractRotation(camera.matrixWorld);
+		lookAtPosition.set(0, 0, -1).applyMatrix4(rotationMatrix).add(cameraWorldPosition);
+		target.subVectors(reflectorWorldPosition, lookAtPosition).reflect(normal).negate().add(reflectorWorldPosition);
+		virtualCamera.position.copy(view); virtualCamera.up.set(0, 1, 0).applyMatrix4(rotationMatrix).reflect(normal);
+		virtualCamera.lookAt(target); virtualCamera.far = camera.far; virtualCamera.updateMatrixWorld(); virtualCamera.projectionMatrix.copy(camera.projectionMatrix);
+		textureMatrix.set(0.5,0,0,0.5, 0,0.5,0,0.5, 0,0,0.5,0.5, 0,0,0,1).multiply(virtualCamera.projectionMatrix).multiply(virtualCamera.matrixWorldInverse).multiply(parent.matrixWorld);
+		reflectorPlane.setFromNormalAndCoplanarPoint(normal, reflectorWorldPosition).applyMatrix4(virtualCamera.matrixWorldInverse);
+		clipPlane.set(reflectorPlane.normal.x, reflectorPlane.normal.y, reflectorPlane.normal.z, reflectorPlane.constant);
+		const projection = virtualCamera.projectionMatrix;
+		q.x = (Math.sign(clipPlane.x) + projection.elements[8]!) / projection.elements[0]!; q.y = (Math.sign(clipPlane.y) + projection.elements[9]!) / projection.elements[5]!;
+		q.z = -1; q.w = (1 + projection.elements[10]!) / projection.elements[14]!; clipPlane.multiplyScalar(2 / clipPlane.dot(q));
+		projection.elements[2] = clipPlane.x; projection.elements[6] = clipPlane.y; projection.elements[10] = clipPlane.z + 1; projection.elements[14] = clipPlane.w;
+	}, [camera, reflectorOffset]);
+	const [fbo1, fbo2, blurpass, reflectorProps] = useMemo(() => {
+		const parameters = { minFilter: LinearFilter, magFilter: LinearFilter, type: HalfFloatType };
+		const first = new WebGLRenderTarget(resolution, resolution, parameters); first.depthBuffer = true;
+		first.depthTexture = new DepthTexture(resolution, resolution); first.depthTexture.format = DepthFormat; first.depthTexture.type = UnsignedShortType;
+		const second = new WebGLRenderTarget(resolution, resolution, parameters);
+		const pass = new BlurPass({ gl: renderer, resolution, width: blurX, height: blurY, minDepthThreshold, maxDepthThreshold, depthScale, depthToBlurRatioBias });
+		return [first, second, pass, { mirror, textureMatrix, mixBlur, tDiffuse: first.texture, tDepth: first.depthTexture, tDiffuseBlur: second.texture, hasBlur, mixStrength, minDepthThreshold, maxDepthThreshold, depthScale, depthToBlurRatioBias, distortion, distortionMap, mixContrast,
+			'defines-USE_BLUR': hasBlur ? '' : undefined, 'defines-USE_DEPTH': depthScale > 0 ? '' : undefined, 'defines-USE_DISTORTION': distortionMap ? '' : undefined } as const];
+	}, [gl, blurX, blurY, textureMatrix, resolution, mirror, hasBlur, mixBlur, mixStrength, minDepthThreshold, maxDepthThreshold, depthScale, depthToBlurRatioBias, distortion, distortionMap, mixContrast]);
+	useFrame(() => {
+		const parent = instance.current?.parent?.object as any; if (!parent) return;
+		parent.visible = false; const xr = renderer.xr.enabled; const shadow = renderer.shadowMap.autoUpdate; beforeRender(); renderer.xr.enabled = false; renderer.shadowMap.autoUpdate = false;
+		renderer.setRenderTarget(fbo1); renderer.state.buffers.depth.setMask(true); if (!renderer.autoClear) renderer.clear(); renderer.render(scene, virtualCamera);
+		if (hasBlur) blurpass.render(renderer, fbo1, fbo2); renderer.xr.enabled = xr; renderer.shadowMap.autoUpdate = shadow; parent.visible = true; renderer.setRenderTarget(null);
+	});
+	<MeshReflectorMaterialNode attach="material" key={`key${reflectorProps['defines-USE_BLUR']}${reflectorProps['defines-USE_DEPTH']}${reflectorProps['defines-USE_DISTORTION']}`} ref={materialRef} {...(reflectorProps as any)} {...(props as any)} />
+}

package/src/core/MeshRefractionMaterial.three.tsrx

@@ -0,0 +1,70 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { extend, type ThreeElements, useFrame, useInstanceHandle, useThree } from '@octanejs/three';
+import { useLayoutEffect, useMemo, useRef } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { MeshBVH, MeshBVHUniformStruct, SAH } from 'three-mesh-bvh';
+import { MeshRefractionMaterialImpl } from '../materials/MeshRefractionMaterial.js';
+
+const MeshRefractionMaterialNode = extend(MeshRefractionMaterialImpl);
+
+export type MeshRefractionMaterialProps = ThreeElements['shaderMaterial'] & {
+	envMap: THREE.CubeTexture | THREE.Texture;
+	bounces?: number;
+	ior?: number;
+	fresnel?: number;
+	aberrationStrength?: number;
+	color?: THREE.ColorRepresentation;
+	fastChroma?: boolean;
+};
+
+const isCubeTexture = (texture: THREE.CubeTexture | THREE.Texture): texture is THREE.CubeTexture =>
+	Boolean((texture as THREE.CubeTexture).isCubeTexture);
+
+export function MeshRefractionMaterial({
+	aberrationStrength = 0,
+	fastChroma = true,
+	envMap,
+	...props
+}: MeshRefractionMaterialProps) @{
+	const material = useRef<InstanceType<typeof MeshRefractionMaterialImpl> | null>(null);
+	const instance = useInstanceHandle(material);
+	const size = useThree((state) => state.size);
+	const defines = useMemo(() => {
+		const result: Record<string, string> = {};
+		const cubeMap = isCubeTexture(envMap);
+		const image = cubeMap ? envMap.image[0] : envMap.image;
+		const width = image?.width ?? 1024;
+		const cubeSize = width / 4;
+		const lodMax = Math.floor(Math.log2(cubeSize));
+		const normalizedCubeSize = Math.pow(2, lodMax);
+		const packedWidth = 3 * Math.max(normalizedCubeSize, 16 * 7);
+		const packedHeight = 4 * normalizedCubeSize;
+		if (cubeMap) result.ENVMAP_TYPE_CUBEM = '';
+		result.CUBEUV_TEXEL_WIDTH = `${1 / packedWidth}`;
+		result.CUBEUV_TEXEL_HEIGHT = `${1 / packedHeight}`;
+		result.CUBEUV_MAX_MIP = `${lodMax}.0`;
+		if (aberrationStrength > 0) result.CHROMATIC_ABERRATIONS = '';
+		if (fastChroma) result.FAST_CHROMA = '';
+		return result;
+	}, [aberrationStrength, fastChroma]);
+	useLayoutEffect(() => {
+		const geometry = (instance.current?.parent?.object as THREE.Mesh | undefined)?.geometry;
+		if (!geometry || !material.current) return;
+		material.current.bvh = new MeshBVHUniformStruct();
+		material.current.bvh.updateFrom(new MeshBVH(geometry.clone().toNonIndexed() as any, { strategy: SAH }));
+	}, []);
+	useFrame(({ camera }) => {
+		if (!material.current) return;
+		material.current.viewMatrixInverse = camera.matrixWorld;
+		material.current.projectionMatrixInverse = camera.projectionMatrixInverse;
+	});
+	<MeshRefractionMaterialNode
+		key={JSON.stringify(defines)}
+		defines={defines}
+		ref={material}
+		resolution={[size.width, size.height]}
+		aberrationStrength={aberrationStrength}
+		envMap={envMap}
+		{...(props as any)}
+	/>
+}

package/src/core/MeshTransmissionMaterial.three.tsrx

@@ -0,0 +1,71 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { extend, type ThreeElements, type ThreeRef, useFrame, useInstanceHandle } from '@octanejs/three';
+import { useImperativeHandle, useRef, useState } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { MeshTransmissionMaterialImpl } from '../materials/MeshTransmissionMaterial.js';
+import { useFBO } from './Fbo.three.tsrx';
+import { DiscardMaterialImpl } from './simple-materials.three.tsrx';
+
+type MeshTransmissionMaterialType = Omit<ThreeElements['meshPhysicalMaterial'], 'args' | 'roughness' | 'thickness' | 'transmission'> & {
+	transmission?: number; thickness?: number; roughness?: number; chromaticAberration?: number; anisotropy?: number;
+	anisotropicBlur?: number; distortion?: number; distortionScale?: number; temporalDistortion?: number;
+	buffer?: THREE.Texture; time?: number; args?: [samples: number, transmissionSampler: boolean];
+};
+
+export type MeshTransmissionMaterialProps = Omit<MeshTransmissionMaterialType, 'ref' | 'args'> & {
+	transmissionSampler?: boolean; backside?: boolean; backsideThickness?: number; backsideEnvMapIntensity?: number;
+	resolution?: number; backsideResolution?: number; samples?: number; background?: THREE.Texture | THREE.Color;
+};
+
+type MaterialInstance = MeshTransmissionMaterialImpl & {
+	time: number; buffer: THREE.Texture; _transmission: number; anisotropicBlur: number; chromaticAberration: number;
+	distortion: number; distortionScale: number; temporalDistortion: number;
+};
+const MeshTransmissionMaterialNode = extend(MeshTransmissionMaterialImpl);
+
+export function MeshTransmissionMaterial({
+	buffer, transmissionSampler = false, backside = false, side = THREE.FrontSide, transmission = 1, thickness = 0,
+	backsideThickness = 0, backsideEnvMapIntensity = 1, samples = 10, resolution, backsideResolution, background,
+	anisotropy, anisotropicBlur, ref: forwardedRef, ...props
+}: MeshTransmissionMaterialProps & { ref?: ThreeRef<MaterialInstance> }) @{
+	const ref = useRef<MaterialInstance | null>(null);
+	const instance = useInstanceHandle(ref);
+	const [discardMaterial] = useState(() => new DiscardMaterialImpl());
+	const fboBack = useFBO(backsideResolution || resolution);
+	const fboMain = useFBO(resolution);
+	useFrame((state) => {
+		ref.current!.time = state.clock.elapsedTime;
+		if (ref.current!.buffer !== fboMain.texture || transmissionSampler) return;
+		const parent = instance.current?.parent?.object as THREE.Mesh<THREE.BufferGeometry, MaterialInstance | THREE.ShaderMaterial> | undefined;
+		if (!parent) return;
+		const oldTone = state.gl.toneMapping;
+		const oldBackground = state.scene.background;
+		const oldEnvMapIntensity = ref.current!.envMapIntensity;
+		state.gl.toneMapping = THREE.NoToneMapping;
+		if (background) state.scene.background = background;
+		parent.material = discardMaterial;
+		if (backside) {
+			state.gl.setRenderTarget(fboBack); state.gl.render(state.scene, state.camera);
+			parent.material = ref.current!; ref.current!.buffer = fboBack.texture; ref.current!.thickness = backsideThickness;
+			ref.current!.side = THREE.BackSide; ref.current!.envMapIntensity = backsideEnvMapIntensity;
+		}
+		state.gl.setRenderTarget(fboMain); state.gl.render(state.scene, state.camera);
+		parent.material = ref.current!; ref.current!.thickness = thickness; ref.current!.side = side;
+		ref.current!.buffer = fboMain.texture; ref.current!.envMapIntensity = oldEnvMapIntensity;
+		state.scene.background = oldBackground; state.gl.setRenderTarget(null); state.gl.toneMapping = oldTone;
+	});
+	useImperativeHandle((forwardedRef ?? null) as any, () => ref.current!, [samples, transmissionSampler]);
+	<MeshTransmissionMaterialNode
+		attach="material"
+		key={`${samples}:${transmissionSampler}`}
+		args={[samples, transmissionSampler]}
+		ref={ref}
+		{...(props as any)}
+		buffer={(buffer || fboMain.texture) as any}
+		_transmission={transmission}
+		anisotropicBlur={anisotropicBlur ?? anisotropy}
+		transmission={transmissionSampler ? transmission : 0}
+		thickness={thickness}
+		side={side}
+	/>
+}

package/src/core/MotionPathControls.three.tsrx

@@ -0,0 +1,139 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame, useInstanceHandle, useThree } from '@octanejs/three';
+import { useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, type RefObject } from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import { easing, misc } from 'maath';
+import * as THREE from 'three';
+
+export type MotionPathProps = ThreeElements['group'] & {
+	curves?: THREE.Curve<THREE.Vector3>[];
+	debug?: boolean;
+	debugColor?: THREE.ColorRepresentation;
+	object?: RefObject<THREE.Object3D>;
+	focus?: [x: number, y: number, z: number] | RefObject<THREE.Object3D>;
+	loop?: boolean;
+	offset?: number;
+	smooth?: boolean | number;
+	eps?: number;
+	damping?: number;
+	focusDamping?: number;
+	maxSpeed?: number;
+	children?: OctaneNode;
+};
+
+type MotionState = {
+	current: number;
+	path: THREE.CurvePath<THREE.Vector3>;
+	focus: RefObject<THREE.Object3D> | [number, number, number] | undefined;
+	object: RefObject<THREE.Object3D>;
+	offset: number;
+	point: THREE.Vector3;
+	tangent: THREE.Vector3;
+	next: THREE.Vector3;
+};
+
+export type MotionPathRef = THREE.Group & { motion: MotionState };
+
+function isObject3DRef(ref: unknown): ref is RefObject<THREE.Object3D> {
+	return (ref as RefObject<THREE.Object3D> | undefined)?.current instanceof THREE.Object3D;
+}
+
+const MotionContext = createContext<MotionState>(null!);
+
+export function useMotion() {
+	const context = useContext(MotionContext);
+	if (!context) throw new Error('useMotion hook must be used in a MotionPathControls component.');
+	return context;
+}
+
+function Debug({ points = 50, color = 'black' }: { points?: number; color?: THREE.ColorRepresentation }) @{
+	const { path } = useMotion();
+	const [dots, setDots] = useState<THREE.Vector3[]>([]);
+	const material = useMemo(() => new THREE.MeshBasicMaterial({ color }), [color]);
+	const geometry = useMemo(() => new THREE.SphereGeometry(0.025, 16, 16), []);
+	const last = useRef<THREE.Curve<THREE.Vector3>[]>([]);
+	useEffect(() => {
+		if (path.curves !== last.current) {
+			setDots(path.getPoints(points));
+			last.current = path.curves;
+		}
+	});
+	<>
+		@for (const dot of dots; key dots.indexOf(dot)) {
+			<mesh material={material} geometry={geometry} position={[dot.x, dot.y, dot.z]} />
+		}
+	</>
+}
+
+export function MotionPathControls({
+	children,
+	curves = [],
+	debug = false,
+	debugColor = 'black',
+	object,
+	focus,
+	loop = true,
+	offset,
+	smooth = false,
+	eps = 0.00001,
+	damping = 0.1,
+	focusDamping = 0.1,
+	maxSpeed = Infinity,
+	ref,
+	...props
+}: MotionPathProps & { ref?: ThreeRef<MotionPathRef> }) @{
+	const { camera } = useThree();
+	const group = useRef<MotionPathRef | null>(null);
+	const position = useRef(offset ?? 0);
+	const path = useMemo(() => new THREE.CurvePath<THREE.Vector3>(), []);
+	const state = useMemo<MotionState>(() => ({
+		focus,
+		object: isObject3DRef(object) ? object : { current: camera },
+		path,
+		current: position.current,
+		offset: position.current,
+		point: new THREE.Vector3(),
+		tangent: new THREE.Vector3(),
+		next: new THREE.Vector3(),
+	}), [focus, object]);
+	const instance = useInstanceHandle(group as any);
+	useLayoutEffect(() => {
+		path.curves = [];
+		const nextCurves = curves.length > 0
+			? curves
+			: instance.current!.children.map((child) => child.object as unknown as THREE.Curve<THREE.Vector3>);
+		for (const curve of nextCurves) path.add(curve);
+		if (smooth) {
+			const points = path.getPoints(typeof smooth === 'number' ? smooth : 1);
+			path.curves = [new THREE.CatmullRomCurve3(points)];
+		}
+		path.updateArcLengths();
+	});
+	useImperativeHandle((ref ?? null) as any, () => Object.assign(group.current!, { motion: state }), [state]);
+	useLayoutEffect(() => {
+		position.current = misc.repeat(position.current, 1);
+	}, [offset]);
+	const vector = useMemo(() => new THREE.Vector3(), []);
+	useFrame((_frameState, delta) => {
+		const lastOffset = state.offset;
+		easing.damp(position, 'current', offset !== undefined ? offset : state.current, damping, delta, maxSpeed, undefined, eps);
+		state.offset = loop ? misc.repeat(position.current, 1) : misc.clamp(position.current, 0, 1);
+		if (path.getCurveLengths().length === 0) return;
+		path.getPointAt(state.offset, state.point);
+		path.getTangentAt(state.offset, state.tangent).normalize();
+		path.getPointAt(misc.repeat(position.current - (lastOffset - state.offset), 1), state.next);
+		const target = isObject3DRef(object) ? object.current! : camera;
+		target.position.copy(state.point);
+		if (focus) {
+			easing.dampLookAt(target, isObject3DRef(focus) ? focus.current!.getWorldPosition(vector) : focus, focusDamping, delta, maxSpeed, undefined, eps);
+		}
+	});
+	<group ref={group as any} {...props}>
+		<MotionContext.Provider value={state}>
+			{children}
+			@if (debug) {
+				<Debug color={debugColor} />
+			}
+		</MotionContext.Provider>
+	</group>
+}

package/src/core/MultiMaterial.three.tsrx

@@ -0,0 +1,32 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, useInstanceHandle } from '@octanejs/three';
+import { useLayoutEffect, useRef } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+
+export type MultiMaterialProps = Omit<ThreeElements['group'], 'ref'>;
+
+export function MultiMaterial(props: MultiMaterialProps) @{
+	const group = useRef<THREE.Group | null>(null);
+	const instance = useInstanceHandle(group);
+	useLayoutEffect(() => {
+		const parent = group.current?.parent as THREE.Mesh<
+			THREE.BufferGeometry,
+			THREE.Material[]
+		> | undefined;
+		const geometry = parent?.geometry;
+		if (!parent || !geometry || !instance.current) return;
+		const oldMaterial = parent.material;
+		parent.material = instance.current.children.map((child) => child.object as THREE.Material);
+		const oldGroups = [...geometry.groups];
+		geometry.clearGroups();
+		parent.material.forEach((material, index) => {
+			if (index < parent.material.length - 1) material.depthWrite = false;
+			geometry.addGroup(0, Infinity, index);
+		});
+		return () => {
+			parent.material = oldMaterial;
+			geometry.groups = oldGroups;
+		};
+	});
+	<group ref={group} {...props} />
+}