Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 37 additions & 59 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,60 +25,32 @@ This file provides high-signal context, architectural invariants, and authoring

## 1. Component & Bundle Selection

Goal | Element | Recommended Bundle | Enforced Budget
:----------------------------------------------------------- | :------------- | :------------------------- | :-------------:
`.glb` / `.usdz` 3D viewer + 1-tap AR handoff (no scripting) | `<three-live>` | `three-live-viewer.min.js` | `< 31 KB gz`

Procedural `<script type="text/three">` + `InstancedMesh` +
`KHR_interactivity` + AR | `<three-live>` | `three-live.min.js` | `< 78 KB gz`
Add-on: PBR Next, HDRI/SH, multi-light `shadow-maps`, `bloom`/`outline`,
`KHR_materials_variants`, `meshopt`, `lod`, hotspots | `<three-live>` |
`three-live-studio.min.js` | `< 36 KB gz` Add-on: 2D `Shape`/`ExtrudeGeometry`,
3D `SweepGeometry`/`HelixGeometry`, 3D `CSG` BSP Booleans, 3D stroke-font
`TextGeometry` | `<three-live>` |
`three-live-cad.min.js` | `< 14 KB gz` Domain Kit (a la carte): Parametric
`THREE.Mechanical` gears, bevel gears, ISO bolts/nuts/washers, bearings, pillow
blocks, couplers, springs | `<three-live>` | `three-live-kit-mechanical.min.js`
| `< 18 KB gz` Domain Kit (a la carte): Parametric `THREE.Architecture` walls,
slabs, stairs, roofs, 10-style doors & windows, railings, columns, archways |
`<three-live>` | `three-live-kit-architecture.min.js` | `< 16 KB gz` Domain Kit
(a la carte): Parametric `THREE.Industrial` process pipes, valves, pumps, pallet
racks, conveyors, ladders, catwalks, tanks | `<three-live>` |
`three-live-kit-industrial.min.js` | `< 14 KB gz` Domain Kit (a la carte):
Parametric `THREE.Science` molecules, protein ribbons, crystal lattices,
isosurfaces, streamlines, callouts | `<three-live>` |
`three-live-kit-science.min.js` | `< 31 KB gz` Domain Kit (a la carte):
Parametric `THREE.Electronics` PCBs, flanged/cutout enclosures, heatsinks, DIN
rails, ICs, connectors, discretes | `<three-live>` |
`three-live-kit-electronics.min.js` | `< 14 KB gz` Domain Kits Roll-Up (a la
carte): All 5 domain kits (`Mechanical`, `Architecture`, `Industrial`,
`Science`, `Electronics`; 57 geometries) | `<three-live>` |
`three-live-kits.min.js` | `< 82 KB gz` Add-on: `Box3`/`Sphere`,
`CanvasTexture`, `Noise`, `Sprite`, 2D Curves (`SplineCurve`), Scene Helpers |
`<three-live>` | `three-live-procedural.min.js` | `< 30 KB gz` Add-on: 64-joint
skinning, morph targets, keyframe cross-fading, 2-bone/FABRIK `IKSolver` |
`<three-live>` | `three-live-animation.min.js` | `< 11 KB gz` Add-on:
bring-your-own-LLM scene editing (`editScene()`, `undoEdit()`), Tap & Speak &
Talk-to-Select | `<three-live>` | `three-live-ai.min.js` | `< 33 KB gz` Add-on:
opt-in WebGPU `GPURenderBundle` scene accelerator
(`renderer="auto\|webgpu\|webgl2"`) | `<three-live>` |
`three-live-webgpu.min.js` | `< 23 KB gz` Add-on: opt-in Loop-Free `THREE.TSL` &
`MeshStandardNodeMaterial` compiler (`extras.tsl` -> GLSL/WGSL/USDZ) |
`<three-live>` | `three-live-tsl.min.js` | `< 19 KB gz` Full 3D viewer +
studio + CAD/CSG/Text + procedural + animation + IK + AI + WebGPU + TSL (domain
kits excluded) | `<three-live>` | `three-live-full.min.js` | `< 227 KB gz` 6DoF
WebXR + spatial traits (`grab`, `scale`, `billboard`, `anchor`) +
`<div slot="spatial">` | `<xr-live>` | `xr-live.min.js` | `< 90 KB gz` Add-on:
hardware XR depth occlusion, heightfield physics, 25-joint hands, simulator,
WebMCP | `<xr-live>` | `xr-live-sensors.min.js` | `< 10 KB gz` Add-on bundle
with all 15 modular `<xr-live>` spatial UX, world, splat, audio & AI plugins |
`<xr-live>` | `xr-live-spatial.min.js` | `< 63 KB gz` Add-on bundle with the 6
simulation plugins (character, agents, rigid-body/joints, hit zones, objectives,
audio) | `<xr-live>` | `xr-live-sim.min.js` | `< 30 KB gz` Add-on: opt-in WebGPU
Gaussian Splatting compute & `drawIndirect` render accelerator | `<xr-live>` |
`xr-live-webgpu.min.js` | `< 12 KB gz` Full Spatial Computing + Depth Physics +
25-Joint Hands + all 15 spatial + 6 sim + WebGPU + TSL plugins | `<xr-live>` |
`xr-live-full.min.js` | `< 336 KB gz`
<!-- mdformat off(reason: preserve GFM single-line pipe tables for GitHub) -->
| Goal | Element | Recommended Bundle | Enforced Budget |
| :--- | :--- | :--- | :---: |
| `.glb` / `.usdz` 3D viewer + 1-tap AR handoff (no scripting) | `<three-live>` | `three-live-viewer.min.js` | `< 31 KB gz` |
| Procedural `<script type="text/three">` + `InstancedMesh` + `KHR_interactivity` + AR | `<three-live>` | `three-live.min.js` | `< 78 KB gz` |
| Add-on: PBR Next, HDRI/SH, multi-light `shadow-maps`, `bloom`/`outline`, `KHR_materials_variants`, `meshopt`, `lod`, hotspots | `<three-live>` | `three-live-studio.min.js` | `< 36 KB gz` |
| Add-on: 2D `Shape`/`ExtrudeGeometry`, 3D `SweepGeometry`/`HelixGeometry`/`LoftGeometry`, 3D `CSG` BSP Booleans, 3D stroke-font `TextGeometry` | `<three-live>` | `three-live-cad.min.js` | `< 17 KB gz` |
| Domain Kit (a la carte): Parametric `THREE.Mechanical` gears, bevel gears, ISO bolts/nuts/washers, bearings, pillow blocks, couplers, springs | `<three-live>` | `three-live-kit-mechanical.min.js` | `< 18 KB gz` |
| Domain Kit (a la carte): Parametric `THREE.Architecture` walls, slabs, stairs, roofs, 10-style doors & windows, railings, columns, archways | `<three-live>` | `three-live-kit-architecture.min.js` | `< 16 KB gz` |
| Domain Kit (a la carte): Parametric `THREE.Industrial` process pipes, valves, pumps, pallet racks, conveyors, ladders, catwalks, tanks | `<three-live>` | `three-live-kit-industrial.min.js` | `< 14 KB gz` |
| Domain Kit (a la carte): Parametric `THREE.Science` molecules, protein ribbons, crystal lattices, isosurfaces, streamlines, callouts | `<three-live>` | `three-live-kit-science.min.js` | `< 31 KB gz` |
| Domain Kit (a la carte): Parametric `THREE.Electronics` PCBs, flanged/cutout enclosures, heatsinks, DIN rails, ICs, connectors, discretes | `<three-live>` | `three-live-kit-electronics.min.js` | `< 14 KB gz` |
| Domain Kits Roll-Up (a la carte): All 5 domain kits (`Mechanical`, `Architecture`, `Industrial`, `Science`, `Electronics`; 57 geometries) | `<three-live>` | `three-live-kits.min.js` | `< 82 KB gz` |
| Add-on: `Box3`/`Sphere`, `CanvasTexture`, `Noise`, `Sprite`, 2D Curves (`SplineCurve`), Scene Helpers | `<three-live>` | `three-live-procedural.min.js` | `< 30 KB gz` |
| Add-on: 64-joint skinning, morph targets, keyframe cross-fading, 2-bone/FABRIK `IKSolver` | `<three-live>` | `three-live-animation.min.js` | `< 11 KB gz` |
| Add-on: bring-your-own-LLM scene editing (`editScene()`, `undoEdit()`), Tap & Speak & Talk-to-Select | `<three-live>` | `three-live-ai.min.js` | `< 33 KB gz` |
| Add-on: opt-in WebGPU `GPURenderBundle` scene accelerator (`renderer="auto\|webgpu\|webgl2"`) | `<three-live>` | `three-live-webgpu.min.js` | `< 23 KB gz` |
| Add-on: opt-in Loop-Free `THREE.TSL` & `MeshStandardNodeMaterial` compiler (`extras.tsl` -> GLSL/WGSL/USDZ) | `<three-live>` | `three-live-tsl.min.js` | `< 19 KB gz` |
| Full 3D viewer + studio + CAD/CSG/Text + procedural + animation + IK + AI + WebGPU + TSL (domain kits excluded) | `<three-live>` | `three-live-full.min.js` | `< 231 KB gz` |
| 6DoF WebXR + spatial traits (`grab`, `scale`, `billboard`, `anchor`) + `<div slot="spatial">` | `<xr-live>` | `xr-live.min.js` | `< 90 KB gz` |
| Add-on: hardware XR depth occlusion, heightfield physics, 25-joint hands, simulator, WebMCP | `<xr-live>` | `xr-live-sensors.min.js` | `< 10 KB gz` |
| Add-on bundle with all 15 modular `<xr-live>` spatial UX, world, splat, audio & AI plugins | `<xr-live>` | `xr-live-spatial.min.js` | `< 63 KB gz` |
| Add-on bundle with the 6 simulation plugins (character, agents, rigid-body/joints, hit zones, objectives, audio) | `<xr-live>` | `xr-live-sim.min.js` | `< 30 KB gz` |
| Add-on: opt-in WebGPU Gaussian Splatting compute & `drawIndirect` render accelerator | `<xr-live>` | `xr-live-webgpu.min.js` | `< 12 KB gz` |
| Full Spatial Computing + Depth Physics + 25-Joint Hands + all 15 spatial + 6 sim + WebGPU + TSL plugins | `<xr-live>` | `xr-live-full.min.js` | `< 340 KB gz` |
<!-- mdformat on -->

