@liveroom-tech/react-immersive 1.2.1 → 1.3.0

package/README.md

@@ -1802,6 +1802,39 @@ To use this library successfully, your GLB/GLTF asset should follow these expect
 
 If a node name or material name does not match, that object will not render through the interactive binding flow.
 
+### Large models
+
+Viewport picking (click/hover) is accelerated by a BVH index built in a
+background worker, so even multi-million-triangle models stay responsive to
+the pointer. Models above roughly **12 million triangles** are too large to
+index without a significant memory cost, and the viewer degrades gracefully
+instead of freezing:
+
+- viewport click/hover picking is disabled (`onObjectSelect` / `onObjectHover`
+  do not fire from the canvas); selection through the scene objects panel
+  still works
+- a dismissible banner tells the user the model is very large, may render
+  slowly on their device, and that selection is available through the panel
+- the loading overlay calls out the extra work — uploading that much geometry
+  to the GPU is a single synchronous operation that can block the page for
+  tens of seconds in any WebGL viewer
+
+Orbit, zoom, animations, annotations, and the panels keep working. There is no
+viewer-side way to make models of this size feel fast — the per-frame cost is
+inherent, and on mobile devices the decoded geometry alone can exceed the
+tab's memory budget. Decimate such assets at ingestion (to roughly 2–3M
+triangles) instead of shipping the raw export; note that very large
+Draco-compressed files need Blender or native tooling to decimate — the WASM
+builds of `gltf-transform` and `gltfpack` cannot decode them within their 4GB
+address space.
+
+Two related picking notes that apply to models of every size:
+
+- clicks resolve the front-most surface under the pointer; a mesh with
+  `selectable: false` does not pass the click through to meshes behind it
+- `SimpleModelViewer` renders on demand — an idle viewer draws no frames, so
+  it costs no GPU time or battery until something changes
+
 ## License
 
 Proprietary — see [LICENSE](./LICENSE). Installing the package does not itself grant a right to use it in production; a valid `licenseKey` from the [Developer Portal](https://react-immersive.liveroom.dev) is required, and usage is bound to the terms of your license tier.