@needle-tools/engine 4.4.0-alpha.5 → 4.4.0-beta.1

package/src/engine/engine_physics.ts

@@ -1,783 +1,783 @@
-import { getRaycastMesh } from '@needle-tools/gltf-progressive';
-import { ArrayCamera, Box3, BufferGeometry, Camera, type Intersection, Layers, Line, Matrix3, Matrix4, Mesh, Object3D, PerspectiveCamera, Plane, Ray, Raycaster, SkinnedMesh, Sphere, SphereGeometry, Vector2, Vector3 } from 'three'
-import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
-import type { MeshBVH, MeshBVHOptions, StaticGeometryGenerator } from 'three-mesh-bvh';
-import type { GenerateMeshBVHWorker } from 'three-mesh-bvh/src/workers/GenerateMeshBVHWorker.js';
-
-import { isDevEnvironment } from './debug/index.js';
-import { Gizmos } from './engine_gizmos.js';
-import { Context } from './engine_setup.js';
-import { getTempVector, getWorldPosition } from "./engine_three_utils.js"
-import type { ConstructorConcrete, Vec2, Vec3, } from './engine_types.js';
-import type { IPhysicsEngine } from './engine_types.js';
-import { getParam } from "./engine_utils.js"
-
-const debugPhysics = getParam("debugphysics");
-const layerMaskHelper: Layers = new Layers();
-
-
-export declare type RaycastTestObjectReturnType = void | boolean | "continue in children";
-export declare type RaycastTestObjectCallback = (obj: Object3D) => RaycastTestObjectReturnType;
-
-export declare interface IRaycastOptions {
-    /** Optionally a custom raycaster can be provided. Other properties will then be set on this raycaster */
-    raycaster?: Raycaster;
-    /** Optional ray that can be used for raycasting  
-     *  @link https://threejs.org/docs/#api/en/math/Ray 
-     * */
-    ray?: Ray;
-    /** The camera to use for the raycaster */
-    cam?: Camera | null;
-    /** Point on screen in raycast space / normalized device coordinates (-1 to 1).   
-     * @link https://threejs.org/docs/#api/en/core/Raycaster.setFromCamera */
-    screenPoint?: Vector2;
-    /** Raycast results array. You can provide an array here to avoid creating a new one (note that if your array already contains items they will be removed) */
-    results?: Array<Intersection>;
-    /** Objects to raycast against. If no target array is provided the whole scene will be raycasted */
-    targets?: Array<Object3D>;
-    /**
-     * If true, the raycaster will traverse the scene recursively.
-     * @default true
-     */
-    recursive?: boolean;
-    /**
-     * If true, the raycaster will use a more precise method to test for intersections. This is slower but more accurate.  
-     * @default true
-     */
-    precise?: boolean;
-    /** Set the raycaster near distance:  
-     * The near factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be smaller than the far property.  
-     * @link https://threejs.org/docs/#api/en/core/Raycaster.near
-     */
-    minDistance?: number;
-    /** Set the raycaster far distance:  
-     * The far factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be larger than the near property.
-     * @link https://threejs.org/docs/#api/en/core/Raycaster.far
-     */
-    maxDistance?: number;
-    /** @link https://threejs.org/docs/#api/en/core/Raycaster.params */
-    lineThreshold?: number;
-    /** raw layer mask, use setLayer to set an individual layer active */
-    layerMask?: Layers | number;
-    ignore?: Object3D[];
-    /** Optional calback function to be called per object before tested for intersections.  
-     * This can be used to filter objects.  
-     * Return `false` to ignore the object completely or `"continue in children"` to skip the object but continue to traverse its children (if you do raycast with `recursive` enabled)  
-     * */
-    testObject?: RaycastTestObjectCallback;
-
-    /**
-     * Use MeshBVH for raycasting. This is faster than the default threejs raycaster but uses more memory.
-     * @default undefined
-     */
-    useAcceleratedRaycast?: boolean;
-}
-
-export class RaycastOptions implements IRaycastOptions {
-    public static readonly AllLayers = 0xFFFFFFFF;
-
-    ray?: Ray;
-    cam?: Camera | null;
-    screenPoint?: Vector2;
-    raycaster?: Raycaster;
-    results?: Array<Intersection>;
-    targets?: Array<Object3D>;
-    recursive?: boolean = true;
-    minDistance?: number;
-    maxDistance?: number;
-    lineThreshold?: number;
-    layerMask?: Layers | number;
-    ignore?: Object3D[];
-    testObject?: RaycastTestObjectCallback;
-    useAcceleratedRaycast?: boolean | undefined;
-
-    screenPointFromOffset(ox: number, oy: number) {
-        if (this.screenPoint === undefined) this.screenPoint = new Vector2();
-        this.screenPoint.x = ox / window.innerWidth * 2 - 1;
-        this.screenPoint.y = -(oy / window.innerHeight) * 2 + 1;
-    }
-
-    /** sets one layer for raycasting (e.g. layer 4, only objects on layer 4 will then be hit) */
-    setLayer(layer: number) {
-        layerMaskHelper.set(layer);
-        this.layerMask = layerMaskHelper;
-    }
-
-    /** sets the layer.mask value directly, use setLayer if you want to set e.g. an individual layer only active. See https://threejs.org/docs/#api/en/core/Layers for more information about layers */
-    setMask(mask: number) {
-        if (!this.layerMask) this.layerMask = new Layers();
-        const lm = this.layerMask as Layers;
-        if (lm)
-            lm.mask = mask;
-        else this.layerMask = mask;
-    }
-
-}
-
-export class SphereIntersection implements Intersection {
-    distance: number;
-    point: Vector3;
-    object: Object3D;
-    constructor(object: Object3D, distance: number, point: Vector3) {
-        this.object = object;
-        this.distance = distance;
-        this.point = point;
-    }
-}
-
-export class Physics {
-
-    private static _raycasting: number = 0;
-    /**
-     * Returns true if raycasting is currently happening
-     */
-    public static get raycasting() {
-        return this._raycasting > 0;
-    }
-
-    /**@deprecated use `this.context.physics.engine.raycast` {@link IPhysicsEngine.raycast} */
-    public raycastPhysicsFast(origin: Vec2 | Vec3, direction: Vec3 | undefined = undefined, maxDistance: number = Infinity, solid: boolean = true) {
-        return this.context.physics.engine?.raycast(origin, direction, { maxDistance, solid }) ?? null;
-    }
-
-    /**@deprecated use `this.context.physics.engine.raycastAndGetNormal` {@link IPhysicsEngine.raycastAndGetNormal} */
-    public raycastPhysicsFastAndGetNormal(origin: Vec2 | Vec3, direction: Vec3 | undefined = undefined, maxDistance: number = Infinity, solid: boolean = true) {
-        return this.context.physics.engine?.raycastAndGetNormal(origin, direction, { maxDistance, solid }) ?? null;
-    }
-
-    /**@deprecated use this.context.physics.engine.sphereOverlap */
-    public sphereOverlapPhysics(point: Vector3, radius: number) {
-        return this.context.physics.engine?.sphereOverlap(point, radius) ?? null;
-    }
-
-
-    private readonly context: Context;
-    engine?: IPhysicsEngine;
-
-    constructor(context: Context) {
-        this.context = context;
-    }
-
-    // raycasting
-    private readonly raycaster: Raycaster = new Raycaster();
-    private readonly defaultRaycastOptions: RaycastOptions = new RaycastOptions();
-    private readonly targetBuffer: Array<Object3D> = new Array<Object3D>(1);
-    private readonly defaultThresholds = {
-        Mesh: {},
-        Line: { threshold: -1 },
-        LOD: {},
-        Points: { threshold: 0 },
-        Sprite: {}
-    }
-
-
-    private sphereResults: Array<Intersection> = new Array<Intersection>();
-    private sphereMask: Layers = new Layers();
-    private readonly sphere: Sphere = new Sphere();
-    /** Test overlapping of a sphere with the threejs geometry. This does not use colliders. This does not return an exact intersection point (intersections returned contain the object and the world position of the object that is being hit)
-     * For a more accurate test use the physics engine's collider overlap test (see sphereOverlapPhysics)
-     * @param spherePos the center of the sphere in world space
-     * @param radius the radius of the sphere
-     * @param traverseChildsAfterHit if false it will stop after the first hit. If true it will continue to traverse and add all hits to the result array
-     * @param bvh use MeshBVH for raycasting. This is faster than the default threejs raycaster but uses more memory.
-     * @param shouldRaycast optional callback to filter objects. Return `false` to ignore the object completely or `"continue in children"` to skip the object but continue to traverse its children (if you do raycast with `recursive` enabled)
-     */
-    public sphereOverlap(spherePos: Vector3, radius: number, traverseChildsAfterHit: boolean = true, bvh: boolean = false, shouldRaycast: RaycastTestObjectCallback | null = null): Array<Intersection> {
-        this.sphereResults.length = 0;
-        if (!this.context.scene) return this.sphereResults;
-        const mask = this.sphereMask;
-        mask.enableAll();
-        mask.disable(2);
-        for (const ch of this.context.scene.children) {
-            this.intersectSphere(ch, spherePos, radius, mask, this.sphereResults, traverseChildsAfterHit, bvh, shouldRaycast);
-        }
-        return this.sphereResults.sort((a, b) => a.distance - b.distance);
-    }
-
-    public raycastFromRay(ray: Ray, options: IRaycastOptions | null = null): Array<Intersection> {
-        const opts = options ?? this.defaultRaycastOptions;
-        opts.ray = ray;
-        const res = this.raycast(opts);
-        // reset the default options ray
-        if (opts === this.defaultRaycastOptions) opts.ray = undefined;
-        return res;
-    }
-
-    /** raycast against rendered three objects. This might be very slow depending on your scene complexity.
-     * We recommend setting objects to IgnoreRaycast layer (2) when you don't need them to be raycasted.
-     * Raycasting SkinnedMeshes is specially expensive.
-     * Use raycastPhysics for raycasting against physic colliders only. Depending on your scenario this might be faster.
-     * @param options raycast options. If null, default options will be used.
-     */
-    public raycast(options: IRaycastOptions | null = null): Array<Intersection> {
-        if (debugPhysics) {
-            performance.mark('raycast.start');
-        }
-        if (!options) options = this.defaultRaycastOptions;
-        const mp = options.screenPoint ?? this.context.input.mousePositionRC;
-        const rc = options.raycaster ?? this.raycaster;
-        rc.near = options.minDistance ?? 0;
-        rc.far = options.maxDistance ?? Infinity;
-        rc.params = this.defaultThresholds;
-        if (options.lineThreshold === undefined) options.lineThreshold = -1;
-        rc.params.Line = { threshold: options.lineThreshold };
-        if (options.ray) {
-            rc.ray.copy(options.ray);
-        }
-        else {
-            const cam = options.cam ?? this.context.mainCamera;
-            if (!cam) {
-                if (debugPhysics)
-                    console.error("Can not perform raycast - no main camera found");
-                if (this.defaultRaycastOptions.results) this.defaultRaycastOptions.results.length = 0;
-                return this.defaultRaycastOptions.results ?? [];
-            }
-            const xrCam = this.context.xrCamera;
-            if (this.context.isInXR && xrCam instanceof ArrayCamera && xrCam.cameras.length > 0) {
-                rc.setFromCamera(mp, xrCam.cameras[0] as PerspectiveCamera);
-            }
-            else {
-                rc.setFromCamera(mp, cam);
-            }
-        }
-        let targets = options.targets;
-        if (!targets) {
-            targets = this.targetBuffer;
-            targets.length = 1;
-            targets[0] = this.context.scene;
-        }
-        let results = options.results;
-        if (this.defaultRaycastOptions.results)
-            this.defaultRaycastOptions.results.length = 0;
-        if (!results) {
-            if (!this.defaultRaycastOptions.results)
-                this.defaultRaycastOptions.results = new Array<Intersection>();
-            results = this.defaultRaycastOptions.results;
-        }
-
-        // layermask
-        // https://github.com/mrdoob/js/blob/master/src/core/Layers.js
-        if (options.layerMask !== undefined) {
-            if (options.layerMask instanceof Layers)
-                rc.layers.mask = options.layerMask.mask;
-            else
-                rc.layers.mask = options.layerMask;
-        }
-        else {
-            rc.layers.enableAll();
-            rc.layers.disable(2);
-        }
-
-        if (debugPhysics) {
-            // Gizmos.DrawRay(rc.ray.origin, rc.ray.direction, 0xff0000, .2);
-            console.time("raycast");
-        }
-
-        // shoot
-        results.length = 0;
-        Physics._raycasting++;
-        this.intersect(this.raycaster, targets, results, options);
-        results.sort((a, b) => a.distance - b.distance);
-
-        // TODO: instead of doing this we should temporerly set these objects to layer 2 during raycasting
-        const ignorelist = options.ignore;
-        if (ignorelist !== undefined && ignorelist.length > 0) {
-            results = results.filter(r => !ignorelist.includes(r.object));
-        }
-
-        Physics._raycasting--;
-
-        if (debugPhysics) {
-            console.timeEnd("raycast");
-            console.warn("#" + this.context.time.frame + ", hits:", (results?.length ? [...results] : "nothing"));
-            performance.mark('raycast.end');
-            performance.measure('raycast', 'raycast.start', 'raycast.end');
-        }
-
-        return results;
-    }
-
-    private intersect(raycaster: Raycaster, objects: Object3D[], results: Intersection[], options: IRaycastOptions) {
-        for (const obj of objects) {
-
-            // handle case where null or undefined object is in the scene
-            if (!obj) continue;
-            // dont raycast invisible objects
-            if (obj.visible === false) continue;
-
-            if (Gizmos.isGizmo(obj)) continue;
-
-            // dont raycast object if it's a line and the line threshold is < 0
-            if (options.lineThreshold !== undefined && options.lineThreshold < 0) {
-                if (obj instanceof Line) {
-                    continue;
-                }
-            }
-
-            let shouldIntersectObject = true;
-            const mesh = obj as Mesh | SkinnedMesh;
-            const geo = mesh.geometry;
-
-            // We need to run this first because of "EventSystem.testObject" implementation
-            if (options.testObject) {
-                const testResult = options.testObject?.(obj);
-                if (testResult === false) {
-                    continue;
-                }
-                else if (testResult === "continue in children") {
-                    shouldIntersectObject = false;
-                }
-            }
-
-            if (shouldIntersectObject) {
-                if (!geo) {
-                    shouldIntersectObject = false;
-                }
-                // check if the geometry is valid
-                else if (!canRaycastGeometry(geo)) {
-                    shouldIntersectObject = false;
-                }
-            }
-
-
-            if (shouldIntersectObject) {
-                const raycastMesh = getRaycastMesh(obj);
-                if (raycastMesh) mesh.geometry = raycastMesh as any;
-                const lastResultsCount = results.length;
-
-                let usePrecise = true;
-                if (options.precise === false) usePrecise = false;
-                usePrecise ||= geo.getAttribute("position")?.array?.length < 64;
-                if (mesh instanceof GroundedSkybox) {
-                    usePrecise = false;
-                }
-
-                if (!usePrecise && customRaycast(mesh, raycaster, results)) {
-                    // did handle raycast
-                }
-                else if (options.useAcceleratedRaycast !== false) {
-                    NEMeshBVH.runMeshBVHRaycast(raycaster, mesh, results, this.context);
-                }
-                else {
-                    raycaster.intersectObject(mesh, false, results);
-                }
-
-                if (debugPhysics && results.length != lastResultsCount) {
-                    const latestResult = results[results.length - 1];
-                    const col = raycastMesh ? 0x88dd55 : 0x770000;
-                    Gizmos.DrawWireSphere(latestResult.point, .1, col, 1, false);
-                    Gizmos.DrawWireMesh({ mesh: obj as Mesh, depthTest: false, duration: .2, color: col });
-                }
-                mesh.geometry = geo;
-            }
-
-            if (options.recursive !== false) {
-                this.intersect(raycaster, obj.children, results, options);
-            }
-        }
-        return results;
-    }
-
-    private tempBoundingBox: Box3 = new Box3();
-    private intersectSphere(obj: Object3D, spherePos: Vector3, radius: number, mask: Layers, results: Array<Intersection>, traverseChildsAfterHit: boolean, useBvh: boolean, shouldRaycast: RaycastTestObjectCallback | null): void {
-
-        let shouldIntersectObject = obj && (obj as Mesh).isMesh && obj.layers.test(mask) && !Gizmos.isGizmo(obj);
-
-        shouldIntersectObject &&= obj.visible;
-        shouldIntersectObject &&= !(obj instanceof Line);
-        shouldIntersectObject &&= !(obj instanceof GroundedSkybox);
-
-        const mesh = obj as Mesh;
-        const geo = mesh.geometry;
-
-        if (shouldIntersectObject && shouldRaycast) {
-            const testResult = shouldRaycast(obj);
-            if (testResult === false) {
-                return;
-            }
-            else if (testResult === "continue in children") {
-                shouldIntersectObject = false;
-            }
-        }
-
-        // check if geometry exists
-        if (!geo) {
-            shouldIntersectObject = false;
-        }
-        // check if the geometry is valid
-        else if (!canRaycastGeometry(geo)) {
-            shouldIntersectObject = false;
-        }
-
-
-        if (shouldIntersectObject) {
-            if (useBvh) {
-                const sphere = this.sphere;
-                sphere.center.copy(spherePos);
-                sphere.radius = radius;
-                const previousResults = results.length;
-                NEMeshBVH.runMeshBVHRaycast(this.sphere, mesh, results, this.context);
-                if (previousResults != results.length && !traverseChildsAfterHit) {
-                    return;
-                }
-            }
-            // Classic sphere intersection test
-            else {
-                if (!geo.boundingBox)
-                    geo.computeBoundingBox();
-
-                if (geo.boundingBox) {
-                    if (mesh.matrixWorldNeedsUpdate) mesh.updateWorldMatrix(false, false);
-                    const test = this.tempBoundingBox.copy(geo.boundingBox).applyMatrix4(mesh.matrixWorld);
-                    const sphere = this.sphere;
-                    sphere.center.copy(spherePos);
-                    sphere.radius = radius;
-
-                    if (sphere.intersectsBox(test)) {
-                        const wp = getWorldPosition(obj);
-                        const dist = wp.distanceTo(sphere.center);
-                        const int = new SphereIntersection(obj, dist, wp);
-                        results.push(int);
-                        if (!traverseChildsAfterHit) return;
-                    }
-                }
-            }
-        }
-
-
-        if (obj.children) {
-            for (const ch of obj.children) {
-                const len = results.length;
-                this.intersectSphere(ch, spherePos, radius, mask, results, traverseChildsAfterHit, useBvh, shouldRaycast);
-                if (len != results.length && !traverseChildsAfterHit) return;
-            }
-        }
-    }
-}
-
-/**
- * See https://linear.app/needle/issue/NE-5524
- * @returns true if the geometry can be raycasted
- */
-function canRaycastGeometry(geo: BufferGeometry): boolean {
-    // if the geometry has an index buffer but no indices, we can't raycast
-    if (geo.index && geo.index.array.length < 3) return false;
-    // we might want to test if the geometry has a position buffer
-    return true;
-}
-
-
-const tempSphere = new Sphere();
-const tempPlane = new Plane();
-const normalUpMatrix = new Matrix3();
-
-/**
- * @returns false if custom raycasting can not run, otherwise true
- */
-function customRaycast(mesh: Mesh, raycaster: Raycaster, results: Intersection[]): boolean {
-    const originalComputeIntersectionsFn = mesh["_computeIntersections"];
-    if (!originalComputeIntersectionsFn) {
-        return false;
-    }
-
-    // compute custom intersection, check if a custom method already exists
-    let computeCustomIntersectionFn = mesh["_computeIntersections:Needle"];
-    if (!computeCustomIntersectionFn) {
-        // create and bind a custom method once to the mesh object
-        // TODO: maybe we want to add this to the prototype instead
-        computeCustomIntersectionFn = mesh["_computeIntersections:Needle"] = function (raycaster: Raycaster, intersects: Intersection[], _rayLocalSpace: Ray) {
-            const self = this as Mesh;
-            const boundingSphere = self.geometry.boundingSphere;
-            if (boundingSphere) {
-
-                if (self instanceof GroundedSkybox) {
-                    tempPlane.setFromNormalAndCoplanarPoint(getTempVector(0, 1, 0), getTempVector(0, -self.position.y, 0));
-                    tempPlane.applyMatrix4(self.matrixWorld, normalUpMatrix);
-                    const point = raycaster.ray.intersectPlane(tempPlane, getTempVector());
-                    if (point) {
-                        tempSphere.copy(boundingSphere);
-                        tempSphere.applyMatrix4(self.matrixWorld);
-                        const dir = getTempVector(point).sub(raycaster.ray.origin);
-                        const distance = dir.length();
-                        const groundProjectionFloorRadius = tempSphere.radius * .5;
-                        if (distance < groundProjectionFloorRadius) // make sure we're inside the sphere
-                            intersects.push({ distance: distance, point, object: self, normal: tempPlane.normal.clone() });
-                    }
-                    return;
-                }
-
-                tempSphere.copy(boundingSphere);
-                tempSphere.applyMatrix4(self.matrixWorld);
-                const point = raycaster.ray.intersectSphere(tempSphere, getTempVector());
-                if (point) {
-                    const dir = getTempVector(point).sub(raycaster.ray.origin);
-                    const distance = dir.length();
-                    // Ignore hits when we're inside the sphere
-                    if (distance > tempSphere.radius) {
-                        const normal = dir.clone().normalize();
-                        intersects.push({ distance: distance, point, object: self, normal });
-                    }
-                }
-            }
-        }
-    }
-    mesh["_computeIntersections"] = computeCustomIntersectionFn;
-    raycaster.intersectObject(mesh, false, results);
-    mesh["_computeIntersections"] = originalComputeIntersectionsFn;
-    return true;
-}
-
-
-
-declare module 'three' {
-    interface SkinnedMesh {
-        staticGenerator?: StaticGeometryGenerator;
-        staticGeometry?: BufferGeometry;
-        staticGeometryLastUpdate?: number;
-    }
-    interface Mesh {
-        acceleratedRaycast?: any;
-    }
-    export interface SkinnedMesh {
-        autoUpdateMeshBVH?: boolean;
-        bvhNeedsUpdate?: boolean;
-    }
-}
-
-
-
-namespace NEMeshBVH {
-    export function runMeshBVHRaycast(method: Raycaster | Sphere, mesh: Mesh, results: Intersection[], context: Pick<Context, "xr">): boolean {
-        if (!mesh.geometry) {
-            return false;
-        }
-        // Completely prevent raycasting on object that has no position
-        if (!mesh.geometry.hasAttribute('position')) {
-            return false;
-        }
-        // The code below handles generating the mesh bvh structure that is used for raycasting
-        // We first try to setup workers so it can run off the main thread
-        const geom = mesh.geometry;
-
-        if ((mesh as SkinnedMesh)?.isSkinnedMesh) {
-            const skinnedMesh = mesh as SkinnedMesh;
-            const skinnedMeshBVHNeedsUpdate = skinnedMesh.bvhNeedsUpdate;
-            if (!skinnedMesh.staticGenerator) {
-                loadMeshBVHLibrary();
-                if (_StaticGeometryGenerator) {
-                    skinnedMesh.staticGenerator = new _StaticGeometryGenerator(mesh);
-                    skinnedMesh.staticGenerator.applyWorldTransforms = false;
-                    skinnedMesh.staticGeometry = skinnedMesh.staticGenerator.generate();
-                    geom.boundsTree = _computeBoundsTree?.call(skinnedMesh.staticGeometry);
-                    skinnedMesh.staticGeometryLastUpdate = performance.now() + Math.random() * 200;
-                    if (skinnedMesh.autoUpdateMeshBVH === undefined)
-                        skinnedMesh.autoUpdateMeshBVH = false;
-                }
-            }
-            else if (geom.boundsTree && (skinnedMesh.autoUpdateMeshBVH === true || skinnedMeshBVHNeedsUpdate === true)) {
-                // automatically refit the tree every 300ms
-                const now = performance.now();
-                const timeSinceLastUpdate = now - skinnedMesh.staticGeometryLastUpdate!;
-                if (skinnedMeshBVHNeedsUpdate || timeSinceLastUpdate > 100) {
-                    skinnedMesh.bvhNeedsUpdate = false;
-                    skinnedMesh.staticGeometryLastUpdate = now;
-                    skinnedMesh.staticGenerator?.generate(skinnedMesh.staticGeometry);
-                    geom.boundsTree.refit();
-                }
-            }
-        }
-
-        else if (!geom.boundsTree) {
-
-            // Try to generate the bvh on a worker
-            if (!didSetupWorker) internalSetupWorker();
-
-            let canUseWorker = true;
-
-            if (context.xr) { // < in XR for some reason sometimes geometry (controllers) are broken - maybe this is not exclusive to controller geometry
-                canUseWorker = false;
-            }
-            else if (geom[canUseWorkerSymbol] === false) {
-                canUseWorker = false;
-            }
-            else if (geom.getAttribute('position')?.["isInterleavedBufferAttribute"]
-                || geom.index && geom.index?.["isInterleavedBufferAttribute"]) {
-                canUseWorker = false;
-            }
-
-            // if we have a worker use that
-            if (canUseWorker && _GenerateMeshBVHWorker) {
-                if (geom[workerTaskSymbol] === undefined) {
-
-                    // get available worker
-                    let workerInstance: GenerateMeshBVHWorker | null = null;
-                    // if there are workers available, use one
-                    if (availableWorkers.length > 0) {
-                        const available = availableWorkers.shift();
-                        if (available && !available.running) {
-                            workerInstance = available;
-                        }
-                    }
-                    // if there are no workers available, create a new one
-                    if (!workerInstance && workerInstances.length < 3) {
-                        workerInstance = new _GenerateMeshBVHWorker();
-                        workerInstances.push(workerInstance);
-                    }
-
-                    if (workerInstance != null && !workerInstance.running) {
-                        const name = mesh.name;
-                        if (debugPhysics) console.log("<<<< worker start", name, workerInstance);
-                        geom[workerTaskSymbol] = "queued";
-                        performance.mark("bvh.create.start");
-                        // If we don't clone the buffer geometry here we will get a "Transferable ArrayBuffer" error
-                        // see https://linear.app/needle/issue/NE-5602
-                        // Additionally normal raycasts stop working if we don't clone the geometry
-                        const copy = geom.clone();
-                        try {
-                            workerInstance.generate(copy)
-                                .then(bvh => {
-                                    geom[workerTaskSymbol] = "done";
-                                    geom.boundsTree = bvh;
-                                })
-                                .catch(err => {
-                                    geom[workerTaskSymbol] = "failed - " + err?.message;
-                                    geom[canUseWorkerSymbol] = false;
-                                    if (debugPhysics) console.error("Failed to generate mesh bvh on worker", err);
-                                })
-                                .finally(() => {
-                                    if (debugPhysics) console.log(">>>>> worker done", name, { hasBoundsTre: geom.boundsTree != undefined });
-                                    availableWorkers.push(workerInstance);
-                                    copy.dispose();
-                                    performance.mark("bvh.create.end");
-                                    performance.measure("bvh.create (worker)", "bvh.create.start", "bvh.create.end");
-                                });
-                        }
-                        catch (err) {
-                            console.error("Failed to generate mesh bvh on worker", err);
-                        }
-                    }
-                    else {
-                        // we don't want to generate the BVH on the main thread unless workers are not supported
-                        // If all workers are currently running we need to run a "slow" raycast
-                        if (debugPhysics) console.warn("No worker available");
-                    }
-                }
-            }
-            // Fallback to sync bvh generation if workers are not available
-            else if (!isRequestingWorker || !canUseWorker) {
-                loadMeshBVHLibrary();
-                if (_MeshBVH) {
-                    performance.mark("bvh.create.start");
-                    geom.boundsTree = new _MeshBVH(geom as BufferGeometry);
-                    performance.mark("bvh.create.end");
-                    performance.measure("bvh.create", "bvh.create.start", "bvh.create.end");
-                }
-            }
-        }
-
-        if (method instanceof Raycaster) {
-            const raycaster = method;
-            // Skinned meshes work when we disable applyWorldTransform in the generator (see applyWorldTransforms = false above)
-            // We do need to set the accelerated raycast method (bind it once)
-            // We could also override it on the prototype - not sure if it's more performant but then it would always run
-            const raycastMesh = mesh.raycast;
-            if (geom.boundsTree) {
-                loadMeshBVHLibrary();
-                if (_acceleratedRaycast) {
-                    // bind the raycast to the mesh
-                    if (!mesh.acceleratedRaycast) {
-                        mesh.acceleratedRaycast = _acceleratedRaycast.bind(mesh) as any;
-                        if (debugPhysics) console.debug(`Physics: bind acceleratedRaycast fn to \"${mesh.name}\"`);
-                    }
-                    mesh.raycast = mesh.acceleratedRaycast;
-                }
-            }
-            else {
-                if (debugPhysics) console.warn("No bounds tree found for mesh", mesh.name, { workerTask: geom[workerTaskSymbol], hasAcceleratedRaycast: _acceleratedRaycast != null });
-            }
-            const prevFirstHitOnly = raycaster.firstHitOnly;
-            raycaster.firstHitOnly = false;
-            raycaster.intersectObject(mesh, false, results);
-            raycaster.firstHitOnly = prevFirstHitOnly;
-            mesh.raycast = raycastMesh;
-            return true;
-        }
-        else if (method instanceof Sphere) {
-            const bvh = geom.boundsTree;
-            if (bvh) {
-                const sphere = method;
-                // Gizmos.DrawWireSphere(sphere.center, sphere.radius, 0xdddd00, 1, false);
-
-                invMat.copy(mesh.matrixWorld).invert();
-                sphere.applyMatrix4(invMat);
-                const intersects = bvh.intersectsSphere(sphere);
-                if (intersects) {
-                    // console.log(intersects, mesh.name);
-                    const worldpos = getWorldPosition(mesh);
-                    const distance = worldpos.distanceTo(sphere.center);
-                    const intersection = new SphereIntersection(mesh, distance, worldpos);
-                    results.push(intersection);
-                }
-            }
-            return true;
-        }
-
-
-        return false;
-    }
-
-    let didLoadMeshBVHLibrary: boolean = false;
-    let _acceleratedRaycast: Function | null = null;
-    let _MeshBVH: ConstructorConcrete<MeshBVH> | null = null;
-    let _StaticGeometryGenerator: ConstructorConcrete<StaticGeometryGenerator> | null = null;
-    let _computeBoundsTree: ((_opt?: MeshBVHOptions) => MeshBVH) | null = null;
-
-    function loadMeshBVHLibrary() {
-        if (didLoadMeshBVHLibrary) return;
-        didLoadMeshBVHLibrary = true;
-        import("three-mesh-bvh").then(res => {
-            _acceleratedRaycast = res.acceleratedRaycast;
-            _MeshBVH = res.MeshBVH;
-            _StaticGeometryGenerator = res.StaticGeometryGenerator;
-            _computeBoundsTree = res.computeBoundsTree;
-        }).catch(_err => {
-            if (debugPhysics || isDevEnvironment()) {
-                console.error("Failed to load BVH library...", _err.message);
-            }
-        })
-    }
-
-
-    const invMat = new Matrix4();
-
-    /** True after the worker has been requested for the first time */
-    let didSetupWorker: boolean = false;
-    /** True while the worker is being requested */
-    let isRequestingWorker: boolean = false;
-    let _GenerateMeshBVHWorker: ConstructorConcrete<GenerateMeshBVHWorker> | null = null;
-
-    const workerTaskSymbol = Symbol("Needle:MeshBVH-Worker");
-    const canUseWorkerSymbol = Symbol("Needle:MeshBVH-CanUseWorker");
-    const workerInstances: GenerateMeshBVHWorker[] = [];
-    const availableWorkers: GenerateMeshBVHWorker[] = [];
-
-    function internalSetupWorker() {
-        didSetupWorker = true;
-        isRequestingWorker = true;
-        // Using local worker. see https://github.com/gkjohnson/three-mesh-bvh/issues/636#issuecomment-2209571751
-        import("./physics/workers/mesh-bvh/GenerateMeshBVHWorker.js")
-            .then(res => {
-                _GenerateMeshBVHWorker = res.GenerateMeshBVHWorker;
-            })
-            .catch(_err => {
-                if (debugPhysics || isDevEnvironment()) {
-                    console.warn("Failed to setup mesh bvh worker");
-                }
-            })
-            .finally(() => {
-                isRequestingWorker = false;
-            });
-    }
-
-
-}
+import { getRaycastMesh } from '@needle-tools/gltf-progressive';
+import { ArrayCamera, Box3, BufferGeometry, Camera, type Intersection, Layers, Line, Matrix3, Matrix4, Mesh, Object3D, PerspectiveCamera, Plane, Ray, Raycaster, SkinnedMesh, Sphere, SphereGeometry, Vector2, Vector3 } from 'three'
+import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
+import type { MeshBVH, MeshBVHOptions, StaticGeometryGenerator } from 'three-mesh-bvh';
+import type { GenerateMeshBVHWorker } from 'three-mesh-bvh/src/workers/GenerateMeshBVHWorker.js';
+
+import { isDevEnvironment } from './debug/index.js';
+import { Gizmos } from './engine_gizmos.js';
+import { Context } from './engine_setup.js';
+import { getTempVector, getWorldPosition } from "./engine_three_utils.js"
+import type { ConstructorConcrete, Vec2, Vec3, } from './engine_types.js';
+import type { IPhysicsEngine } from './engine_types.js';
+import { getParam } from "./engine_utils.js"
+
+const debugPhysics = getParam("debugphysics");
+const layerMaskHelper: Layers = new Layers();
+
+
+export declare type RaycastTestObjectReturnType = void | boolean | "continue in children";
+export declare type RaycastTestObjectCallback = (obj: Object3D) => RaycastTestObjectReturnType;
+
+export declare interface IRaycastOptions {
+    /** Optionally a custom raycaster can be provided. Other properties will then be set on this raycaster */
+    raycaster?: Raycaster;
+    /** Optional ray that can be used for raycasting  
+     *  @link https://threejs.org/docs/#api/en/math/Ray 
+     * */
+    ray?: Ray;
+    /** The camera to use for the raycaster */
+    cam?: Camera | null;
+    /** Point on screen in raycast space / normalized device coordinates (-1 to 1).   
+     * @link https://threejs.org/docs/#api/en/core/Raycaster.setFromCamera */
+    screenPoint?: Vector2;
+    /** Raycast results array. You can provide an array here to avoid creating a new one (note that if your array already contains items they will be removed) */
+    results?: Array<Intersection>;
+    /** Objects to raycast against. If no target array is provided the whole scene will be raycasted */
+    targets?: Array<Object3D>;
+    /**
+     * If true, the raycaster will traverse the scene recursively.
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * If true, the raycaster will use a more precise method to test for intersections. This is slower but more accurate.  
+     * @default true
+     */
+    precise?: boolean;
+    /** Set the raycaster near distance:  
+     * The near factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be smaller than the far property.  
+     * @link https://threejs.org/docs/#api/en/core/Raycaster.near
+     */
+    minDistance?: number;
+    /** Set the raycaster far distance:  
+     * The far factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be larger than the near property.
+     * @link https://threejs.org/docs/#api/en/core/Raycaster.far
+     */
+    maxDistance?: number;
+    /** @link https://threejs.org/docs/#api/en/core/Raycaster.params */
+    lineThreshold?: number;
+    /** raw layer mask, use setLayer to set an individual layer active */
+    layerMask?: Layers | number;
+    ignore?: Object3D[];
+    /** Optional calback function to be called per object before tested for intersections.  
+     * This can be used to filter objects.  
+     * Return `false` to ignore the object completely or `"continue in children"` to skip the object but continue to traverse its children (if you do raycast with `recursive` enabled)  
+     * */
+    testObject?: RaycastTestObjectCallback;
+
+    /**
+     * Use MeshBVH for raycasting. This is faster than the default threejs raycaster but uses more memory.
+     * @default undefined
+     */
+    useAcceleratedRaycast?: boolean;
+}
+
+export class RaycastOptions implements IRaycastOptions {
+    public static readonly AllLayers = 0xFFFFFFFF;
+
+    ray?: Ray;
+    cam?: Camera | null;
+    screenPoint?: Vector2;
+    raycaster?: Raycaster;
+    results?: Array<Intersection>;
+    targets?: Array<Object3D>;
+    recursive?: boolean = true;
+    minDistance?: number;
+    maxDistance?: number;
+    lineThreshold?: number;
+    layerMask?: Layers | number;
+    ignore?: Object3D[];
+    testObject?: RaycastTestObjectCallback;
+    useAcceleratedRaycast?: boolean | undefined;
+
+    screenPointFromOffset(ox: number, oy: number) {
+        if (this.screenPoint === undefined) this.screenPoint = new Vector2();
+        this.screenPoint.x = ox / window.innerWidth * 2 - 1;
+        this.screenPoint.y = -(oy / window.innerHeight) * 2 + 1;
+    }
+
+    /** sets one layer for raycasting (e.g. layer 4, only objects on layer 4 will then be hit) */
+    setLayer(layer: number) {
+        layerMaskHelper.set(layer);
+        this.layerMask = layerMaskHelper;
+    }
+
+    /** sets the layer.mask value directly, use setLayer if you want to set e.g. an individual layer only active. See https://threejs.org/docs/#api/en/core/Layers for more information about layers */
+    setMask(mask: number) {
+        if (!this.layerMask) this.layerMask = new Layers();
+        const lm = this.layerMask as Layers;
+        if (lm)
+            lm.mask = mask;
+        else this.layerMask = mask;
+    }
+
+}
+
+export class SphereIntersection implements Intersection {
+    distance: number;
+    point: Vector3;
+    object: Object3D;
+    constructor(object: Object3D, distance: number, point: Vector3) {
+        this.object = object;
+        this.distance = distance;
+        this.point = point;
+    }
+}
+
+export class Physics {
+
+    private static _raycasting: number = 0;
+    /**
+     * Returns true if raycasting is currently happening
+     */
+    public static get raycasting() {
+        return this._raycasting > 0;
+    }
+
+    /**@deprecated use `this.context.physics.engine.raycast` {@link IPhysicsEngine.raycast} */
+    public raycastPhysicsFast(origin: Vec2 | Vec3, direction: Vec3 | undefined = undefined, maxDistance: number = Infinity, solid: boolean = true) {
+        return this.context.physics.engine?.raycast(origin, direction, { maxDistance, solid }) ?? null;
+    }
+
+    /**@deprecated use `this.context.physics.engine.raycastAndGetNormal` {@link IPhysicsEngine.raycastAndGetNormal} */
+    public raycastPhysicsFastAndGetNormal(origin: Vec2 | Vec3, direction: Vec3 | undefined = undefined, maxDistance: number = Infinity, solid: boolean = true) {
+        return this.context.physics.engine?.raycastAndGetNormal(origin, direction, { maxDistance, solid }) ?? null;
+    }
+
+    /**@deprecated use this.context.physics.engine.sphereOverlap */
+    public sphereOverlapPhysics(point: Vector3, radius: number) {
+        return this.context.physics.engine?.sphereOverlap(point, radius) ?? null;
+    }
+
+
+    private readonly context: Context;
+    engine?: IPhysicsEngine;
+
+    constructor(context: Context) {
+        this.context = context;
+    }
+
+    // raycasting
+    private readonly raycaster: Raycaster = new Raycaster();
+    private readonly defaultRaycastOptions: RaycastOptions = new RaycastOptions();
+    private readonly targetBuffer: Array<Object3D> = new Array<Object3D>(1);
+    private readonly defaultThresholds = {
+        Mesh: {},
+        Line: { threshold: -1 },
+        LOD: {},
+        Points: { threshold: 0 },
+        Sprite: {}
+    }
+
+
+    private sphereResults: Array<Intersection> = new Array<Intersection>();
+    private sphereMask: Layers = new Layers();
+    private readonly sphere: Sphere = new Sphere();
+    /** Test overlapping of a sphere with the threejs geometry. This does not use colliders. This does not return an exact intersection point (intersections returned contain the object and the world position of the object that is being hit)
+     * For a more accurate test use the physics engine's collider overlap test (see sphereOverlapPhysics)
+     * @param spherePos the center of the sphere in world space
+     * @param radius the radius of the sphere
+     * @param traverseChildsAfterHit if false it will stop after the first hit. If true it will continue to traverse and add all hits to the result array
+     * @param bvh use MeshBVH for raycasting. This is faster than the default threejs raycaster but uses more memory.
+     * @param shouldRaycast optional callback to filter objects. Return `false` to ignore the object completely or `"continue in children"` to skip the object but continue to traverse its children (if you do raycast with `recursive` enabled)
+     */
+    public sphereOverlap(spherePos: Vector3, radius: number, traverseChildsAfterHit: boolean = true, bvh: boolean = false, shouldRaycast: RaycastTestObjectCallback | null = null): Array<Intersection> {
+        this.sphereResults.length = 0;
+        if (!this.context.scene) return this.sphereResults;
+        const mask = this.sphereMask;
+        mask.enableAll();
+        mask.disable(2);
+        for (const ch of this.context.scene.children) {
+            this.intersectSphere(ch, spherePos, radius, mask, this.sphereResults, traverseChildsAfterHit, bvh, shouldRaycast);
+        }
+        return this.sphereResults.sort((a, b) => a.distance - b.distance);
+    }
+
+    public raycastFromRay(ray: Ray, options: IRaycastOptions | null = null): Array<Intersection> {
+        const opts = options ?? this.defaultRaycastOptions;
+        opts.ray = ray;
+        const res = this.raycast(opts);
+        // reset the default options ray
+        if (opts === this.defaultRaycastOptions) opts.ray = undefined;
+        return res;
+    }
+
+    /** raycast against rendered three objects. This might be very slow depending on your scene complexity.
+     * We recommend setting objects to IgnoreRaycast layer (2) when you don't need them to be raycasted.
+     * Raycasting SkinnedMeshes is specially expensive.
+     * Use raycastPhysics for raycasting against physic colliders only. Depending on your scenario this might be faster.
+     * @param options raycast options. If null, default options will be used.
+     */
+    public raycast(options: IRaycastOptions | null = null): Array<Intersection> {
+        if (debugPhysics) {
+            performance.mark('raycast.start');
+        }
+        if (!options) options = this.defaultRaycastOptions;
+        const mp = options.screenPoint ?? this.context.input.mousePositionRC;
+        const rc = options.raycaster ?? this.raycaster;
+        rc.near = options.minDistance ?? 0;
+        rc.far = options.maxDistance ?? Infinity;
+        rc.params = this.defaultThresholds;
+        if (options.lineThreshold === undefined) options.lineThreshold = -1;
+        rc.params.Line = { threshold: options.lineThreshold };
+        if (options.ray) {
+            rc.ray.copy(options.ray);
+        }
+        else {
+            const cam = options.cam ?? this.context.mainCamera;
+            if (!cam) {
+                if (debugPhysics)
+                    console.error("Can not perform raycast - no main camera found");
+                if (this.defaultRaycastOptions.results) this.defaultRaycastOptions.results.length = 0;
+                return this.defaultRaycastOptions.results ?? [];
+            }
+            const xrCam = this.context.xrCamera;
+            if (this.context.isInXR && xrCam instanceof ArrayCamera && xrCam.cameras.length > 0) {
+                rc.setFromCamera(mp, xrCam.cameras[0] as PerspectiveCamera);
+            }
+            else {
+                rc.setFromCamera(mp, cam);
+            }
+        }
+        let targets = options.targets;
+        if (!targets) {
+            targets = this.targetBuffer;
+            targets.length = 1;
+            targets[0] = this.context.scene;
+        }
+        let results = options.results;
+        if (this.defaultRaycastOptions.results)
+            this.defaultRaycastOptions.results.length = 0;
+        if (!results) {
+            if (!this.defaultRaycastOptions.results)
+                this.defaultRaycastOptions.results = new Array<Intersection>();
+            results = this.defaultRaycastOptions.results;
+        }
+
+        // layermask
+        // https://github.com/mrdoob/js/blob/master/src/core/Layers.js
+        if (options.layerMask !== undefined) {
+            if (options.layerMask instanceof Layers)
+                rc.layers.mask = options.layerMask.mask;
+            else
+                rc.layers.mask = options.layerMask;
+        }
+        else {
+            rc.layers.enableAll();
+            rc.layers.disable(2);
+        }
+
+        if (debugPhysics) {
+            // Gizmos.DrawRay(rc.ray.origin, rc.ray.direction, 0xff0000, .2);
+            console.time("raycast");
+        }
+
+        // shoot
+        results.length = 0;
+        Physics._raycasting++;
+        this.intersect(this.raycaster, targets, results, options);
+        results.sort((a, b) => a.distance - b.distance);
+
+        // TODO: instead of doing this we should temporerly set these objects to layer 2 during raycasting
+        const ignorelist = options.ignore;
+        if (ignorelist !== undefined && ignorelist.length > 0) {
+            results = results.filter(r => !ignorelist.includes(r.object));
+        }
+
+        Physics._raycasting--;
+
+        if (debugPhysics) {
+            console.timeEnd("raycast");
+            console.warn("#" + this.context.time.frame + ", hits:", (results?.length ? [...results] : "nothing"));
+            performance.mark('raycast.end');
+            performance.measure('raycast', 'raycast.start', 'raycast.end');
+        }
+
+        return results;
+    }
+
+    private intersect(raycaster: Raycaster, objects: Object3D[], results: Intersection[], options: IRaycastOptions) {
+        for (const obj of objects) {
+
+            // handle case where null or undefined object is in the scene
+            if (!obj) continue;
+            // dont raycast invisible objects
+            if (obj.visible === false) continue;
+
+            if (Gizmos.isGizmo(obj)) continue;
+
+            // dont raycast object if it's a line and the line threshold is < 0
+            if (options.lineThreshold !== undefined && options.lineThreshold < 0) {
+                if (obj instanceof Line) {
+                    continue;
+                }
+            }
+
+            let shouldIntersectObject = true;
+            const mesh = obj as Mesh | SkinnedMesh;
+            const geo = mesh.geometry;
+
+            // We need to run this first because of "EventSystem.testObject" implementation
+            if (options.testObject) {
+                const testResult = options.testObject?.(obj);
+                if (testResult === false) {
+                    continue;
+                }
+                else if (testResult === "continue in children") {
+                    shouldIntersectObject = false;
+                }
+            }
+
+            if (shouldIntersectObject) {
+                if (!geo) {
+                    shouldIntersectObject = false;
+                }
+                // check if the geometry is valid
+                else if (!canRaycastGeometry(geo)) {
+                    shouldIntersectObject = false;
+                }
+            }
+
+
+            if (shouldIntersectObject) {
+                const raycastMesh = getRaycastMesh(obj);
+                if (raycastMesh) mesh.geometry = raycastMesh as any;
+                const lastResultsCount = results.length;
+
+                let usePrecise = true;
+                if (options.precise === false) usePrecise = false;
+                usePrecise ||= geo.getAttribute("position")?.array?.length < 64;
+                if (mesh instanceof GroundedSkybox) {
+                    usePrecise = false;
+                }
+
+                if (!usePrecise && customRaycast(mesh, raycaster, results)) {
+                    // did handle raycast
+                }
+                else if (options.useAcceleratedRaycast !== false) {
+                    NEMeshBVH.runMeshBVHRaycast(raycaster, mesh, results, this.context);
+                }
+                else {
+                    raycaster.intersectObject(mesh, false, results);
+                }
+
+                if (debugPhysics && results.length != lastResultsCount) {
+                    const latestResult = results[results.length - 1];
+                    const col = raycastMesh ? 0x88dd55 : 0x770000;
+                    Gizmos.DrawWireSphere(latestResult.point, .1, col, 1, false);
+                    Gizmos.DrawWireMesh({ mesh: obj as Mesh, depthTest: false, duration: .2, color: col });
+                }
+                mesh.geometry = geo;
+            }
+
+            if (options.recursive !== false) {
+                this.intersect(raycaster, obj.children, results, options);
+            }
+        }
+        return results;
+    }
+
+    private tempBoundingBox: Box3 = new Box3();
+    private intersectSphere(obj: Object3D, spherePos: Vector3, radius: number, mask: Layers, results: Array<Intersection>, traverseChildsAfterHit: boolean, useBvh: boolean, shouldRaycast: RaycastTestObjectCallback | null): void {
+
+        let shouldIntersectObject = obj && (obj as Mesh).isMesh && obj.layers.test(mask) && !Gizmos.isGizmo(obj);
+
+        shouldIntersectObject &&= obj.visible;
+        shouldIntersectObject &&= !(obj instanceof Line);
+        shouldIntersectObject &&= !(obj instanceof GroundedSkybox);
+
+        const mesh = obj as Mesh;
+        const geo = mesh.geometry;
+
+        if (shouldIntersectObject && shouldRaycast) {
+            const testResult = shouldRaycast(obj);
+            if (testResult === false) {
+                return;
+            }
+            else if (testResult === "continue in children") {
+                shouldIntersectObject = false;
+            }
+        }
+
+        // check if geometry exists
+        if (!geo) {
+            shouldIntersectObject = false;
+        }
+        // check if the geometry is valid
+        else if (!canRaycastGeometry(geo)) {
+            shouldIntersectObject = false;
+        }
+
+
+        if (shouldIntersectObject) {
+            if (useBvh) {
+                const sphere = this.sphere;
+                sphere.center.copy(spherePos);
+                sphere.radius = radius;
+                const previousResults = results.length;
+                NEMeshBVH.runMeshBVHRaycast(this.sphere, mesh, results, this.context);
+                if (previousResults != results.length && !traverseChildsAfterHit) {
+                    return;
+                }
+            }
+            // Classic sphere intersection test
+            else {
+                if (!geo.boundingBox)
+                    geo.computeBoundingBox();
+
+                if (geo.boundingBox) {
+                    if (mesh.matrixWorldNeedsUpdate) mesh.updateWorldMatrix(false, false);
+                    const test = this.tempBoundingBox.copy(geo.boundingBox).applyMatrix4(mesh.matrixWorld);
+                    const sphere = this.sphere;
+                    sphere.center.copy(spherePos);
+                    sphere.radius = radius;
+
+                    if (sphere.intersectsBox(test)) {
+                        const wp = getWorldPosition(obj);
+                        const dist = wp.distanceTo(sphere.center);
+                        const int = new SphereIntersection(obj, dist, wp);
+                        results.push(int);
+                        if (!traverseChildsAfterHit) return;
+                    }
+                }
+            }
+        }
+
+
+        if (obj.children) {
+            for (const ch of obj.children) {
+                const len = results.length;
+                this.intersectSphere(ch, spherePos, radius, mask, results, traverseChildsAfterHit, useBvh, shouldRaycast);
+                if (len != results.length && !traverseChildsAfterHit) return;
+            }
+        }
+    }
+}
+
+/**
+ * See https://linear.app/needle/issue/NE-5524
+ * @returns true if the geometry can be raycasted
+ */
+function canRaycastGeometry(geo: BufferGeometry): boolean {
+    // if the geometry has an index buffer but no indices, we can't raycast
+    if (geo.index && geo.index.array.length < 3) return false;
+    // we might want to test if the geometry has a position buffer
+    return true;
+}
+
+
+const tempSphere = new Sphere();
+const tempPlane = new Plane();
+const normalUpMatrix = new Matrix3();
+
+/**
+ * @returns false if custom raycasting can not run, otherwise true
+ */
+function customRaycast(mesh: Mesh, raycaster: Raycaster, results: Intersection[]): boolean {
+    const originalComputeIntersectionsFn = mesh["_computeIntersections"];
+    if (!originalComputeIntersectionsFn) {
+        return false;
+    }
+
+    // compute custom intersection, check if a custom method already exists
+    let computeCustomIntersectionFn = mesh["_computeIntersections:Needle"];
+    if (!computeCustomIntersectionFn) {
+        // create and bind a custom method once to the mesh object
+        // TODO: maybe we want to add this to the prototype instead
+        computeCustomIntersectionFn = mesh["_computeIntersections:Needle"] = function (raycaster: Raycaster, intersects: Intersection[], _rayLocalSpace: Ray) {
+            const self = this as Mesh;
+            const boundingSphere = self.geometry.boundingSphere;
+            if (boundingSphere) {
+
+                if (self instanceof GroundedSkybox) {
+                    tempPlane.setFromNormalAndCoplanarPoint(getTempVector(0, 1, 0), getTempVector(0, -self.position.y, 0));
+                    tempPlane.applyMatrix4(self.matrixWorld, normalUpMatrix);
+                    const point = raycaster.ray.intersectPlane(tempPlane, getTempVector());
+                    if (point) {
+                        tempSphere.copy(boundingSphere);
+                        tempSphere.applyMatrix4(self.matrixWorld);
+                        const dir = getTempVector(point).sub(raycaster.ray.origin);
+                        const distance = dir.length();
+                        const groundProjectionFloorRadius = tempSphere.radius * .5;
+                        if (distance < groundProjectionFloorRadius) // make sure we're inside the sphere
+                            intersects.push({ distance: distance, point, object: self, normal: tempPlane.normal.clone() });
+                    }
+                    return;
+                }
+
+                tempSphere.copy(boundingSphere);
+                tempSphere.applyMatrix4(self.matrixWorld);
+                const point = raycaster.ray.intersectSphere(tempSphere, getTempVector());
+                if (point) {
+                    const dir = getTempVector(point).sub(raycaster.ray.origin);
+                    const distance = dir.length();
+                    // Ignore hits when we're inside the sphere
+                    if (distance > tempSphere.radius) {
+                        const normal = dir.clone().normalize();
+                        intersects.push({ distance: distance, point, object: self, normal });
+                    }
+                }
+            }
+        }
+    }
+    mesh["_computeIntersections"] = computeCustomIntersectionFn;
+    raycaster.intersectObject(mesh, false, results);
+    mesh["_computeIntersections"] = originalComputeIntersectionsFn;
+    return true;
+}
+
+
+
+declare module 'three' {
+    interface SkinnedMesh {
+        staticGenerator?: StaticGeometryGenerator;
+        staticGeometry?: BufferGeometry;
+        staticGeometryLastUpdate?: number;
+    }
+    interface Mesh {
+        acceleratedRaycast?: any;
+    }
+    export interface SkinnedMesh {
+        autoUpdateMeshBVH?: boolean;
+        bvhNeedsUpdate?: boolean;
+    }
+}
+
+
+
+namespace NEMeshBVH {
+    export function runMeshBVHRaycast(method: Raycaster | Sphere, mesh: Mesh, results: Intersection[], context: Pick<Context, "xr">): boolean {
+        if (!mesh.geometry) {
+            return false;
+        }
+        // Completely prevent raycasting on object that has no position
+        if (!mesh.geometry.hasAttribute('position')) {
+            return false;
+        }
+        // The code below handles generating the mesh bvh structure that is used for raycasting
+        // We first try to setup workers so it can run off the main thread
+        const geom = mesh.geometry;
+
+        if ((mesh as SkinnedMesh)?.isSkinnedMesh) {
+            const skinnedMesh = mesh as SkinnedMesh;
+            const skinnedMeshBVHNeedsUpdate = skinnedMesh.bvhNeedsUpdate;
+            if (!skinnedMesh.staticGenerator) {
+                loadMeshBVHLibrary();
+                if (_StaticGeometryGenerator) {
+                    skinnedMesh.staticGenerator = new _StaticGeometryGenerator(mesh);
+                    skinnedMesh.staticGenerator.applyWorldTransforms = false;
+                    skinnedMesh.staticGeometry = skinnedMesh.staticGenerator.generate();
+                    geom.boundsTree = _computeBoundsTree?.call(skinnedMesh.staticGeometry);
+                    skinnedMesh.staticGeometryLastUpdate = performance.now() + Math.random() * 200;
+                    if (skinnedMesh.autoUpdateMeshBVH === undefined)
+                        skinnedMesh.autoUpdateMeshBVH = false;
+                }
+            }
+            else if (geom.boundsTree && (skinnedMesh.autoUpdateMeshBVH === true || skinnedMeshBVHNeedsUpdate === true)) {
+                // automatically refit the tree every 300ms
+                const now = performance.now();
+                const timeSinceLastUpdate = now - skinnedMesh.staticGeometryLastUpdate!;
+                if (skinnedMeshBVHNeedsUpdate || timeSinceLastUpdate > 100) {
+                    skinnedMesh.bvhNeedsUpdate = false;
+                    skinnedMesh.staticGeometryLastUpdate = now;
+                    skinnedMesh.staticGenerator?.generate(skinnedMesh.staticGeometry);
+                    geom.boundsTree.refit();
+                }
+            }
+        }
+
+        else if (!geom.boundsTree) {
+
+            // Try to generate the bvh on a worker
+            if (!didSetupWorker) internalSetupWorker();
+
+            let canUseWorker = true;
+
+            if (context.xr) { // < in XR for some reason sometimes geometry (controllers) are broken - maybe this is not exclusive to controller geometry
+                canUseWorker = false;
+            }
+            else if (geom[canUseWorkerSymbol] === false) {
+                canUseWorker = false;
+            }
+            else if (geom.getAttribute('position')?.["isInterleavedBufferAttribute"]
+                || geom.index && geom.index?.["isInterleavedBufferAttribute"]) {
+                canUseWorker = false;
+            }
+
+            // if we have a worker use that
+            if (canUseWorker && _GenerateMeshBVHWorker) {
+                if (geom[workerTaskSymbol] === undefined) {
+
+                    // get available worker
+                    let workerInstance: GenerateMeshBVHWorker | null = null;
+                    // if there are workers available, use one
+                    if (availableWorkers.length > 0) {
+                        const available = availableWorkers.shift();
+                        if (available && !available.running) {
+                            workerInstance = available;
+                        }
+                    }
+                    // if there are no workers available, create a new one
+                    if (!workerInstance && workerInstances.length < 3) {
+                        workerInstance = new _GenerateMeshBVHWorker();
+                        workerInstances.push(workerInstance);
+                    }
+
+                    if (workerInstance != null && !workerInstance.running) {
+                        const name = mesh.name;
+                        if (debugPhysics) console.log("<<<< worker start", name, workerInstance);
+                        geom[workerTaskSymbol] = "queued";
+                        performance.mark("bvh.create.start");
+                        // If we don't clone the buffer geometry here we will get a "Transferable ArrayBuffer" error
+                        // see https://linear.app/needle/issue/NE-5602
+                        // Additionally normal raycasts stop working if we don't clone the geometry
+                        const copy = geom.clone();
+                        try {
+                            workerInstance.generate(copy)
+                                .then(bvh => {
+                                    geom[workerTaskSymbol] = "done";
+                                    geom.boundsTree = bvh;
+                                })
+                                .catch(err => {
+                                    geom[workerTaskSymbol] = "failed - " + err?.message;
+                                    geom[canUseWorkerSymbol] = false;
+                                    if (debugPhysics) console.error("Failed to generate mesh bvh on worker", err);
+                                })
+                                .finally(() => {
+                                    if (debugPhysics) console.log(">>>>> worker done", name, { hasBoundsTre: geom.boundsTree != undefined });
+                                    availableWorkers.push(workerInstance);
+                                    copy.dispose();
+                                    performance.mark("bvh.create.end");
+                                    performance.measure("bvh.create (worker)", "bvh.create.start", "bvh.create.end");
+                                });
+                        }
+                        catch (err) {
+                            console.error("Failed to generate mesh bvh on worker", err);
+                        }
+                    }
+                    else {
+                        // we don't want to generate the BVH on the main thread unless workers are not supported
+                        // If all workers are currently running we need to run a "slow" raycast
+                        if (debugPhysics) console.warn("No worker available");
+                    }
+                }
+            }
+            // Fallback to sync bvh generation if workers are not available
+            else if (!isRequestingWorker || !canUseWorker) {
+                loadMeshBVHLibrary();
+                if (_MeshBVH) {
+                    performance.mark("bvh.create.start");
+                    geom.boundsTree = new _MeshBVH(geom as BufferGeometry);
+                    performance.mark("bvh.create.end");
+                    performance.measure("bvh.create", "bvh.create.start", "bvh.create.end");
+                }
+            }
+        }
+
+        if (method instanceof Raycaster) {
+            const raycaster = method;
+            // Skinned meshes work when we disable applyWorldTransform in the generator (see applyWorldTransforms = false above)
+            // We do need to set the accelerated raycast method (bind it once)
+            // We could also override it on the prototype - not sure if it's more performant but then it would always run
+            const raycastMesh = mesh.raycast;
+            if (geom.boundsTree) {
+                loadMeshBVHLibrary();
+                if (_acceleratedRaycast) {
+                    // bind the raycast to the mesh
+                    if (!mesh.acceleratedRaycast) {
+                        mesh.acceleratedRaycast = _acceleratedRaycast.bind(mesh) as any;
+                        if (debugPhysics) console.debug(`Physics: bind acceleratedRaycast fn to \"${mesh.name}\"`);
+                    }
+                    mesh.raycast = mesh.acceleratedRaycast;
+                }
+            }
+            else {
+                if (debugPhysics) console.warn("No bounds tree found for mesh", mesh.name, { workerTask: geom[workerTaskSymbol], hasAcceleratedRaycast: _acceleratedRaycast != null });
+            }
+            const prevFirstHitOnly = raycaster.firstHitOnly;
+            raycaster.firstHitOnly = false;
+            raycaster.intersectObject(mesh, false, results);
+            raycaster.firstHitOnly = prevFirstHitOnly;
+            mesh.raycast = raycastMesh;
+            return true;
+        }
+        else if (method instanceof Sphere) {
+            const bvh = geom.boundsTree;
+            if (bvh) {
+                const sphere = method;
+                // Gizmos.DrawWireSphere(sphere.center, sphere.radius, 0xdddd00, 1, false);
+
+                invMat.copy(mesh.matrixWorld).invert();
+                sphere.applyMatrix4(invMat);
+                const intersects = bvh.intersectsSphere(sphere);
+                if (intersects) {
+                    // console.log(intersects, mesh.name);
+                    const worldpos = getWorldPosition(mesh);
+                    const distance = worldpos.distanceTo(sphere.center);
+                    const intersection = new SphereIntersection(mesh, distance, worldpos);
+                    results.push(intersection);
+                }
+            }
+            return true;
+        }
+
+
+        return false;
+    }
+
+    let didLoadMeshBVHLibrary: boolean = false;
+    let _acceleratedRaycast: Function | null = null;
+    let _MeshBVH: ConstructorConcrete<MeshBVH> | null = null;
+    let _StaticGeometryGenerator: ConstructorConcrete<StaticGeometryGenerator> | null = null;
+    let _computeBoundsTree: ((_opt?: MeshBVHOptions) => MeshBVH) | null = null;
+
+    function loadMeshBVHLibrary() {
+        if (didLoadMeshBVHLibrary) return;
+        didLoadMeshBVHLibrary = true;
+        import("three-mesh-bvh").then(res => {
+            _acceleratedRaycast = res.acceleratedRaycast;
+            _MeshBVH = res.MeshBVH;
+            _StaticGeometryGenerator = res.StaticGeometryGenerator;
+            _computeBoundsTree = res.computeBoundsTree;
+        }).catch(_err => {
+            if (debugPhysics || isDevEnvironment()) {
+                console.error("Failed to load BVH library...", _err.message);
+            }
+        })
+    }
+
+
+    const invMat = new Matrix4();
+
+    /** True after the worker has been requested for the first time */
+    let didSetupWorker: boolean = false;
+    /** True while the worker is being requested */
+    let isRequestingWorker: boolean = false;
+    let _GenerateMeshBVHWorker: ConstructorConcrete<GenerateMeshBVHWorker> | null = null;
+
+    const workerTaskSymbol = Symbol("Needle:MeshBVH-Worker");
+    const canUseWorkerSymbol = Symbol("Needle:MeshBVH-CanUseWorker");
+    const workerInstances: GenerateMeshBVHWorker[] = [];
+    const availableWorkers: GenerateMeshBVHWorker[] = [];
+
+    function internalSetupWorker() {
+        didSetupWorker = true;
+        isRequestingWorker = true;
+        // Using local worker. see https://github.com/gkjohnson/three-mesh-bvh/issues/636#issuecomment-2209571751
+        import("./physics/workers/mesh-bvh/GenerateMeshBVHWorker.js")
+            .then(res => {
+                _GenerateMeshBVHWorker = res.GenerateMeshBVHWorker;
+            })
+            .catch(_err => {
+                if (debugPhysics || isDevEnvironment()) {
+                    console.warn("Failed to setup mesh bvh worker");
+                }
+            })
+            .finally(() => {
+                isRequestingWorker = false;
+            });
+    }
+
+
+}