@needle-tools/engine 4.16.0-next.73c93c0 → 4.16.0

package/plugins/common/needle-engine-skill.md

@@ -1,160 +1,122 @@
 ---
 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.
+You are an expert in Needle Engine — a web-first 3D engine built on Three.js with a Unity/Blender-based workflow.
 
-## When to Use This Skill
+## Key concepts
 
-**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
+**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 GameObjects in Unity are serialized into the GLB and re-hydrated at runtime in the browser.
 
+### Embedding in HTML
 ```html
+<!-- The <needle-engine> web component creates and manages a 3D context -->
 <needle-engine src="assets/scene.glb"></needle-engine>
-<script type="module">
-  import "@needle-tools/engine";
-</script>
 ```
+Access the context programmatically: `document.querySelector("needle-engine").context`
 
-Minimal TypeScript component:
+### Component lifecycle (mirrors Unity MonoBehaviour)
 ```ts
 import { Behaviour, serializable, registerType } from "@needle-tools/engine";
 
 @registerType
-export class HelloWorld extends Behaviour {
-  @serializable() message: string = "Hello!";
-
-  start() {
-    console.log(this.message);
-  }
+export class MyComponent extends Behaviour {
+  @serializable() myValue: number = 1;
+
+  awake()  {}   // called once when instantiated
+  start()  {}   // called once on first frame
+  update() {}   // called every frame
+  onEnable()  {}
+  onDisable() {}
+  onDestroy() {}
+  onBeforeRender(_frame: XRFrame | null) {}
 }
 ```
 
-> **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.
+### Serialization
+- `@registerType` — makes the class discoverable by the GLB deserializer
+- `@serializable()` — marks a field for GLB deserialization (primitives)
+- `@serializable(Object3D)` — for Three.js object references
+- `@serializable(Texture)` — for textures (import Texture from "three")
+- `@serializable(RGBAColor)` — for colors
 
-- **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
+### Accessing the scene
+```ts
+this.context.scene       // THREE.Scene
+this.context.mainCamera  // active camera (THREE.Camera)
+this.context.renderer    // THREE.WebGLRenderer
+this.context.time.frame  // current frame number
+this.context.time.deltaTime  // seconds since last frame
+this.gameObject          // the THREE.Object3D this component is on
+```
 
-### `<needle-engine>` Attributes
+### Finding components
+```ts
+this.gameObject.getComponent(MyComponent)
+this.gameObject.getComponentInChildren(MyComponent)
+this.context.scene.getComponentInChildren(MyComponent)
+
+// Global search (import as standalone functions from "@needle-tools/engine")
+import { findObjectOfType, findObjectsOfType } from "@needle-tools/engine";
+findObjectOfType(MyComponent, this.context)
+findObjectsOfType(MyComponent, this.context)
+```
 
-Boolean attributes can be disabled with `="0"` (e.g. `camera-controls="0"`).
+### Input handling
+```ts
+// Polling
+if (this.context.input.getPointerDown(0)) { /* pointer pressed */ }
+if (this.context.input.getKeyDown("Space")) { /* space pressed */ }
 
-```html
-<needle-engine
-  src="assets/scene.glb"
-  camera-controls
-  auto-rotate
-  autoplay
-  background-color="#222"
-  environment-image="studio"
-  contactshadows
-></needle-engine>
+// Event-based (NEPointerEvent works across mouse, touch, and XR controllers)
+this.gameObject.addEventListener("pointerdown", (e: NEPointerEvent) => { });
 ```
 
-| 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 |
+### Physics & raycasting
+```ts
+// Default raycasts hit visible geometry — no colliders needed
+// Uses mesh BVH (bounding volume hierarchy) for accelerated raycasting, BVH is generated on a worker
+const hits = this.context.physics.raycast();
 
----
+// Physics-based raycasts (require colliders, uses Rapier physics engine)
+const physicsHits = this.context.physics.raycastPhysics();
+```
 
-## 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)` |
+### Networking & multiplayer
+Needle Engine has built-in multiplayer. Add a `SyncedRoom` component to enable networking.
 
