@octanejs/drei 0.0.1

package/src/core/Cloud.three.tsrx

@@ -0,0 +1,314 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import {
+	applyProps,
+	extend,
+	type Color as ColorProp,
+	type ThreeElements,
+	type ThreeRef,
+	type Vector3 as Vector3Prop,
+	useFrame,
+} from '@octanejs/three';
+import {
+	useId,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@octanejs/three/renderer';
+import { createContext, type OctaneNode, useContext } from 'octane';
+import {
+	BufferAttribute,
+	Color,
+	DynamicDrawUsage,
+	Group,
+	InstancedMesh,
+	Material,
+	Matrix4,
+	MeshLambertMaterial,
+	Quaternion,
+	REVISION,
+	type Texture,
+	Vector3,
+} from 'three';
+import { useTexture } from './Texture.three.tsrx';
+
+const CLOUD_URL = 'https://rawcdn.githack.com/pmndrs/drei-assets/9225a9f1fbd449d9411125c2f419b843d0308c9f/cloud.png';
+
+type CloudState = {
+	uuid: string;
+	index: number;
+	segments: number;
+	dist: number;
+	matrix: Matrix4;
+	bounds: Vector3;
+	position: Vector3;
+	volume: number;
+	length: number;
+	ref: { current: Group | null };
+	speed: number;
+	growth: number;
+	opacity: number;
+	fade: number;
+	density: number;
+	rotation: number;
+	rotationFactor: number;
+	color: Color;
+};
+
+export type CloudsProps = Omit<ThreeElements['group'], 'ref'> & {
+	texture?: string;
+	limit?: number;
+	range?: number;
+	material?: typeof Material;
+	frustumCulled?: boolean;
+	children?: OctaneNode;
+};
+
+export type CloudProps = Omit<ThreeElements['group'], 'ref'> & {
+	seed?: number;
+	segments?: number;
+	bounds?: Vector3Prop;
+	concentrate?: 'random' | 'inside' | 'outside';
+	scale?: Vector3Prop;
+	volume?: number;
+	smallestVolume?: number;
+	distribute?: ((cloud: CloudState, index: number) => { point: Vector3; volume?: number }) | null;
+	growth?: number;
+	speed?: number;
+	fade?: number;
+	opacity?: number;
+	color?: ColorProp;
+};
+
+const parentMatrix = new Matrix4();
+const translation = new Vector3();
+const rotation = new Quaternion();
+const cameraPosition = new Vector3();
+const cameraQuaternion = new Quaternion();
+const workScale = new Vector3();
+const CloudsContext = createContext<{ current: CloudState[] } | 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 function Clouds({
+	children,
+	material = MeshLambertMaterial,
+	texture = CLOUD_URL,
+	range,
+	limit = 200,
+	frustumCulled,
+	ref,
+	...props
+}: CloudsProps & { ref?: ThreeRef<Group> }) @{
+	const CloudMaterialElement = useMemo(() => {
+		const CloudMaterial = class extends (material as typeof MeshLambertMaterial) {
+			constructor() {
+				super();
+				const opaqueFragment = Number.parseInt(REVISION.replace(/\D+/g, ''), 10) >= 154
+					? 'opaque_fragment'
+					: 'output_fragment';
+				this.onBeforeCompile = (shader) => {
+					shader.vertexShader = `attribute float cloudOpacity;
+               varying float vOpacity;
+              ` + shader.vertexShader.replace(
+						'#include <fog_vertex>',
+						`#include <fog_vertex>
+                 vOpacity = cloudOpacity;
+                `,
+					);
+					shader.fragmentShader = `varying float vOpacity;
+              ` + shader.fragmentShader.replace(
+						`#include <${opaqueFragment}>`,
+						`#include <${opaqueFragment}>
+                 gl_FragColor = vec4(outgoingLight, diffuseColor.a * vOpacity);
+                `,
+					);
+				};
+			}
+		};
+		return extend(CloudMaterial);
+	}, [material]);
+	const instance = useRef<InstancedMesh | null>(null);
+	const [clouds] = useState<CloudState[]>([]);
+	const cloudsRef = useMemo(() => ({ current: clouds }), [clouds]);
+	const opacities = useMemo(() => Float32Array.from({ length: limit }, () => 1), [limit]);
+	const colors = useMemo(() => Float32Array.from({ length: limit * 3 }, () => 1), [limit]);
+	const cloudTexture = useTexture(texture, undefined) as Texture;
+	const quaternion = new Quaternion();
+	const direction = new Vector3(0, 0, 1);
+	const position = new Vector3();
+	const mergedRef = useMemo(
+		() => (value: Group | null) => assignRef(ref, value),
+		[ref],
+	);
+
+	useFrame((state, delta) => {
+		const mesh = instance.current;
+		if (!mesh) return;
+		parentMatrix.copy(mesh.matrixWorld).invert();
+		state.camera.matrixWorld.decompose(cameraPosition, cameraQuaternion, workScale);
+		for (const config of clouds) {
+			if (!config.ref.current) continue;
+			config.ref.current.matrixWorld.decompose(translation, rotation, workScale);
+			translation.add(position.copy(config.position).applyQuaternion(rotation).multiply(workScale));
+			rotation.copy(cameraQuaternion).multiply(
+				quaternion.setFromAxisAngle(direction, (config.rotation += delta * config.rotationFactor)),
+			);
+			workScale.multiplyScalar(
+				config.volume + ((1 + Math.sin(state.clock.elapsedTime * config.density * config.speed)) / 2) * config.growth,
+			);
+			config.matrix.compose(translation, rotation, workScale).premultiply(parentMatrix);
+			config.dist = translation.distanceTo(cameraPosition);
+		}
+		clouds.sort((left, right) => right.dist - left.dist);
+		for (let index = 0; index < clouds.length; index++) {
+			const config = clouds[index]!;
+			opacities[index] = config.opacity * (config.dist < config.fade - 1 ? config.dist / config.fade : 1);
+			mesh.setMatrixAt(index, config.matrix);
+			mesh.setColorAt(index, config.color);
+		}
+		mesh.geometry.attributes.cloudOpacity!.needsUpdate = true;
+		mesh.instanceMatrix.needsUpdate = true;
+		if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+	});
+
+	useLayoutEffect(() => {
+		const mesh = instance.current;
+		if (!mesh) return;
+		const count = Math.min(limit, range ?? limit, clouds.length);
+		mesh.count = count;
+		mesh.instanceMatrix.updateRanges[0] = { start: 0, count: count * 16 };
+		if (mesh.instanceColor) mesh.instanceColor.updateRanges[0] = { start: 0, count: count * 3 };
+		(mesh.geometry.attributes.cloudOpacity as BufferAttribute).updateRanges[0] = { start: 0, count };
+	});
+
+	let imageBounds = [cloudTexture.image?.width ?? 1, cloudTexture.image?.height ?? 1];
+	const maximum = Math.max(imageBounds[0]!, imageBounds[1]!);
+	imageBounds = [imageBounds[0]! / maximum, imageBounds[1]! / maximum];
+	<group ref={mergedRef} {...props}>
+		<CloudsContext.Provider value={cloudsRef}>
+			{children}
+			<instancedMesh
+				matrixAutoUpdate={false}
+				ref={instance}
+				args={[null as any, null as any, limit]}
+				frustumCulled={frustumCulled}
+			>
+				<instancedBufferAttribute usage={DynamicDrawUsage} attach="instanceColor" args={[colors, 3]} />
+				<planeGeometry args={imageBounds as [number, number]}>
+					<instancedBufferAttribute usage={DynamicDrawUsage} attach="attributes-cloudOpacity" args={[opacities, 1]} />
+				</planeGeometry>
+				<CloudMaterialElement map={cloudTexture} transparent={true} depthWrite={false} />
+			</instancedMesh>
+		</CloudsContext.Provider>
+	</group>
+}
+
+export function CloudInstance({
+	opacity = 1,
+	speed = 0,
+	bounds = [5, 1, 1],
+	segments = 20,
+	color = '#ffffff',
+	fade = 10,
+	volume = 6,
+	smallestVolume = 0.25,
+	distribute = null,
+	growth = 4,
+	concentrate = 'inside',
+	seed = Math.random(),
+	ref,
+	...props
+}: CloudProps & { ref?: ThreeRef<Group> }) @{
+	const random = () => {
+		const value = Math.sin(seed++) * 10000;
+		return value - Math.floor(value);
+	};
+	const parent = useContext(CloudsContext);
+	if (!parent) throw new Error('CloudInstance must be used inside Clouds component.');
+	const group = useRef<Group | null>(null);
+	const uuid = useId();
+	const clouds = useMemo<CloudState[]>(() => Array.from({ length: segments }, (_, index) => ({
+		segments,
+		bounds: new Vector3(1, 1, 1),
+		position: new Vector3(),
+		uuid,
+		index,
+		ref: group,
+		dist: 0,
+		matrix: new Matrix4(),
+		color: new Color(),
+		rotation: index * (Math.PI / segments),
+		volume: 0,
+		length: 0,
+		speed: 0,
+		growth: 0,
+		opacity: 0,
+		fade: 0,
+		density: 0,
+		rotationFactor: 0,
+	})), [segments, uuid]);
+	const mergedRef = useMemo(
+		() => (value: Group | null) => { group.current = value; assignRef(ref, value); },
+		[ref],
+	);
+
+	useLayoutEffect(() => {
+		for (let index = 0; index < clouds.length; index++) {
+			const cloud = clouds[index]!;
+			applyProps(cloud as any, {
+				volume,
+				color,
+				speed,
+				growth,
+				opacity,
+				fade,
+				bounds,
+				density: Math.max(0.5, random()),
+				rotationFactor: Math.max(0.2, 0.5 * random()) * speed,
+			});
+			const distributed = distribute?.(cloud, index);
+			if (distributed || segments > 1) {
+				cloud.position.copy(cloud.bounds).multiply(distributed?.point ?? new Vector3(
+					random() * 2 - 1,
+					random() * 2 - 1,
+					random() * 2 - 1,
+				));
+			}
+			const xDifference = Math.abs(cloud.position.x);
+			const yDifference = Math.abs(cloud.position.y);
+			const zDifference = Math.abs(cloud.position.z);
+			const maximum = Math.max(xDifference, yDifference, zDifference);
+			cloud.length = 1;
+			if (xDifference === maximum) cloud.length -= xDifference / cloud.bounds.x;
+			if (yDifference === maximum) cloud.length -= yDifference / cloud.bounds.y;
+			if (zDifference === maximum) cloud.length -= zDifference / cloud.bounds.z;
+			cloud.volume = (distributed?.volume !== undefined
+				? distributed.volume
+				: Math.max(
+					Math.max(0, smallestVolume),
+					concentrate === 'random' ? random() : concentrate === 'inside' ? cloud.length : 1 - cloud.length,
+				)) * volume;
+		}
+	}, [concentrate, bounds, fade, color, opacity, growth, volume, seed, segments, speed]);
+	useLayoutEffect(() => {
+		parent.current.push(...clouds);
+		return () => {
+			parent.current = parent.current.filter((item) => item.uuid !== uuid);
+		};
+	}, [clouds, parent, uuid]);
+	<group ref={mergedRef} {...props} />
+}
+
+export function Cloud(props: CloudProps & { ref?: ThreeRef<Group> }) @{
+	const parent = useContext(CloudsContext);
+	@if (parent) {
+		<CloudInstance {...props} />
+	} @else {
+		<Clouds><CloudInstance {...props} /></Clouds>
+	}
+}

package/src/core/ComputedAttribute.three.tsrx

@@ -0,0 +1,27 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, useInstanceHandle } from '@octanejs/three';
+import { useLayoutEffect, useRef, useState } from '@octanejs/three/renderer';
+import { BufferAttribute, type BufferGeometry } from 'three';
+
+export type ComputedAttributeProps =
+	Omit<ThreeElements['bufferAttribute'], 'args'> & {
+		compute: (geometry: BufferGeometry) => BufferAttribute;
+		name: string;
+	};
+
+export function ComputedAttribute({ compute, name, ...props }: ComputedAttributeProps) @{
+	const [bufferAttribute] = useState(() => new BufferAttribute(new Float32Array(0), 1));
+	const primitive = useRef<BufferAttribute | null>(null);
+	const instance = useInstanceHandle(primitive);
+	useLayoutEffect(() => {
+		if (primitive.current && instance.current?.parent?.object) {
+			primitive.current.copy(compute(instance.current.parent.object as BufferGeometry));
+		}
+	}, [compute]);
+	<primitive
+		ref={primitive}
+		object={bufferAttribute}
+		attach={`attributes-${name}`}
+		{...props as any}
+	/>
+}

