@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
646 lines • 30.4 kB
JavaScript
import { getRaycastMesh } from '@needle-tools/gltf-progressive';
import { ArrayCamera, Box3, Layers, Line, Matrix3, Matrix4, Plane, Raycaster, Sphere, Vector2 } from 'three';
import { GroundedSkybox } from 'three/examples/jsm/objects/GroundedSkybox.js';
import { isDevEnvironment } from './debug/index.js';
import { Gizmos } from './engine_gizmos.js';
import { getTempVector, getWorldPosition } from "./engine_three_utils.js";
import { getParam } from "./engine_utils.js";
const debugPhysics = getParam("debugphysics");
const layerMaskHelper = new Layers();
export class RaycastOptions {
static AllLayers = 0xFFFFFFFF;
ray;
cam;
screenPoint;
raycaster;
results;
targets;
recursive = true;
minDistance;
maxDistance;
lineThreshold;
layerMask;
ignore;
testObject;
useAcceleratedRaycast;
screenPointFromOffset(ox, oy) {
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) {
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) {
if (!this.layerMask)
this.layerMask = new Layers();
const lm = this.layerMask;
if (lm)
lm.mask = mask;
else
this.layerMask = mask;
}
}
export class SphereIntersection {
distance;
point;
object;
constructor(object, distance, point) {
this.object = object;
this.distance = distance;
this.point = point;
}
}
export class Physics {
static _raycasting = 0;
/**
* Returns true if raycasting is currently happening
*/
static get raycasting() {
return this._raycasting > 0;
}
/**@deprecated use `this.context.physics.engine.raycast` {@link IPhysicsEngine.raycast} */
raycastPhysicsFast(origin, direction = undefined, maxDistance = Infinity, solid = true) {
return this.context.physics.engine?.raycast(origin, direction, { maxDistance, solid }) ?? null;
}
/**@deprecated use `this.context.physics.engine.raycastAndGetNormal` {@link IPhysicsEngine.raycastAndGetNormal} */
raycastPhysicsFastAndGetNormal(origin, direction = undefined, maxDistance = Infinity, solid = true) {
return this.context.physics.engine?.raycastAndGetNormal(origin, direction, { maxDistance, solid }) ?? null;
}
/**@deprecated use this.context.physics.engine.sphereOverlap */
sphereOverlapPhysics(point, radius) {
return this.context.physics.engine?.sphereOverlap(point, radius) ?? null;
}
context;
engine;
constructor(context) {
this.context = context;
}
// raycasting
raycaster = new Raycaster();
defaultRaycastOptions = new RaycastOptions();
targetBuffer = new Array(1);
defaultThresholds = {
Mesh: {},
Line: { threshold: -1 },
LOD: {},
Points: { threshold: 0 },
Sprite: {}
};
sphereResults = new Array();
sphereMask = new Layers();
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)
*/
sphereOverlap(spherePos, radius, traverseChildsAfterHit = true, bvh = false, shouldRaycast = null) {
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);
}
raycastFromRay(ray, options = null) {
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.
*/
raycast(options = null) {
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]);
}
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();
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;
}
intersect(raycaster, objects, results, options) {
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;
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;
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, depthTest: false, duration: .2, color: col });
}
mesh.geometry = geo;
}
if (options.recursive !== false) {
this.intersect(raycaster, obj.children, results, options);
}
}
return results;
}
tempBoundingBox = new Box3();
intersectSphere(obj, spherePos, radius, mask, results, traverseChildsAfterHit, useBvh, shouldRaycast) {
let shouldIntersectObject = obj && obj.isMesh && obj.layers.test(mask) && !Gizmos.isGizmo(obj);
shouldIntersectObject &&= obj.visible;
shouldIntersectObject &&= !(obj instanceof Line);
shouldIntersectObject &&= !(obj instanceof GroundedSkybox);
const mesh = obj;
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) {
// 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, raycaster, results) {
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, intersects, _rayLocalSpace) {
const self = this;
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;
}
var NEMeshBVH;
(function (NEMeshBVH) {
function runMeshBVHRaycast(method, mesh, results, context) {
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?.isSkinnedMesh) {
const skinnedMesh = mesh;
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 = 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);
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);
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;
}
NEMeshBVH.runMeshBVHRaycast = runMeshBVHRaycast;
let didLoadMeshBVHLibrary = false;
let _acceleratedRaycast = null;
let _MeshBVH = null;
let _StaticGeometryGenerator = null;
let _computeBoundsTree = 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 = false;
/** True while the worker is being requested */
let isRequestingWorker = false;
let _GenerateMeshBVHWorker = null;
const workerTaskSymbol = Symbol("Needle:MeshBVH-Worker");
const canUseWorkerSymbol = Symbol("Needle:MeshBVH-CanUseWorker");
const workerInstances = [];
const availableWorkers = [];
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;
});
}
})(NEMeshBVH || (NEMeshBVH = {}));
//# sourceMappingURL=engine_physics.js.map