@needle-tools/engine 4.15.0-next.f391a30 → 4.16.0-next.35df6b8

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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).
 
+## [4.16.0] - 2026-03-05
+- **NEW**: `makeFilesLocal` build option overhauled — builds can now be fully self-contained and work offline. The plugin downloads external CDN assets at build time and bundles them locally. This is essential for playable ads, app stores that require single-origin or self-contained bundles, offline-capable PWAs, and restricted hosting environments. Supports auto-detection of used features, per-feature opt-in/opt-out, and platform presets. Covers Draco decoders, KTX2 transcoders, MaterialX, WebXR input profiles, skybox/environment textures, Google Fonts, third-party scripts, and more.
+  Example in `vite.config.js`:
+  ```js
+  needlePlugin({
+    makeFilesLocal: "auto" // auto-detect and download only what your project uses
+  })
+  // or with fine-grained control:
+  needlePlugin({
+    makeFilesLocal: {
+      enabled: true,
+      features: ["draco", "ktx2", "fonts"],
+      excludeFeatures: ["xr"]
+    }
+  })
+  ```
+- Add: `showBalloonMessage` now supports `duration`, `once`, and `key` options for controlling message display duration and updating existing messages
+- Add: `needleAI` vite plugin — when using Claude Code in a Needle Engine project, the engine automatically provides a project-aware AI skill with Needle Engine context
+- Add: DragControls now warns when used on static objects that won't update their transforms
+- Add: AR overlay support for AppClip sessions
+- Improve: Stable three.js chunk names in production builds, enabling CDN import maps with predictable URLs
+- Improve: USDZ export now uses `"string"` type for input variable names for better spec compatibility
+- Improve: Gizmo rendering uses consistent font from CDN
+- Improve: needle-menu layout with correct padding and minimum width for icon-only elements
+- Improve: Vite project template aligned with online template
+- Improve: Updated MaterialX dependency
+- Improve: JSDoc documentation
+- Fix: ReflectionProbe support for Blender workflows
+- Fix: Mac build error ("-50" error)
+- Fix: PWA defaults when package name is missing
+- Fix: Improved error handling in MaterialX importer
+
 ## [4.15.0] - 2026-02-27
 - **NEW**: Accessibility support with screen reader overlay. The engine now maintains a visually-hidden DOM tree mirroring 3D scene objects with ARIA roles and labels. Components like Button, Text, DragControls, and USDZ behavior components automatically register accessible elements.
 - Add: `AccessibilityManager` accessible via `context.accessibility` for managing accessible elements, focus, and hover announcements