package/src/core/ContactShadows.three.tsrx

@@ -0,0 +1,106 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame, useThree } from '@octanejs/three';
+import { useImperativeHandle, useMemo, useRef } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { HorizontalBlurShader, VerticalBlurShader } from 'three-stdlib';
+
+export type ContactShadowsProps = Omit<ThreeElements['group'], 'ref' | 'scale'> & {
+	opacity?: number;
+	width?: number;
+	height?: number;
+	blur?: number;
+	near?: number;
+	far?: number;
+	smooth?: boolean;
+	resolution?: number;
+	frames?: number;
+	scale?: number | [x: number, y: number];
+	color?: THREE.ColorRepresentation;
+	depthWrite?: boolean;
+};
+
+export function ContactShadows({
+	scale = 10,
+	frames = Infinity,
+	opacity = 1,
+	width: widthFactor = 1,
+	height: heightFactor = 1,
+	blur = 1,
+	near = 0,
+	far = 10,
+	resolution = 512,
+	smooth = true,
+	color = '#000000',
+	depthWrite = false,
+	renderOrder,
+	ref,
+	...props
+}: ContactShadowsProps & { ref?: ThreeRef<THREE.Group> }) @{
+	const group = useRef<THREE.Group | null>(null);
+	const scene = useThree((state) => state.scene);
+	const gl = useThree((state) => state.gl);
+	const shadowCamera = useRef<THREE.OrthographicCamera | null>(null);
+	const width = widthFactor * (Array.isArray(scale) ? scale[0] : scale || 1);
+	const height = heightFactor * (Array.isArray(scale) ? scale[1] : scale || 1);
+	const resources = useMemo(() => {
+		const renderTarget = new THREE.WebGLRenderTarget(resolution, resolution);
+		const renderTargetBlur = new THREE.WebGLRenderTarget(resolution, resolution);
+		renderTargetBlur.texture.generateMipmaps = renderTarget.texture.generateMipmaps = false;
+		const planeGeometry = new THREE.PlaneGeometry(width, height).rotateX(Math.PI / 2);
+		const blurPlane = new THREE.Mesh(planeGeometry);
+		const depthMaterial = new THREE.MeshDepthMaterial();
+		depthMaterial.depthTest = depthMaterial.depthWrite = false;
+		depthMaterial.onBeforeCompile = (shader) => {
+			shader.uniforms = { ...shader.uniforms, ucolor: { value: new THREE.Color(color) } };
+			shader.fragmentShader = shader.fragmentShader.replace('void main() {', 'uniform vec3 ucolor;\nvoid main() {');
+			shader.fragmentShader = shader.fragmentShader.replace(
+				'vec4( vec3( 1.0 - fragCoordZ ), opacity );',
+				'vec4( ucolor * fragCoordZ * 2.0, ( 1.0 - fragCoordZ ) * 1.0 );',
+			);
+		};
+		const horizontalBlurMaterial = new THREE.ShaderMaterial(HorizontalBlurShader);
+		const verticalBlurMaterial = new THREE.ShaderMaterial(VerticalBlurShader);
+		verticalBlurMaterial.depthTest = horizontalBlurMaterial.depthTest = false;
+		return { renderTarget, renderTargetBlur, planeGeometry, blurPlane, depthMaterial, horizontalBlurMaterial, verticalBlurMaterial };
+	}, [resolution, width, height, scale, color]);
+	const blurShadows = (amount: number) => {
+		const { blurPlane, horizontalBlurMaterial, verticalBlurMaterial, renderTarget, renderTargetBlur } = resources;
+		blurPlane.visible = true;
+		blurPlane.material = horizontalBlurMaterial;
+		horizontalBlurMaterial.uniforms.tDiffuse.value = renderTarget.texture;
+		horizontalBlurMaterial.uniforms.h.value = amount / 256;
+		gl.setRenderTarget(renderTargetBlur);
+		gl.render(blurPlane as any, shadowCamera.current!);
+		blurPlane.material = verticalBlurMaterial;
+		verticalBlurMaterial.uniforms.tDiffuse.value = renderTargetBlur.texture;
+		verticalBlurMaterial.uniforms.v.value = amount / 256;
+		gl.setRenderTarget(renderTarget);
+		gl.render(blurPlane as any, shadowCamera.current!);
+		blurPlane.visible = false;
+	};
+	let count = 0;
+	useFrame(() => {
+		if (!shadowCamera.current || !group.current || (frames !== Infinity && count >= frames)) return;
+		count++;
+		const initialBackground = scene.background;
+		const initialOverrideMaterial = scene.overrideMaterial;
+		group.current.visible = false;
+		scene.background = null;
+		scene.overrideMaterial = resources.depthMaterial;
+		gl.setRenderTarget(resources.renderTarget);
+		gl.render(scene, shadowCamera.current);
+		blurShadows(blur);
+		if (smooth) blurShadows(blur * 0.4);
+		gl.setRenderTarget(null);
+		group.current.visible = true;
+		scene.overrideMaterial = initialOverrideMaterial;
+		scene.background = initialBackground;
+	});
+	useImperativeHandle((ref ?? null) as any, () => group.current!, []);
+	<group rotation-x={Math.PI / 2} {...props} ref={group}>
+		<mesh renderOrder={renderOrder} geometry={resources.planeGeometry as any} scale={[1, -1, 1]} rotation={[-Math.PI / 2, 0, 0]}>
+			<meshBasicMaterial transparent map={resources.renderTarget.texture} opacity={opacity} depthWrite={depthWrite} />
+		</mesh>
+		<orthographicCamera ref={shadowCamera} args={[-width / 2, width / 2, height / 2, -height / 2, near, far]} />
+	</group>
+}