---

Expand Down Expand Up @@ -130,10 +102,15 @@ Gaussian Splatting compute & `drawIndirect` render accelerator | `<xr-live>` |
5. **Procedural CAD, Instancing & IK Helpers (`THREE` in
`<script type="text/three">`):**

- **2D Shapes & Extrusion:** `new THREE.Shape()`,
- **2D Shapes, 3D Sweeps, Helices & Lofts:** `new THREE.Shape()`,
`shape.moveTo/lineTo/quadraticCurveTo/bezierCurveTo/absarc()`,
`shape.holes.push(holePath)`, `new THREE.ExtrudeGeometry(shape, { depth,
bevelEnabled, bevelThickness, bevelSize, bevelSegments })`.
bevelEnabled, bevelThickness, bevelSize, bevelSegments, extrudePath })`,
`new THREE.SweepGeometry(shape, pathOrOptions)`,
`new THREE.HelixGeometry({ radius, height, turns, wireRadius, shape })`,
`new THREE.LoftGeometry(stations, { steps, interpolation, path,
openTop, wallThickness })` (`wallThickness` shells a hollow vessel only
with `openTop: true`; station `shape.holes` are ignored).
- **CSG Booleans:** `THREE.CSG.union(meshA, meshB)`,
`THREE.CSG.subtract(meshA, meshB)`, `THREE.CSG.intersect(meshA, meshB)`
(returns a new `THREE.Mesh` with normals; polygon soup, not guaranteed
Expand Down Expand Up @@ -269,10 +246,11 @@ Every procedural scene and `userData.xr` trait runs across **Web**, **Android**,
- Embeds `compiler/assets/three-author-engine.min.js` inside an isolated
Boa JS context with strict opcode/wall-clock watchdogs, outputting
`.glb` (including `EXT_mesh_gpu_instancing`, `KHR_materials_variants`,
`KHR_audio_emitter`, and validated `extras.tsl` SSA node graphs
via `compiler/src/tsl.rs`) and `.usdz` (including `PointInstancer`,
`KHR_audio_emitter`, and validated `extras.tsl` SSA node graphs via
`compiler/src/tsl.rs`) and `.usdz` (including `PointInstancer`,
`VariantSets`, `SpatialAudio`, and `UsdShade` / MaterialX `NodeGraph`s)
bytes via C FFI (`compiler/include/three_live_compiler.h`) and `three-live-cli`.
bytes via C FFI (`compiler/include/three_live_compiler.h`) and
`three-live-cli`.
4. **Native Mobile SDKs (`mobile/android/` & `mobile/ios/`):**
- **Android (`mobile/android/src/main/java/com/google/threelive/`):**
`XRLiveSceneCoreHelper.kt`, `XRSpatialMath.kt`, `XRSpatialFeatures.kt` +
Expand Down
Loading
Loading