@gadxr/aframe-bvh 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arsra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @gadxr/aframe-bvh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fast raycasts against big static meshes in A-Frame, with
+[three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh). A bounding volume hierarchy lets a
+ray test a handful of triangles instead of every one, which matters for teleport: `blink-controls`
+casts 10–20 short rays per frame while you aim, and without a tree each tests every triangle of
+every collision mesh it comes near.
+
+```js
+import 'aframe';      // first: this package patches A-Frame's three.js
+import '@gadxr/aframe-bvh';
+```
+
+```html
+<a-entity gltf-model="#scan" class="floor" bvh></a-entity>
+```
+
+- Importing it patches `THREE.Mesh.prototype.raycast` for the whole page. Meshes without a tree
+  raycast exactly as before, so the UI lasers and everything else are unaffected.
+- `bvh` builds a tree for every mesh under its entity, including child entities and meshes set
+  later (a model that finishes loading). Building costs time once per mesh: about 4 ms for 2k triangles, 130 ms for 500k triangles, measured on an M-series Mac.
+- Only for meshes whose vertices don't change afterwards: the tree isn't rebuilt. (A geometry
+  that's replaced raycasts the old way until something sets a mesh on the entity again.)
+
+## One three.js
+
+three-mesh-bvh imports `'three'` and has to get the copy A-Frame renders with. With A-Frame from
+npm that's `super-three`, which this package depends on as `three` at A-Frame 1.8's version, so
+pnpm gives three-mesh-bvh the same package: no config needed. Keep that version A-Frame's when
+upgrading A-Frame; otherwise the page gets a second three.js and this warns
+`three-mesh-bvh got a different three.js than A-Frame's`.
+
+A page that loads A-Frame with a script tag aliases `'three'` in its Vite config
+to a module that re-exports the global `THREE` (`src/three-global.js`).

package/index.d.ts

@@ -0,0 +1,2 @@
+// Patches A-Frame's three.js and registers the `bvh` component on the global AFRAME; exports nothing.
+export {};

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@gadxr/aframe-bvh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Fast raycasts against big static meshes (teleport, navmesh walking) in A-Frame, with three-mesh-bvh.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gad-sh/xr-kit.git",
+    "directory": "packages/aframe-bvh"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "sideEffects": true,
+  "files": [
+    "src",
+    "index.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "three": "npm:super-three@0.184.0",
+    "three-mesh-bvh": "^0.9.16"
+  },
+  "peerDependencies": {
+    "aframe": "^1.8.0"
+  }
 }

package/src/index.js

@@ -0,0 +1,36 @@
+// Fast raycasts against big static meshes with three-mesh-bvh: a bounding volume hierarchy lets a
+// ray test a few triangles instead of all of them (teleport arcs cast many short rays every frame).
+// Importing this patches A-Frame's three.js once, for every raycast in the page; meshes without
+// a tree raycast exactly as before. Put `bvh` on an entity to build trees for its meshes.
+import { Mesh } from 'three';
+import { acceleratedRaycast, computeBoundsTree, disposeBoundsTree } from 'three-mesh-bvh';
+
+// three-mesh-bvh has to extend the three.js A-Frame renders with. With npm A-Frame that's
+// super-three, which this package depends on as 'three' (keep its version A-Frame's); a page
+// that loads A-Frame with a script tag aliases 'three' to the global instead.
+const { THREE } = AFRAME;
+if (Mesh !== THREE.Mesh) console.warn("aframe-bvh: three-mesh-bvh got a different three.js than A-Frame's");
+THREE.BufferGeometry.prototype.computeBoundsTree = computeBoundsTree;
+THREE.BufferGeometry.prototype.disposeBoundsTree = disposeBoundsTree;
+THREE.Mesh.prototype.raycast = acceleratedRaycast;
+
+// Builds a tree for every mesh under the entity, now and whenever one is set (`object3dset`
+// bubbles up from child entities). Only for meshes whose vertices don't move afterwards:
+// the tree isn't rebuilt when they change (a replaced geometry just raycasts the old way).
+AFRAME.registerComponent('bvh', {
+  // No options: a single property, so a bare `bvh` attribute parses without a warning.
+  schema: { type: 'boolean', default: true },
+  init() {
+    this.build = this.build.bind(this);
+    this.el.addEventListener('object3dset', this.build);
+    this.build();
+  },
+  remove() {
+    this.el.removeEventListener('object3dset', this.build);
+  },
+  build() {
+    this.el.object3D.traverse((o) => {
+      if (o.isMesh && !o.geometry.boundsTree && o.geometry.attributes.position) o.geometry.computeBoundsTree();
+    });
+  },
+});