package/src/core/CubeTexture.three.tsrx

@@ -0,0 +1,32 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { useLoader } from '@octanejs/three';
+import { CubeTexture as ThreeCubeTexture, CubeTextureLoader, type Texture } from 'three';
+import { resolveRenderChildren, type RenderChildren } from './octane-children.js';
+
+export interface CubeTextureOptions {
+	path: string;
+}
+
+export function useCubeTexture(files: string[], { path }: CubeTextureOptions): ThreeCubeTexture {
+	const [cubeTexture] = useLoader(CubeTextureLoader, [files], (loader) => loader.setPath(path));
+	return cubeTexture;
+}
+
+useCubeTexture.preload = (files: string[], { path }: CubeTextureOptions) => useLoader.preload(
+	CubeTextureLoader,
+	[files],
+	(loader) => loader.setPath(path),
+);
+
+export type CubeTextureProps =
+	CubeTextureOptions & {
+		children?: RenderChildren<Texture>;
+		files: Parameters<typeof useCubeTexture>[0];
+	};
+
+export function CubeTexture({ children, files, ...options }: CubeTextureProps) @{
+	const texture = useCubeTexture(files, options);
+	<>
+		{resolveRenderChildren(children, texture)}
+	</>
+}

package/src/core/CurveModifier.three.tsrx