----
+- `@syncField()` — automatically syncs a field across all connected clients
+- Primitives (string, number, boolean) sync automatically on change
+- Complex types (arrays/objects) require reassignment to trigger sync: `this.myArray = this.myArray`
+- Key components: `SyncedRoom`, `SyncedTransform`, `PlayerSync`, `Voip`
+- Uses WebSockets + optional WebRTC peer-to-peer connections
 
-## 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.
+### WebXR (VR & AR)
+Needle Engine has built-in WebXR support for VR and AR across Meta Quest, Apple Vision Pro, and mobile AR.
 
----
+- Add the `WebXR` component to enable VR/AR sessions
+- Use `XRRig` to define the user's starting position — the user is parented to the rig during XR sessions
+- Available components: `WebXRImageTracking`, `WebXRPlaneTracking`, `XRControllerModel`, `NeedleXRSession`
 
-## Creating a New Project
+## Creating a new project
 
+Use `create-needle` to scaffold a new Needle Engine 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
+npm create needle my-app            # default Vite template
+npm create needle my-app -t react   # React template
+npm create needle my-app -t vue     # Vue.js template
 ```
 
----
+Available templates: `vite` (default), `react`, `vue`, `sveltekit`, `svelte`, `nextjs`, `react-three-fiber`.
 
-## Vite Plugin System
+Use `npm create needle --list` to see all available templates.
+
+## Vite plugin system
+
+Needle Engine ships a set of Vite plugins via `needlePlugins(command, config, userSettings)`. Custom project plugins go in `vite.config.ts`.
 
 ```ts
 import { defineConfig } from "vite";
@@ -167,71 +129,47 @@ export default defineConfig(async ({ 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
+Projects can be deployed to:
+- **Needle Cloud** — official hosting with automatic optimization (`npx needle-cloud deploy`)
+- **Vercel** / **Netlify** — standard web hosting
+- **itch.io** — for games and interactive experiences
+- **Any static host** — Needle Engine projects are standard Vite web apps
 
-From Unity, built-in deployment components (e.g. `DeployToNetlify`) require a PRO license. Needle Cloud deployment works with the free tier.
+From Unity, use built-in deployment components (e.g. `DeployToNeedleCloud`, `DeployToNetlify`).
 
----
+## Progressive loading (`@needle-tools/gltf-progressive`)
 
-## Progressive Loading (`@needle-tools/gltf-progressive`)
+Needle Engine includes `@needle-tools/gltf-progressive` for progressive streaming of 3D models and textures. It creates a tiny initial file with embedded low-quality proxy geometry, then streams higher-quality LODs on demand. Results in ~90% smaller initial downloads with instant display.
 
+Works standalone with any three.js project:
 ```ts
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { WebGLRenderer } from "three";
 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
+const gltfLoader = new GLTFLoader();
+const renderer = new WebGLRenderer();
 
-Use the `needle_search` MCP tool to find relevant docs, forum posts, and community answers:
+// Register once — progressive loading happens automatically for all subsequent loads
+useNeedleProgressive(gltfLoader, renderer);
 
+gltfLoader.load(url, (gltf) => scene.add(gltf.scene));
 ```
-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
+In Needle Engine projects, progressive loading is built in and can be configured via the **Compression & LOD Settings** component in Unity.
 
 ## 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
+
+## Searching the documentation
+
+Use the `needle_search` MCP tool to find relevant docs, forum posts, and community answers.
+
+## Common gotchas
+- Components must use `@registerType` or they won't be instantiated from GLB (this is handled automatically when exporting from Unity or Blender, but must be added manually for hand-written components)
+- GLB assets are in `assets/`, static files in `include/` or `public/`

package/plugins/vite/ai.js

@@ -42,7 +42,7 @@ function writeSkill(claudeDir) {
         mkdirSync(skillDir, { recursive: true });
     }
     const skillPath = join(skillDir, "SKILL.md");
-    const templatePath = join(__dirname, "../common/needle-engine-skill.md");
+    const templatePath = join(__dirname, "../../SKILL.md");
     const content = readFileSync(templatePath, "utf8");
     writeFileSync(skillPath, content, "utf8");
     return skillPath;