lecodes-sdk 2.2.9 → 2.2.10

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.9",
+  "version": "2.2.10",
   "files": [
     "src",
     "dist",

package/prompts/ar.md

@@ -1,84 +1,119 @@
 ## AR
 
-ARScene = a scene rendered over the device camera feed with world tracking. Everything from the
-3D-engine section applies (nodes, meshes, models, materials, physics, events); THIS section is how
-an AR scene is created and driven. There is no skybox/background (the camera feed shows through),
-and lighting still needs the default IBL and/or a Light.sun for lit materials.
+ARScene = a scene over the device camera with world tracking, from the "ar" plugin — the app lists it
+in app.json: `"plugins": { "ar": "*" }` (without it `ARScene.isSupported` is false and open() rejects).
+Everything from the 3D-engine section applies (nodes, meshes, models, materials, physics, events);
+THIS section is how an AR scene is created and driven. The session moves scene.camera every frame and
+draws the camera image behind everything (no skybox shows); lit materials still need the default IBL
+and/or a Light.sun.
 
 // ===== ARSCENE =====
 
 new ARScene(options?: {
     ibl?: boolean                  // image-based ambient light; default TRUE
     environmentIntensity?: number  // IBL strength; default 20000
-    mode?: 'default' | 'markers' | 'arcore' | 'detached'   // tracking mode; default 'default'
+    mode?: 'world' | 'images'      // 'world' (default): planes, hitTest, anchors, images.
+                                   // 'images': image targets only — no planes, no hitTest, no root
 })
-
-await scene.open()               // ASYNC (unlike Scene.open): requests camera permission → warm-renders
-                                 // → launches tracking. REJECTS if the camera is denied or AR can't
-                                 // start — always await and handle failure (fall back / show a message).
-scene.close()                    // stop the AR session
-scene.useWarmRender = true       // default true — open() pre-compiles shaders itself
+ARScene.isSupported              // static: the host has the plugin — check before an AR button
+
+await scene.open(options?: {     // ASYNC: camera permission → warm render → session → on screen.
+    planes?: 'horizontal' | 'vertical' | 'both' | 'none'   // default 'horizontal'
+    lightEstimation?: boolean    // 'light' events
+    followLight?: boolean        // the scene's ambient follows the estimated light
+    transition?: Transition
+})                               // REJECTS: camera denied, 'unavailable' (no ARKit/ARCore), superseded —
+                                 // always await and handle failure (fall back / show a message).
+scene.close()                    // stops the session (the camera is let go)
+
+// ===== TRACKING =====
+scene.trackingState              // 'notAvailable' | 'limited' | 'normal'
+scene.trackingReason             // with 'limited': 'initializing' | 'excessiveMotion' | 'insufficientFeatures' | 'relocalizing'
+scene.addEventListener('tracking', (state, reason) => {})
+scene.addEventListener('error', ({ code, message }) => {})   // the session failed and is over
 
 // ===== ANCHORS =====
-// An anchor is a Node whose transform is DRIVEN BY TRACKING — parent all content under one.
-
-scene.root                       // Node: the world-origin anchor (read-only). NOT available in 'markers' mode.
-scene.createAnchor(source: FetchResponse, physicalWidth = 0.2): Node
-// Image-target anchor: `source` = the marker image (fetch it), `physicalWidth` = the printed
-// target's real-world width in METERS. Add content as children; it appears on the physical image.
-
-// Tracking state — on any anchor node:
-anchor.addEventListener('track', () => {})     // began tracking (marker found / world locked)
-anchor.addEventListener('untrack', () => {})   // lost tracking
-anchor.isTracked                               // current state (false for non-anchor nodes)
-// Typical: hide content until tracked — anchor.visible = false; on 'track' set true.
+// An Anchor is a Node the session moves — parent content under one (it joins the scene with it).
+
+scene.root                       // Anchor: pinned on the FIRST HORIZONTAL PLANE found ('track' fires then);
+                                 // until then at the world's origin. Not in 'images' mode.
+scene.anchor(pose)               // Anchor at a pose ({ position, rotation }, e.g. a hitTest result's)
+scene.createAnchor(source: FetchResponse, physicalWidth = 0.2): ImageAnchor
+// Image target: `source` = the marker image (fetch it), `physicalWidth` = its printed width in
+// METERS. Hidden until the image is seen. A RIGID pose in meters (no scale): its centre, Y out of
+// the image, the image in XZ (Z toward its bottom). Its size: anchor.extent = [width, height] m
+// (refined while tracked; [physicalWidth, 0] before the first 'track'). A plane on it:
+//   const s = Mesh.plane({ material, eulerAngles: [-90, 0, 0] }); anchor.add(s)
+//   anchor.addEventListener('track', () => s.scale = [anchor.extent[0], anchor.extent[1], 1])
+anchor.tracked                   // the session holds it now
+anchor.addEventListener('track', () => {})
+anchor.addEventListener('untrack', () => {})
+anchor.remove()                  // let it go; it leaves the scene
+
+// ===== PLANES & HIT TEST =====
+scene.planes                     // ARPlane[]: plane.type ('horizontal' | 'vertical'), plane.extent [w, d] m,
+                                 // plane.polygon (x,z pairs in the plane's space), plane.center (Vec3)
+scene.addEventListener('plane', ({ plane, change, mergedInto }) => {})   // change: 'added' | 'updated' | 'removed'
+scene.showPlanes = true          // a grid drawn on every plane
+const hits = await scene.hitTest(ev.clientX, ev.clientY, 'planes')   // a scene touch's point → [{ pose, type, plane, distance }], nearest first; [] = nothing
+
+// ===== LIGHT & CAPTURE =====
+scene.lightEstimate              // { intensity (1000 = neutral), temperature (K) } | null
+const photo = await scene.captureFrame()   // the camera image alone: a JPEG File
+const shot = await scene.capture()         // what the scene shows (camera + 3D): a PNG File
 
 // ===== PLACEMENT CONTROLS =====
-// The standard "place an object in your room" gestures, prebuilt on the public touch API:
-
 const controls = scene.addControls(target: Node, options?: {
     minScale?: number,   // pinch clamp; default 0.08
     maxScale?: number,   // default 2
-    pan?: boolean,       // one-finger drag across the ground plane; default true
+    pan?: boolean,       // one finger: over the plane under the finger; default true
     pinch?: boolean,     // two-finger uniform scale; default true
     twist?: boolean,     // two-finger rotate around Y; default true
 })
 controls.remove()        // detach the gesture listeners
 
+// ===== ON THE WEB =====
+// The camera under the scene, the camera turned by the phone's sensors, its position fixed: tracking
+// is 'normal' at once, NO planes, NO images, hitTest resolves [], root never fires 'track' (it stays
+// at the origin) — don't gate content on root's 'track' if the app must work in a browser.
+
 // ===== AR RULES & MISTAKES =====
 
-// The camera is driven by device tracking — READ it (position, getRay), NEVER place it.
-// ❌ moving the camera to frame content — tracking overwrites it every frame
+// The camera is the session's — READ it (position, getRay), NEVER place it.
+// ❌ moving the camera to frame content — the session overwrites it every frame
 arScene.camera.position = [0, 2, 4]
 // ✅ move the WORLD: parent content under scene.root (or an anchor) and place THAT
 scene.root.add(model); model.position = [0, 0, -1]
 
-// ❌ content floating free in scene space without an anchor — it won't stick to the real world
-scene.add(model)                       // added to the draw set but parented to nothing
-// ✅ BOTH: parent under an anchor AND register with the scene
-scene.root.add(model); scene.add(model)
+// ❌ forgetting the plugin: ARScene without "ar" in app.json "plugins" is unsupported everywhere
+// ✅ app.json: { "plugins": { "ar": "*" } }
 
 // ❌ treating open() like Scene.open()
-arScene.open(); spawnStuff()           // runs before permission is granted; rejection unhandled
-// ✅ await it and handle denial
-try { await arScene.open() } catch { toast('Camera access is required for AR') }
-
-// ❌ waiting for content to show without tracking feedback
-// ✅ marker apps: keep content hidden until 'track', tell the user to point at the marker
+arScene.open(); spawnStuff()           // runs before the session started; rejection unhandled
+// ✅ await it and handle failure
+try { await arScene.open() } catch { toast('AR is not available on this device') }
+
+// ❌ placing on a tap at a guessed distance
+// ✅ hitTest the tap and anchor there
+scene.addEventListener('click', async (ev) => {
+    const [hit] = await scene.hitTest(ev.clientX, ev.clientY, 'planes')
+    if (hit) scene.anchor(hit.pose).add(lamp.clone())
+})
 
 // Shadows on the real floor: a Mesh.plane({ normal: [0, 1, 0], material: Material.shadow() })
 // under the object — invisible except where shadows fall.
 
 ## AR example
 
-// Object-placement app: a GLB placed in the room, drag/pinch/twist to position it,
-// tap it to play its animation, shadow on the real floor, transparent HUD hint.
+// Object-placement app: a GLB on the floor once it is found, drag/pinch/twist to position it,
+// tap it to play its animation, shadow on the real floor, a HUD hint over the scene.
+// app.json lists the plugin: { "plugins": { "ar": "*" } }
 
 <file name="main.ts">
 const scene = new ARScene()
 
 const hint = UIText('Move your phone to find the floor').style({ color: 'white', fontSize: 16 })
-const hud = UIScreen(hint).style({ p: 'safe-all', pb: 'comfort-bottom', justifyContent: 'flex-end', alignItems: 'center' })
+scene.widgets(UIWidget(hint).style({ position: 'absolute', left: 0, right: 0, bottom: 48, alignItems: 'center' }))
 
 async function main() {
     const chair = await Model.load(asset('./chair.glb'))
@@ -89,19 +124,17 @@ async function main() {
     const shadow = Mesh.plane({ normal: [0, 1, 0], material: Material.shadow(), scale: 2 })
     chair.add(shadow)
 
-    // Content lives under the tracked world origin AND in the draw set
-    chair.position = [0, 0, -1]
+    // Content lives under the floor anchor (it joins the scene with it)
     scene.root.add(chair)
-    scene.add(chair, shadow, Light.sun({ shadowsQuality: 2 }))
+    scene.add(Light.sun({ shadowsQuality: 2 }))
+    scene.root.addEventListener('track', () => { hint.text = 'Drag to move · pinch to scale · tap to animate' })
 
     scene.addControls(chair)                       // drag / pinch-scale / twist gestures
 
     try {
-        await scene.open()                         // camera permission → tracking
-        hud.open()                                 // transparent HUD over the camera feed
-        hint.text = 'Drag to move · pinch to scale · tap to animate'
+        await scene.open()                         // camera permission → session
     } catch {
-        toast('Camera access is required for AR')
+        toast('AR is not available on this device')
     }
 }