@@ -0,0 +1,37 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { createPortal, type ThreeRef } from '@octanejs/three';
+import { useEffect, useImperativeHandle, useLayoutEffect, useRef, useState } from '@octanejs/three/renderer';
+import type { UniversalRenderable } from 'octane/universal';
+import * as THREE from 'three';
+import { Flow } from 'three-stdlib';
+
+export interface CurveModifierProps {
+	children: UniversalRenderable;
+	curve?: THREE.Curve<THREE.Vector3>;
+}
+
+export type CurveModifierRef = Flow;
+
+export function CurveModifier({ children, curve, ref }: CurveModifierProps & {
+	ref?: ThreeRef<CurveModifierRef>;
+}) @{
+	const [scene] = useState(() => new THREE.Scene());
+	const [object, setObject] = useState<THREE.Object3D | undefined>(undefined);
+	const modifier = useRef<Flow | null>(null);
+	const source = useRef<THREE.Object3D | null>(null);
+	useLayoutEffect(() => {
+		if (!scene.children[0] || source.current === scene.children[0]) return;
+		source.current = scene.children[0];
+		const FlowConstructor = Flow as unknown as new (mesh: THREE.Mesh) => Flow;
+		modifier.current = new FlowConstructor(scene.children[0] as THREE.Mesh);
+		setObject(modifier.current.object3D as unknown as THREE.Object3D);
+	});
+	useEffect(() => {
+		if (curve) modifier.current?.updateCurve(0, curve as any);
+	}, [curve]);
+	useImperativeHandle(ref as any, () => modifier.current!, [modifier.current]);
+	<>
+		{createPortal(children, scene)}
+		{object && <primitive object={object} />}
+	</>
+}