package/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: needle-engine
+description: Automatically provides Needle Engine context when working in a Needle Engine web project. Use this skill when editing TypeScript components, Vite config, GLB assets, or anything related to @needle-tools/engine.
+metadata:
+  reviewed-against: "@needle-tools/engine@4.15.0"
+  last-reviewed: "2026-03"
+---
+
+# Needle Engine
+
+You are an expert in Needle Engine — a web-first 3D engine built on Three.js with a component system and Unity/Blender-based workflow.
+
+## When to Use This Skill
+
+**Use when the user is:**
+- Editing TypeScript files that import from `@needle-tools/engine`
+- Working on a project with `vite.config.ts` that uses `needlePlugins`
+- Loading or debugging `.glb` files exported from Unity or Blender
+- Using the Needle Engine Blender addon or Unity package
+- Asking about component lifecycle, serialization, XR, networking, or deployment
+
+**Do NOT use for:**
+- Pure Three.js projects with no Needle Engine
+- Non-web Unity/Blender work with no GLB export
+
+---
+
+## Quick Start
+
+```html
+<needle-engine src="assets/scene.glb"></needle-engine>
+<script type="module">
+  import "@needle-tools/engine";
+</script>
+```
+
+Minimal TypeScript component:
+```ts
+import { Behaviour, serializable, registerType } from "@needle-tools/engine";
+
+@registerType
+export class HelloWorld extends Behaviour {
+  @serializable() message: string = "Hello!";
+
+  start() {
+    console.log(this.message);
+  }
+}
+```
+
+> **TypeScript config required:** `tsconfig.json` must have `"experimentalDecorators": true` and `"useDefineForClassFields": false` for decorators to work.
+
+---
+
+## Key Concepts
+
+**Needle Engine** ships 3D scenes from Unity or Blender as GLB files and renders them in the browser using Three.js. TypeScript components attached to objects are serialized into the GLB and re-hydrated at runtime.
+
+- **Unity workflow:** C# MonoBehaviours → auto-generated TypeScript stubs → GLB export on play/build
+- **Blender workflow:** Components added via the Needle Engine Blender addon → GLB export with component data embedded
+- **Embedding:** `<needle-engine src="assets/scene.glb">` web component creates and manages a 3D context
+- **Context access:** use `onStart(ctx => { ... })` or `onInitialize(ctx => { ... })` lifecycle hooks (preferred); `document.querySelector("needle-engine").context` works but only from UI event handlers
+
+### `<needle-engine>` Attributes
+
+Boolean attributes can be disabled with `="0"` (e.g. `camera-controls="0"`).
+
+```html
+<needle-engine
+  src="assets/scene.glb"
+  camera-controls
+  auto-rotate
+  autoplay
+  background-color="#222"
+  environment-image="studio"
+  contactshadows
+></needle-engine>
+```
+
+| Attribute | Description |
+|---|---|
+| `src` | GLB/glTF file path(s) — string, array, or comma-separated |
+| `camera-controls` | Adds default OrbitControls with auto-fit if no `OrbitControls`/`ICameraController` exists in the root GLB. Disable with `="0"` for fully custom camera. To tweak defaults, get `OrbitControls` from the main camera in `onStart` |
+| `auto-rotate` | Auto-rotate the camera (requires `camera-controls`) |
+| `autoplay` | Auto-play animations in the loaded scene |
+| `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) |
+| `environment-image` | Environment lighting image URL or preset (same presets as `background-image`) |
+| `contactshadows` | Enable contact shadows |
+| `tone-mapping` | `none`, `linear`, `neutral`, `agx` |
+| `poster` | Placeholder image URL shown while loading |
+| `loadstart` / `progress` / `loadfinished` | Callback functions for loading lifecycle |
+
+---
+
+## Unity → Needle Cheat Sheet
+
+| Unity (C#) | Needle Engine (TypeScript) |
+|---|---|
+| `MonoBehaviour` | `Behaviour` |
+| `[SerializeField]` / public field | `@serializable()` (required for all serialized fields) |
+| `Instantiate(prefab)` | `instantiate(obj)` |
+| `Destroy(obj)` | `destroy(obj)` |
+| `GetComponent<T>()` | `this.gameObject.getComponent(T)` |
+| `AddComponent<T>()` | `this.gameObject.addComponent(T)` |
+| `FindObjectOfType<T>()` | `findObjectOfType(T, ctx)` |
+| `transform.position` | `this.gameObject.worldPosition` (world) / `this.gameObject.position` (local) |
+| `transform.rotation` | `this.gameObject.worldQuaternion` (world) / `this.gameObject.quaternion` (local) |
+| `transform.localScale` | `this.gameObject.worldScale` (world) / `this.gameObject.scale` (local) |
+| `Resources.Load<T>()` | No direct equivalent — use `@serializable(AssetReference)` to assign refs in editor, then `.instantiate()` or `.asset` at runtime |
+| `StartCoroutine()` | `this.startCoroutine()` (in a component; unlike Unity, coroutines stop when the component is disabled) |
+| `Time.deltaTime` | `this.context.time.deltaTime` |
+| `Camera.main` | `this.context.mainCamera` (THREE.Camera) / `this.context.mainCameraComponent` (Needle Camera component) |
+| `Debug.Log()` | `console.log()` |
+| `OnCollisionEnter()` | `onCollisionEnter(col: Collision)` |
+| `OnTriggerEnter()` | `onTriggerEnter(col: Collision)` |
+
+---
+
+## Three.js → Needle Cheat Sheet
+
+| Three.js | Needle Engine |
+|---|---|
+| `new Mesh(geo, mat)` | Created in Unity/Blender, exported as GLB; access via `Renderer.sharedMesh` / `Renderer.sharedMaterials` |
+| `scene.add(obj)` | `this.gameObject.add(obj)` or `instantiate(prefab)` |
+| `scene.remove(obj)` | `obj.removeFromParent()` (re-parent) or `destroy(obj)` (permanent) |
+| `obj.position` | `obj.position` (local) / `obj.worldPosition` (world — Needle extension) |
+| `obj.quaternion` | `obj.quaternion` (local) / `obj.worldQuaternion` (world — Needle extension) |
+| `obj.scale` | `obj.scale` (local) / `obj.worldScale` (world — Needle extension) |
+| `obj.getWorldPosition(v)` | `obj.worldPosition` (getter, no temp vec needed) |
+| `obj.traverse(cb)` | `obj.traverse(cb)` (same — it's Three.js underneath) |
+| `obj.children` | `obj.children` (same) |
+| `obj.parent` | `obj.parent` (same) |
+| `raycaster.intersectObjects()` | `this.context.physics.raycast()` (auto BVH, faster) |
+| `renderer.setAnimationLoop(cb)` | `update() {}` in a component, or `onUpdate(cb)` hook |
+| `clock.getDelta()` | `this.context.time.deltaTime` |
+| `new GLTFLoader().load(url)` | `AssetReference.getOrCreate(base, url)` then `.instantiate()`, or `loadAsset(url)` |
+
+Needle Engine extends `Object3D` with component methods (`getComponent`, `addComponent`, `worldPosition`, `worldQuaternion`, `worldScale`, `worldForward`, `worldRight`, `worldUp`, `contains`, etc.). `this.gameObject` is the `Object3D` a component is attached to. The underlying Three.js API still works directly.
+
+---
+
+## Creating a New Project
+
+```bash
+npm create needle my-app                  # Vite (default)
+npm create needle my-app -t react         # React + Vite
+npm create needle my-app -t vue           # Vue + Vite
+npm create needle my-app -t sveltekit     # SvelteKit
+npm create needle my-app -t nextjs        # Next.js
+npm create needle my-app -t react-three-fiber  # R3F
+```
+
+---
+
+## Vite Plugin System
+
+```ts
+import { defineConfig } from "vite";
+import { needlePlugins } from "@needle-tools/engine/vite";
+
+export default defineConfig(async ({ command }) => ({
+  plugins: [
+    ...(await needlePlugins(command, {}, {})),
+  ],
+}));
+```
+
+---
+
+## Deployment
+
+- **Needle Cloud** — `npx needle-cloud deploy`
+- **Vercel / Netlify** — standard Vite web app
+- **itch.io** — for games
+- **Any static host / FTP** — `npm run build` (or `npm run build:production`) produces a standard dist folder
+
+From Unity, built-in deployment components (e.g. `DeployToNetlify`) require a PRO license. Needle Cloud deployment works with the free tier.
+
+---
+
+## Progressive Loading (`@needle-tools/gltf-progressive`)
+
+```ts
+import { useNeedleProgressive } from "@needle-tools/gltf-progressive";
+useNeedleProgressive(gltfLoader, renderer);
+gltfLoader.load(url, (gltf) => scene.add(gltf.scene));
+```
+
+In Needle Engine projects this is built in — configure via **Compression & LOD Settings** in Unity.
+
+---
+
+## Searching the Documentation
+
+Use the `needle_search` MCP tool to find relevant docs, forum posts, and community answers:
+
+```
+needle_search("how to play animation clip from code")
+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.
+
+---
+
+## Common Gotchas
+
+- `@registerType` is required or the component won't be instantiated from GLB (Unity/Blender export adds this automatically, but hand-written components need it)
+- GLB assets go in `assets/`, static files (fonts, images) in `public/` (configurable via `needle.config.json`)
+- `useDefineForClassFields: false` must be set in `tsconfig.json` — otherwise decorators silently break field initialization
+- `@syncField()` only triggers on reassignment — mutating an array/object in place won't sync; do `this.arr = this.arr`
+- Physics callbacks (`onCollisionEnter` etc.) require a Needle `Collider` component on the GameObject
+- `removeComponent()` does NOT call `onDestroy` — use `destroy(obj)` for full cleanup
+- Prefer `instantiate()` and `destroy()` functions over `GameObject.instantiate()` / `GameObject.destroy()`
+- `loadAsset()` returns a model wrapper (not an Object3D) — use `.scene` to get the root Object3D
+- `AssetReference.getOrCreateFromUrl()` caches by URL — loading the same URL twice returns the same Object3D. Use `.instantiate()` or `loadAsset()` with `{ context }` for multiple copies
+
+---
+
+## References
+
+For detailed API usage, read these reference files:
+
+- [Full API Reference](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/api.md) — lifecycle, decorators, context API, animation, networking, XR, physics
+- [Framework Integration](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/integration.md) — React, Svelte, Vue, vanilla JS examples + SSR patterns
+- [Troubleshooting](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/troubleshooting.md) — common errors and fixes
+- [Component Template](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/templates/my-component.ts) — annotated starter component
+
+## Important URLs
+
+- Docs: https://engine.needle.tools/docs/
+- Samples: https://engine.needle.tools/samples/
+- GitHub: https://github.com/needle-tools/needle-engine-support
+- npm: https://www.npmjs.com/package/@needle-tools/engine