three-virtual-geometry 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+Guidance for AI coding agents working on this repository. To **use** the library in another project, read
+[docs/public/llms.txt](docs/public/llms.txt) instead.
+
+## What this is
+
+three-virtual-geometry: virtual geometry (a cluster LOD hierarchy with GPU-driven selection and culling) for
+three.js WebGPU, written in TypeScript with TSL compute shaders. An independent implementation, not affiliated with
+Epic Games. Do not copy code from, or describe this as derived from, any proprietary engine.
+
+## Commands
+
+```bash
+npm install
+npm run dev          # demo at http://localhost:8090 (?scene=ruins|map|world|import|stress|test)
+npm test             # vitest: DAG invariants, partitioner, serialization, import grouping (Node, no GPU)
+npm run typecheck    # tsc --noEmit
+npm run build        # library (dist/index.js + .d.ts) and the vg-bake CLI (dist/bake.mjs)
+npm run build:demo   # demo into dist-demo/
+npm run docs:dev     # VitePress docs site; the embedded demo player (/live) loads the demo from `npm run dev`
+npm run bench        # uncapped FPS of every demo scene in Chrome (Playwright) -> docs/benchmarks.json
+```
+
+GPU code can only be checked in a WebGPU browser. After runtime changes, load the demo scenes and check the console
+for WebGPU validation errors and the HUD for `overflow`.
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `src/index.ts` | Public API. Everything users import is re-exported here. |
+| `src/source.ts` | `fromBufferGeometry`, `mergeSources`: three.js geometry to a welded `VirtualMeshSource`. |
+| `src/core/preprocess/buildVirtualMesh.ts` | Builds the cluster DAG (meshoptimizer clusterize and simplify, with locked borders). |
+| `src/core/preprocess/partition.ts` | Groups meshlets by shared edges. |
+| `src/core/preprocess/voxelProxy.ts` | Voxel proxy surfaces for coarse levels of aggregate geometry. |
+| `src/core/io/serialize.ts` | `.vgeo` binary format. |
+| `src/core/io/cache.ts` | IndexedDB build cache. Bump `VG_BUILD_VERSION` when build output changes. |
+| `src/core/runtime/VirtualGeometry.ts` | Context: settings, pools, per-frame update, stats, threshold controller. |
+| `src/core/runtime/GeometryPool.ts` | Shared buffers for many meshes and the compute passes (cells, instances, meshlets, prefix, expand). |
+| `src/core/runtime/VirtualMesh.ts` | A three.js `Mesh` that draws its region of a pool with an indirect draw. |
+| `src/core/runtime/OcclusionCulling.ts` | Depth pre-pass, hierarchical depth buffer, automatic on/off tuning. |
+| `src/core/runtime/vgMaterial.ts` | `vgUv`, `vgTexture` and material rewiring. |
+| `src/core/runtime/cut.ts` | CPU reference of the GPU selection, used by tests. |
+| `src/core/import/` | `vg.add()`: grouping an `Object3D` into instanced meshes, material conversion. |
+| `scripts/bake.ts` | The `vg-bake` CLI. |
+| `examples/` | Demo app (Vite root). Scenes are generated procedurally in `examples/demo/`. |
+| `docs/` | VitePress site, deployed with the demo to GitHub Pages. |
+
+## Invariants
+
+- A meshlet is drawn when `projectedError <= threshold < projectedParentError`. Errors must grow monotonically up
+  the DAG; `tests/preprocess.test.ts` checks it. Breaking it causes holes or overlaps.
+- Meshlets have at most 128 triangles (`MAX_MESHLET_TRIANGLES`); the draw index encodes `slot << 7 | local`.
+- Storage-buffer bindings must stay under 128 MB: pools cap their buffers by `maxPoolBytes`.
+- In compute shaders, `workgroupBarrier()` must be reached in uniform control flow: no early return before it.
+- If the build output changes, bump `VG_BUILD_VERSION` and update the fingerprint in `tests/buildversion.test.ts`.
+
+## Conventions
+
+- TypeScript, 2-space indentation, single quotes. Keep the public API small and stable, and document new options in
+  `docs/` and `llms.txt`.
+- The engine decides how to render, never what: new optimizations must be automatic with an opt-out setting, not
+  something users must call.
+- Use three.js and meshoptimizer for what they already do instead of reimplementing it.

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Elad Ben-Haim
+
+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.
+
+Portions of this software are derived from nanite-webgpu; see THIRD_PARTY_NOTICES.md.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# three-virtual-geometry
 