package/src/core/Decal.three.tsrx

@@ -0,0 +1,132 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import {
+	applyProps,
+	type Euler as EulerProp,
+	type RefObject,
+	type ThreeElements,
+	type ThreeRef,
+	type Vector3 as Vector3Prop,
+} from '@octanejs/three';
+import { useImperativeHandle, useLayoutEffect, useMemo, useRef } from '@octanejs/three/renderer';
+import * as THREE from 'three';
+import { DecalGeometry } from 'three-stdlib';
+
+export type DecalProps =
+	Omit<ThreeElements['mesh'], 'ref' | 'children'> & {
+		debug?: boolean;
+		mesh?: RefObject<THREE.Mesh>;
+		position?: Vector3Prop;
+		rotation?: EulerProp | number;
+		scale?: Vector3Prop;
+		map?: THREE.Texture;
+		children?: ThreeElements['mesh']['children'];
+		polygonOffsetFactor?: number;
+		depthTest?: boolean;
+	};
+
+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;
+}
+
+function vecToArray(vector: number[] | Vector3Prop | EulerProp | number = [0, 0, 0]): number[] {
+	if (Array.isArray(vector)) return [Number(vector[0]), Number(vector[1]), Number(vector[2])];
+	if (vector instanceof THREE.Vector3 || vector instanceof THREE.Euler) return [
+		vector.x,
+		vector.y,
+		vector.z,
+	];
+	const scalar = vector as number;
+	return [scalar, scalar, scalar];
+}
+
+export function Decal({
+	debug,
+	depthTest = false,
+	polygonOffsetFactor = -10,
+	map,
+	mesh,
+	children,
+	position,
+	rotation,
+	scale,
+	ref,
+	...props
+}: DecalProps & { ref?: ThreeRef<THREE.Mesh> }) @{
+	const localRef = useRef<THREE.Mesh | null>(null);
+	const imperativeRef = useMemo(
+		() => (value: THREE.Mesh | null | undefined) => assignRef(ref, value ?? null),
+		[ref],
+	);
+	useImperativeHandle(imperativeRef, () => localRef.current!, []);
+	const helper = useRef<THREE.Mesh | null>(null);
+	const state = useRef({
+		position: new THREE.Vector3(),
+		rotation: new THREE.Euler(),
+		scale: new THREE.Vector3(1, 1, 1),
+	});
+	useLayoutEffect(() => {
+		if (!localRef.current) return;
+		const parent = mesh?.current || localRef.current.parent;
+		const target = localRef.current;
+		if (
+			!(parent instanceof THREE.Mesh)
+		) throw new Error('Decal must have a Mesh as parent or specify its "mesh" prop');
+		applyProps(state.current, { position, scale });
+		const matrixWorld = parent.matrixWorld.clone();
+		parent.matrixWorld.identity();
+		if (!rotation || typeof rotation === 'number') {
+			const object = new THREE.Object3D();
+			object.position.copy(state.current.position);
+			const vertices = parent.geometry.attributes.position.array;
+			if (parent.geometry.attributes.normal === undefined) parent.geometry.computeVertexNormals();
+			const normal = parent.geometry.attributes.normal.array;
+			let distance = Infinity;
+			const closestNormal = new THREE.Vector3();
+			let chosenIndex = -1;
+			for (let index = 0; index < vertices.length; index += 3) {
+				const xDiff = vertices[index] - object.position.x;
+				const yDiff = vertices[index + 1] - object.position.y;
+				const zDiff = vertices[index + 2] - object.position.z;
+				const squared = xDiff * xDiff + yDiff * yDiff + zDiff * zDiff;
+				if (squared < distance) {
+					distance = squared;
+					chosenIndex = index;
+				}
+			}
+			closestNormal.fromArray(normal, chosenIndex);
+			object.lookAt(object.position.clone().add(closestNormal));
+			object.rotateZ(Math.PI);
+			object.rotateY(Math.PI);
+			if (typeof rotation === 'number') object.rotateZ(rotation);
+			applyProps(state.current, { rotation: object.rotation });
+		} else applyProps(state.current, { rotation });
+		if (helper.current) applyProps(helper.current, state.current);
+		const Geometry = DecalGeometry as unknown as new (mesh: THREE.Mesh, position: THREE.Vector3, rotation: THREE.Euler, scale: THREE.Vector3) => THREE.BufferGeometry;
+		target.geometry =
+			new Geometry(parent, state.current.position, state.current.rotation, state.current.scale);
+		parent.matrixWorld = matrixWorld;
+		return () => target.geometry.dispose();
+	}, [mesh, ...vecToArray(position), ...vecToArray(scale), ...vecToArray(rotation)]);
+	useLayoutEffect(() => {
+		if (helper.current) helper.current.traverse((child) => (child.raycast = () => null));
+	}, [debug]);
+	<mesh
+		ref={localRef}
+		material-transparent
+		material-polygonOffset
+		material-polygonOffsetFactor={polygonOffsetFactor}
+		material-depthTest={depthTest}
+		material-map={map}
+		{...props}
+	>
+		{children}
+		{debug &&
+			<mesh ref={helper}>
+				<boxGeometry />
+				<meshNormalMaterial wireframe />
+				<axesHelper />
+			</mesh>}
+	</mesh>
+}

package/src/core/Detailed.three.tsrx

@@ -0,0 +1,28 @@
+/** @jsxImportSource @octanejs/three/intrinsics */
+import { type ThreeElements, type ThreeRef, useFrame } from '@octanejs/three';
+import { useLayoutEffect, useRef } from '@octanejs/three/renderer';
+import type { OctaneNode } from 'octane';
+import type { LOD } from 'three';
+
+export type DetailedProps =
+	Omit<ThreeElements['lOD'], 'ref' | 'children'> & {
+		children: OctaneNode;
+		hysteresis?: number;
+		distances: number[];
+	};
+
+export function Detailed({ children, hysteresis = 0, distances, ref, ...props }: DetailedProps & {
+	ref?: ThreeRef<LOD>;
+}) @{
+	const lodRef = useRef<LOD | null>(null);
+	useLayoutEffect(() => {
+		const lod = lodRef.current;
+		if (!lod) return;
+		lod.levels.length = 0;
+		lod.children.forEach((object, index) => {
+			lod.levels.push({ object, hysteresis, distance: distances[index] });
+		});
+	});
+	useFrame((state) => lodRef.current?.update(state.camera));
+	<lOD ref={[lodRef, ref ?? null]} {...props}>{children}</lOD>
+}