@needle-tools/engine 5.1.9 → 5.1.11

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [5.1.11] - 2026-08-13
+- Fix: mirrored and negatively-scaled instanced meshes now render correctly (NE-7069)
+
+## [5.1.10] - 2026-08-07
+- Add: turn the whole postprocessing stack on or off at runtime with `PostProcessing.enabled`
+- Fix: scene brightness no longer shifts when XR hand models are shown or hidden
+- Fix: the `showHandModels` toggle now reliably shows or hides XR hand models
+- Change: `SyncedRoom` warns (in development) when a room-name URL parameter overrides the `roomName` set on the component, making it easier to diagnose ending up in an unexpected room
+
 ## [5.1.9] - 2026-07-30
 **Added**
 - `WebXRImageTracking`: friendlier `addImage` API for registering marker images

package/SKILL.md

@@ -13,7 +13,10 @@ description: >
   or error without mentioning Needle Engine — check if @needle-tools/engine is in
   package.json or imports. If the project uses Needle Engine, always load this skill.
 compatibility:
-  - optional: needle_search MCP tool (search Needle Engine docs, forum posts, and community answers)
+  - optional: >
+      needle_search MCP tool (search Needle Engine docs, forum posts, and community answers).
+      Without it, the same corpus is reachable over HTTP at
+      https://search.needle.tools/api/semantic-search?q=... (public, no key) — see references/mcp.md
 ---
 
 # Needle Engine