-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.
+**Virtual geometry for three.js WebGPU.** Put in your models at full detail. The engine draws only the triangles
+you can see: about one per pixel, wherever you are.
+
+[**Live demo**](https://elad12390.github.io/three-virtual-geometry/live) ·
+[**Docs**](https://elad12390.github.io/three-virtual-geometry/) ·
+[API](https://elad12390.github.io/three-virtual-geometry/api) ·
+[Use it from a CDN](#use-it-from-a-cdn-no-build-step) ·
+[Set it up with your AI agent](#set-it-up-with-your-ai-agent)
+
+**Measured results** (uncapped, no vsync, shadows on; MacBook Pro with an M4 Pro, Chrome 154):
+
+- **5.7 billion triangles** in the ruins scene at **160 to 230 FPS** at 1080p, and 103 to 158 FPS at 4K.
+- **37.5 billion triangles in 3 million instances** (a 6 km world) at **147 to 150 FPS** at 1080p.
+- **1 million instances** (39.5 billion triangles) at **177 FPS** or more at 1080p.
+- **Over 100 FPS in every scene and camera view, even at 4K**, with at most 0.6 ms of CPU time per frame.
+
+![An ancient city of 5.7 billion triangles drawn with about 8 million](docs/public/screenshots/ruins-wide.jpg)
+
+| | |
+| --- | --- |
+| ![Close-up: every brick and carving is real geometry](docs/public/screenshots/ruins-closeup.jpg) | ![Clusters colored by detail level](docs/public/screenshots/world-meshlets.jpg) |
+| ![3 million instances over 6 km](docs/public/screenshots/world.jpg) | ![Textured glTF models converted with one call](docs/public/screenshots/import.jpg) |
+
+- **One line to adopt.** `await vg.add(gltf.scene)` converts every static mesh, with its materials and textures.
+- **Billions of triangles.** The ruins scene holds 5.7 billion and draws 7 to 9 million a frame, at 160 to 230 FPS
+  at 1080p on a MacBook Pro (M4 Pro).
+- **No visible LOD switching.** Detail changes cluster by cluster, below one pixel of error. No hand-made LODs.
+- **GPU-driven.** Frustum, size and occlusion culling and level selection run in compute shaders. One draw call
+  per mesh, millions of instances.
+- **Everything three.js.** Node materials, lights, shadows, fog and tone mapping work unchanged.
+
+## Benchmarks
+
+Uncapped frame rates (no vsync) on a MacBook Pro with an M4 Pro, Chrome 154, 1 px error threshold, shadows on.
+Ranges span several camera views per scene. [Details and how to run them](https://elad12390.github.io/three-virtual-geometry/guide/performance#benchmarks):
+`npm run bench`.
+
+| Scene | Full-detail triangles | Instances | Drawn per frame | FPS at 1080p | FPS at 4K |
+| --- | --- | --- | --- | --- | --- |
+| Ruins | 5.7B | 113k | 6.5M – 9.0M | 160 – 230 | 103 – 158 |
+| World (6 km) | 37.5B | 3.0M | 8.3M – 9.1M | 147 – 150 | 101 – 120 |
+| Valley (2 km) | 1.1B | 152k | 3.1M – 8.6M | 159 – 329 | 109 – 203 |
+| glTF import | 5.1M | 12k | 0.5M – 0.6M | 941 – 964 | 468 – 516 |
+| Stress, 1M instances | 39.5B | 1.0M | 0.6M – 8.4M | 177 – 1,404 | 154 – 696 |
+
+## Install
+
+```bash
+npm install three-virtual-geometry three
+```
+
+Needs three.js r180+ and a browser with WebGPU (Chrome or Edge 113+, Safari 26+, Firefox 141+ on Windows).
+
+### Use it from a CDN (no build step)
+
+No npm needed: one import in a plain HTML file. The all-in-one build includes three.js, `GLTFLoader`,
+`OrbitControls` and `RoomEnvironment`:
+
+```html
+<script type="module">
+  import { THREE, VirtualGeometry, GLTFLoader } from
+    'https://cdn.jsdelivr.net/npm/three-virtual-geometry@0.1/dist/three-virtual-geometry.all.min.js';
+  // ... same code as below, with THREE from this import
+</script>
+```
+
+Already using three.js on the page? The minimal build (`dist/three-virtual-geometry.min.js`) leaves three.js out and
+uses yours through an import map. The [CDN guide](https://elad12390.github.io/three-virtual-geometry/guide/cdn)
+has complete pages for both, every line explained.
+
+## Use it
+
+```ts
+import * as THREE from 'three/webgpu';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { VirtualGeometry } from 'three-virtual-geometry';
+
+const renderer = new THREE.WebGPURenderer({ antialias: true });
+await renderer.init();
+
+const vg = new VirtualGeometry();
+const gltf = await new GLTFLoader().loadAsync('level.glb');
+await vg.add(gltf.scene);   // every static mesh becomes virtual geometry, in place
+scene.add(gltf.scene);
+
+renderer.setAnimationLoop(() => renderer.render(scene, camera)); // render as usual
+```
+
+That's the whole integration. Repeated props are instanced automatically, builds are cached in the browser, and
+level of detail and culling run before every render. Everything else is an optional lever:
+
+```ts
+vg.errorThreshold.value = 1.5;          // coarser and faster (pixels of error, default 1)
+vg.triangleBudget = 6_000_000;          // or adapt detail to a budget (off by default)
+grass.maxDrawDistance = 400;            // per mesh: stop drawing small clutter far away
+```
+
+Geometry made in code works too:
+
+```ts
+const data = await buildVirtualMeshCached(fromBufferGeometry(geometry));
+scene.add(vg.createMesh(data, material, { matrices })); // 16 floats per instance
+```
+
+See the [guide](https://elad12390.github.io/three-virtual-geometry/guide/getting-started) for importing,
+instancing, settings, baking `.vgeo` files with `npx vg-bake`, and performance tips.
+
+## Set it up with your AI agent
+
+Paste this into Claude Code, Cursor, Copilot or any coding agent, in your project:
+
+```text
+Add three-virtual-geometry (https://github.com/elad12390/three-virtual-geometry) to this project so that every
+static mesh is rendered as virtual geometry. Read https://elad12390.github.io/three-virtual-geometry/llms.txt first.
+Install it, make sure the renderer is THREE.WebGPURenderer from 'three/webgpu' (await renderer.init()), create one
+VirtualGeometry, and call await vg.add(model) for each loaded model before adding it to the scene. Keep the render
+loop, materials, lights and shadows as they are. Run the app and confirm there are no console errors.
+```
+
+[More on agent setup](https://elad12390.github.io/three-virtual-geometry/guide/ai-agents) · [llms.txt](docs/public/llms.txt)
+· [AGENTS.md](AGENTS.md) (for agents working on this repository).
+
+## How it works
+
+Each mesh is split into clusters of up to 128 triangles, which are grouped, simplified with locked borders, and
+split again, level by level, into a hierarchy where every cluster knows its own error and its parent's. Every frame,
+compute shaders pick, per instance and per cluster, the version whose error projects to under a pixel. Because
+errors grow monotonically up the hierarchy, the selection never has cracks. Many meshes share pooled buffers, so
+the per-frame cost doesn't grow with the number of unique meshes.
+[Read more](https://elad12390.github.io/three-virtual-geometry/guide/how-it-works).
+
+## Run the demos locally
+
+```bash
+git clone https://github.com/elad12390/three-virtual-geometry && cd three-virtual-geometry
+npm install
+npm run dev     # http://localhost:8090/?scene=ruins (also map, world, import, stress, test)
+npm test        # build invariants, partitioner, file format and import tests (Node)
+```
+
+## Limitations
+
+- Static meshes (no skinning or morph targets); instances can move. Skinned meshes are left as normal three.js meshes.
+- One UV channel. Hardware rasterization only (no software rasterizer for pixel-sized triangles).
+- Occlusion culling needs a perspective camera with standard depth; it turns itself off otherwise.
+
+## About this project
+
+This is an independent, open-source implementation of *virtual geometry* (a cluster LOD hierarchy selected per
+frame on the GPU), the rendering technique popularized by Nanite. It is written from scratch in TypeScript for
+three.js, based on public descriptions of the technique and on the MIT-licensed
+[nanite-webgpu](https://github.com/Scthe/nanite-webgpu) by Marcin Matuszczyk.
+
+- It contains no source code, shaders, binaries or assets from Epic Games or their engine, and nothing in it is
+  derived from their code or compiled code.
+- It is not affiliated with, endorsed by or sponsored by Epic Games, Inc. "Nanite" is a trademark of Epic Games,
+  Inc., used here only to name the technique.
+
+Built on [three.js](https://threejs.org) and [meshoptimizer](https://github.com/zeux/meshoptimizer). The demo's
+cars are the [Kenney Car Kit](https://kenney.nl/assets/car-kit) (CC0). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Elad Ben-Haim

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,42 @@
+# Third-party notices
+
+## nanite-webgpu
+
+Parts of the mesh preprocessing (`src/nanite/preprocess/buildNaniteMesh.ts`) and of the GPU culling
+pipeline (`src/nanite/runtime/NaniteMesh.ts`) were ported from
+[nanite-webgpu](https://github.com/Scthe/nanite-webgpu) and have since been substantially rewritten.
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2024 Marcin Matuszczyk
+
+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.
+```
+
+## Runtime dependencies
+
+`three` and `meshoptimizer` are npm dependencies (both MIT) and are not vendored here; their licenses
+ship with their packages.
+
+## Demo assets (not part of the npm package)
+
+`examples/public/models/kenney-car-kit/`: [Car Kit](https://kenney.nl/assets/car-kit) by Kenney (www.kenney.nl),
+CC0 1.0 Universal (public domain). See `License.txt` in that folder. All other demo scenes are generated
+procedurally in code.