@@ -47,6 +50,33 @@ export class HelloWorld extends Behaviour {
 
 > ⚠️ **TypeScript config required:** `tsconfig.json` must have `"experimentalDecorators": true` and `"useDefineForClassFields": false` for decorators to work. Without `useDefineForClassFields: false`, TypeScript overwrites `@serializable()` properties with their default values *after* the decorator runs, silently breaking deserialization.
 
+On **5.1+**, scenes expose auto-generated typed bindings, and `needle` gives you the context from
+anywhere — often shorter than `getComponent` lookups:
+```ts
+import { needle, onStart } from "@needle-tools/engine";
+
+// `needle` resolves to the current context when the handler runs — no wrapper needed
+button.onclick = () => {
+  needle.sceneData.MyScene.MainCamera.$components.OrbitControls.autoRotate = false;
+};
+
+// Without it, you'd wrap the wiring in onStart purely to capture a ctx:
+onStart(ctx => {
+  button.onclick = () => {
+    ctx.sceneData.MyScene.MainCamera.$components.OrbitControls.autoRotate = false;
+  };
+});
+```
+`onStart(ctx => …)` is still the right tool for setup that must run once the scene is ready —
+`needle` is for reaching the context from code that runs later.
+> ⚠️ **Don't touch `needle` at module top-level.** It's a lazy Proxy resolving to the *current*
+> context — module bodies evaluate before any scene exists, so it logs an error and returns a
+> no-op proxy. Use it inside callbacks and event handlers; use `onStart(ctx => …)` for setup.
+> (Importing it at top level is fine, including under SSR — only *access* is the problem.)
+
+Components need `$components`; bare names are child nodes. Both APIs are experimental — see
+[What's New](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/whats-new.md).
+
 ---
 
 ## Key Concepts
@@ -137,7 +167,9 @@ Boolean attributes can be disabled with `="0"` (e.g. `camera-controls="0"`).
 | `background-color` | Hex or RGB background color (e.g. `#ff0000`) |
 | `background-image` | Skybox URL or preset: `studio`, `blurred-skybox`, `quicklook`, `quicklook-ar` |
 | `background-blurriness` | Blur intensity for background (0–1) |
+| `background-rotation` | Rotate the background skybox (5.1+) |
 | `environment-image` | Environment lighting image URL or preset (same presets as `background-image`) |
+| `environment-rotation` | Rotate the environment lighting (5.1+) |
 | `contactshadows` | Enable contact shadows |
 | `tone-mapping` | `none`, `linear`, `neutral`, `agx` |
 | `poster` | Placeholder image URL shown while loading |
@@ -245,6 +277,13 @@ export default defineConfig(async ({ command }) => ({
 }));
 ```
 
+As of 5.1, `needlePlugins()` resolves the Vite command itself, so it can be called with no
+arguments and without `await`/spread — handy when composing with other framework plugins:
+```js
+export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+```
+Still pass `(command, config, settings)` when you need options like `makeFilesLocal`.
+
 ---
 
 ## `needle.config.json`
@@ -375,7 +414,9 @@ Use this when you need exact method signatures, constructor parameters, or prope
 
 ## Searching the Documentation
 
-Use the `needle_search` MCP tool to find relevant docs, forum posts, and community answers:
+Search the docs *before* guessing at API details — they are the source of truth. The corpus covers Needle Engine documentation, the API reference, the community forum, Discord, and Needle source code.
+
+**If the `needle_search` MCP tool is available, use it:**
 
 ```
 needle_search("how to play animation clip from code")
@@ -383,12 +424,25 @@ needle_search("SyncedTransform multiplayer")
 needle_search("deploy to Needle Cloud CI")
 ```
 
-Use this *before* guessing at API details — the docs are the source of truth.
+**Otherwise, hit the public search API — no key, no setup:**
+
+```bash
+curl -s -H "Accept: application/json" \
+  "https://search.needle.tools/api/semantic-search?q=how+to+play+animation+clip+from+code&limit=5"
+```
+
+Returns JSON `{ query, results: [{ title, source, content, url, score, truncated }], durationMs }`. Optional `limit` (1–20, default 10) and `max_chars` (200–10000, default 2000). Rate-limited to 10 requests/minute for unauthenticated callers.
+
+Both are **semantic** search — phrase queries as full questions ("how do I make an object follow the camera in VR"), not keyword soup ("vr camera follow"). Result `url`s include a `#:~:text=` fragment linking to the exact passage; pass them on to the user.
+
+See 🔌 [MCP & Search API](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/mcp.md) for the full tool inventory — project file access, live scene inspection via the Needle Inspector, Unity/Blender tools — and for MCP server setup.
 
 ---
 
 ## Common Gotchas
 
+- **Scene Bindings: bare names are child nodes, components need `$components`.** `ctx.sceneData.MyGlb.Camera.OrbitControls` looks for a child *object* named OrbitControls; the component is `ctx.sceneData.MyGlb.Camera.$components.OrbitControls`. Worse, misses don't throw — they return an error proxy that swallows every get/set and only warns. If a scene-bindings assignment appears to run but changes nothing, check the console for `[SceneData]`.
+- **`autoCleanup`'s teardown timing depends on where you call it.** In `onEnable` → cleaned on disable. In `awake`/`start` → cleaned on destroy, so it survives disable/enable. Registering a subscription in `start()` and expecting it to stop when the component is disabled is the common mistake.
 - **`obj.visible = false` disables components!** Setting `visible = false` on a parent disables the entire hierarchy including component lifecycle (SyncedTransform, etc.) — like Unity's `setActive`. To hide visually but keep components running, hide child meshes instead: `obj.traverse(c => { if (c.isMesh) c.visible = false; })`. Or use `Renderer.setVisible(obj, false)` which only affects rendering.
 - `@registerType` is required or the component won't be instantiated from GLB. Unity/Blender export adds this automatically via codegen; hand-written components need it explicitly.
 - GLB assets go in `assets/`, static files (fonts, images, videos) in `public/` (configurable via `needle.config.json`)
@@ -406,6 +460,7 @@ Use this *before* guessing at API details — the docs are the source of truth.
 - WebXR requires HTTPS — the Needle project templates include a local HTTPS dev server by default. Use `--host` when running the dev server (e.g. `npx vite --host`) to expose it on your local network IP, allowing you to test on phones/headsets via QR code
 - **Avoid unnecessary allocations.** Do NOT write `obj.worldPosition.clone()` or `new Vector3()` in per-frame code. The `world___` getters (`worldPosition`, `worldQuaternion`, `worldScale`) return temp vectors that can be read directly and re-assigned (`obj.worldPosition = otherObj.worldPosition`). When you need a temporary vector for math, use `getTempVector()` / `getTempQuaternion()` from `@needle-tools/engine` — these come from a circular buffer with zero GC pressure. Only use `.clone()` when you truly need to store a value across frames.
 - **NEVER import from `@needle-tools/engine` subpaths** like `@needle-tools/engine/lib/...` or `@needle-tools/engine/src/...`. These are internal paths that break across versions. Everything is exported from the package root: `import { NEEDLE_ENGINE_MODULES, Rigidbody, BloomEffect, ... } from "@needle-tools/engine"`. The only exception is the vite plugin: `import { needlePlugins } from "@needle-tools/engine/vite"`.
+- **Optimization & compression run at build time (not a scene upload).** Texture (KTX2/WebP) and mesh (Draco/Meshopt) compression, progressive loading, and automatic LODs are applied during the production build (Compression & LOD Settings component). It's **license-gated**, so the user must be logged in to Needle Cloud (`npx needle-cloud start`, or the Unity/Blender integration which handles it) — but that's a login/license check, not uploading their scene. Details: [Optimization & Compression](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/optimization.md).
 
 ---
 
@@ -413,6 +468,7 @@ Use this *before* guessing at API details — the docs are the source of truth.
 
 Read these **only when needed** — don't load them all upfront:
 
+- 🆕 [What's New (5.1 → 6.0)](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/whats-new.md) — Scene Bindings (`ctx.sceneData`), `needle` shorthand, `Context.events`, `autoCleanup`, builder APIs, `<needle-app>`, GaussianSplat. **Check this before assuming an API doesn't exist** — much of it postdates the rest of these references.
 - 📖 [Core API](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/api.md) — lifecycle, decorators, context (input, physics, time), gameobject, coroutines, asset loading, renderer/materials, async modules
 - 🧩 [Components](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/components.md) — animation, audio, video, lighting, camera, scene switching, interaction, splines, particles, debug tools
 - ⚡ [Physics](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/physics.md) — colliders, Rigidbody (forces, velocity, impulse), raycasting, async Rapier loading
@@ -420,14 +476,18 @@ Read these **only when needed** — don't load them all upfront:
 - 🌐 [Networking](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/networking.md) — connection API, SyncedRoom, PlayerSync, @syncField, SyncedTransform, Voip, ScreenCapture, guid persistence
 - 🥽 [WebXR](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/xr.md) — VR/AR sessions, XRRig, controllers, pointer events in XR, image tracking, depth sensing, camera access, mesh detection, DOM overlay, iOS AR, multiplayer avatars
 - 🚀 [Deployment](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/deployment.md) — Needle Cloud (GitHub Actions, CLI), Vercel, Netlify, other platforms
+- 📦 [Optimization & Compression](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/optimization.md) — build-time (local) texture/mesh compression (KTX2, Draco/Meshopt), progressive loading, automatic LODs — **not** a cloud upload
 - 🔗 [Framework Integration](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/integration.md) — React, Svelte, Vue, Next.js, SvelteKit patterns, CDN with import maps
 - 💡 [Component Examples](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/examples.md) — practical examples: click handling, runtime loading, networking, materials, code-only scenes, input, coroutines
 - 🐛 [Troubleshooting](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/troubleshooting.md) — error messages, unexpected behavior, build failures, **runtime logs at `node_modules/.needle/logs/`**, build info
+- 🔌 [MCP & Search API](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/mcp.md) — `needle_search`, the public search HTTP API, MCP server setup, project file tools, live scene inspection via the Needle Inspector, Unity/Blender tools
 - 🧩 [Component Template](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/templates/my-component.ts) — annotated starting point for new components
 
 ## Important URLs
 
-- Docs: https://engine.needle.tools/docs/
+- Docs: https://engine.needle.tools/docs/ (any page also available as markdown — swap `.html` for `.md`)
+- Search API: https://search.needle.tools/api/semantic-search?q=your+question ([API reference](https://search.needle.tools/api-docs))
+- AI & MCP docs: https://engine.needle.tools/docs/ai/
 - Samples: https://engine.needle.tools/samples/
 - Samples index (all official samples with source): https://github.com/needle-tools/needle-engine-samples/blob/main/samples.json
 - GitHub: https://github.com/needle-tools/needle-engine-support