@needle-tools/engine 4.16.0 → 4.16.1-next.b4c9779

package/CHANGELOG.md

@@ -4,6 +4,9 @@ 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.1] - 2026-03-09
+- Fix: Regression causing error in react
+
 ## [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`:

package/README.md

@@ -1,63 +1,31 @@
-# Needle Engine 
+# Needle Engine
 
-**Needle Engine** is a web engine for high quality 3D applications with performance in mind.
+**Needle Engine** is a web-first 3D framework built on [three.js](https://threejs.org/) for building games, configurators, AR/VR experiences, and interactive websites.
 
-Built on three.js and the glTF standard, Needle Engine delivers flexible, extensible web experiences with built-in collaboration and XR support.
+`Built-in: Rapier Physics | WebXR (incl. iOS) | Multiplayer & VOIP | Blender & Unity Integration`
 
-## Quick Links
-🏓 [Changelog](https://github.com/needle-tools/needle-engine-support/releases) • 📑 [Documentation](https://docs.needle.tools) • 🧠 [Sample Scenes](https://samples.needle.tools) • 💎 [Showcase](https://engine.needle.tools/samples/?overlay=showcase)
-
-## Key Features
-
-**🎮 Development Experience**
-- Component system with easy custom component creation
-- Unity and Blender integrations for familiar workflows
-- Multi-scene support with dynamic content loading
-
-**🌐 Web & XR Ready**
-- WebXR support for immersive experiences on Android and iOS ([yes! WebXR on iOS!](https://engine.needle.tools/docs/how-to-guides/xr/ios-webxr-app-clip.html))
-- Interactive QuickLook support for interactive AR on Vision Pro
-- Built-in networking and collaboration
+Built on three.js and the glTF standard, Needle Engine delivers flexible, extensible web experiences with built-in collaboration and XR support. Use it standalone with npm or with powerful editor integrations for Unity and Blender.
 
-**⚡ Performance Optimized**
-- Progressive texture and mesh loading
-- Automatic LOD generation for textures and meshes
-- Advanced PBR rendering with lightmap support
-
-**🎬 Animation & Effects**
-- Animation state machines and timeline animations
-- Physics simulation
-- Post-processing effects
-- Animate anything with ease
-
-[→ See all features](https://docs.needle.tools/features)
-
-## Editor Integrations
-
-**Powerful integrations for Unity and Blender** allow artists and developers to collaborate and manage web applications inside battle-tested 3d editors. Needle Engine integrations allow you to use editor features for exporting models, author materials, animate and sequence animations, bake lightmaps and more.   
-- 🎲 [Download Unity Integration](https://engine.needle.tools/downloads/unity)
-- 🐵 [Download Blender Integration](https://engine.needle.tools/downloads/blender)
-- 📜 [Use with Code](https://engine.needle.tools/docs/three/)
+## Quick Links
+[Changelog](https://github.com/needle-tools/needle-engine-support/releases) | [Documentation](https://docs.needle.tools) | [Samples](https://samples.needle.tools) | [Showcase](https://engine.needle.tools/samples/?overlay=showcase) | [API Reference](https://engine.needle.tools/docs/api/latest)
 
 ## Getting Started
 
-**Quick Start with npm:**
 ```bash
 npm install @needle-tools/engine
 ```
 
-**Or use our Editor Integrations:** Follow the [Getting Started Guide](https://docs.needle.tools/getting-started) to download and install Needle Engine with Unity or Blender.
-
-**Explore Examples:** [Try our interactive samples](https://engine.needle.tools/samples) to see what's possible ⚡
+[Try it now on StackBlitz](https://engine.needle.tools/new) | [Getting Started Guide](https://docs.needle.tools/getting-started)
 
-## Basic Usage
+## Code Examples
 
-### Creating a Custom Component
+### Custom Component
 
 ```typescript
 import { Behaviour, serializable } from "@needle-tools/engine";
 
 export class MyComponent extends Behaviour {
+
     @serializable()
     speed: number = 1;
 
@@ -71,7 +39,42 @@ export class MyComponent extends Behaviour {
 }
 ```
 
-### Using Lifecycle Hooks (without components)
+### Physics with Rapier (built-in)
+
+```typescript
+import { Behaviour, Rigidbody, BoxCollider } from "@needle-tools/engine";
+
+export class PhysicsBox extends Behaviour {
+    
+    awake() {
+        // Add a physics body — Rapier is built in, no extra install needed
+        const rb = this.gameObject.addComponent(Rigidbody);
+        rb.useGravity = true;
+
+        // Add a collider
+        this.gameObject.addComponent(BoxCollider);
+    }
+}
+```
+
+### Multiplayer with @syncField
+
+```typescript
+import { Behaviour, syncField } from "@needle-tools/engine";
+
+export class SyncedCounter extends Behaviour {
+    // Automatically synced across all connected clients
+    @syncField()
+    count: number = 0;
+
+    onPointerClick() {
+        // Reassign to trigger sync (this is required for sync to work)
+        this.count = this.count + 1;
+    }
+}
+```
+
+### Lifecycle Hooks (no component needed)
 
 ```typescript
 import { onStart, onUpdate } from "@needle-tools/engine";
@@ -85,11 +88,54 @@ onUpdate((context) => {
 });
 ```
 
-[→ See API Documentation](https://engine.needle.tools/docs/api/latest)
+## Key Features
+
+**WebXR & AR** — immersive experiences on Android and iOS
+- WebXR support including [WebXR on iOS](https://engine.needle.tools/docs/how-to-guides/xr/ios-webxr-app-clip.html)
+- `WebXRImageTracking` — AR image targets with full tracking lifecycle
+- `WebXRPlaneTracking` — AR surface detection
+- Interactive QuickLook for AR on Vision Pro
+
+**Scene & Asset Management**
+- `SceneSwitcher` — load different scenes by URL
+- `AssetReference` — runtime asset loading by URL
+- `NestedGltf` — lazy-load GLB files on demand within a scene
+- Multi-scene support with dynamic content loading
+
+**Physics & Interaction** — Built-in [Rapier](https://rapier.rs/) physics engine
+- `Rigidbody`, `BoxCollider`, `SphereCollider`, `MeshCollider` — full physics simulation
+- `CharacterController` — movement with gravity, slopes, and steps
+- `DragControls` — click-and-drag 3D objects with zero code
+- `SpatialTrigger` — proximity and enter-zone detection
+
+**Multiplayer & Networking** — real-time collaboration out of the box
+- `SyncedRoom` + `@syncField()` — automatic state synchronization
+- `Voip` — built-in WebRTC voice chat
+- `PlayerSync` — player object sync on join/leave
+- `SyncedCamera` — camera sync for observer sessions
+
+**Rendering & Effects**
+- Advanced PBR rendering with lightmap support
+- Post-processing (Bloom, DepthOfField, SSAO, ChromaticAberration, and more)
+- Progressive texture and mesh loading with automatic LOD generation
+
+**Animation & Media**
+- Animation state machines and timeline animations
+- `VideoPlayer` — full video playback component
+- `AudioSource` — 3D spatial audio
+- Animate anything via [KHR_animation_pointer](https://github.com/nicolo-ribaudo/glTF/tree/animation-pointer/extensions/2.0/Khronos/KHR_animation_pointer)
+
+**Framework Integration** — works with React, Vue, Svelte, or vanilla JS/TS
+
+[See all features](https://docs.needle.tools/features)
+
+## Editor Integrations
 
----
+Needle Engine works standalone with just npm — no editor required. For asset-heavy workflows, use our editor integrations:
 
-*Available under commercial and educational licenses*
+- [Download Unity Integration](https://engine.needle.tools/downloads/unity)
+- [Download Blender Integration](https://engine.needle.tools/downloads/blender)
+- [Code-only workflow docs](https://engine.needle.tools/docs/three/)
 
 ## Examples
 

package/SKILL.md

@@ -1,30 +1,22 @@
 ---
 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"
+description: >
+  Provides Needle Engine context for web-based 3D projects built on Three.js
+  with the @needle-tools/engine component system. Use this skill whenever the user
+  is working with Needle Engine components, GLB files exported from Unity or Blender,
+  Vite configs with needlePlugins, TypeScript classes extending Behaviour, or anything
+  involving @needle-tools/engine imports. Also trigger when the user mentions
+  "needle engine", "needle tools", serializable decorators (@serializable, @syncField,
+  @registerType), the <needle-engine> web component, or 3D scenes loaded from GLB
+  in a web context — even if they don't explicitly name the engine.
+compatibility:
+  - optional: needle_search MCP tool (search Needle Engine docs, forum posts, and community answers)
 ---
 
 # 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
@@ -48,7 +40,7 @@ export class HelloWorld extends Behaviour {
 }
 ```
 
-> **TypeScript config required:** `tsconfig.json` must have `"experimentalDecorators": true` and `"useDefineForClassFields": false` for decorators to work.
+> ⚠️ **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.
 
 ---
 
@@ -208,26 +200,26 @@ 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()`
+- `@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`)
+- `useDefineForClassFields: false` must be set in `tsconfig.json` — otherwise TypeScript overwrites decorated fields with their defaults after the decorator runs, silently breaking serialization
+- `@syncField()` only triggers on reassignment — mutating an array/object in place won't sync. Do `this.arr = this.arr` to force a sync event.
+- Physics callbacks (`onCollisionEnter` etc.) require a Needle `Collider` component (BoxCollider, SphereCollider ...) on the GameObject — they won't fire on mesh-only objects
+- `removeComponent()` does NOT call `onDestroy` — any cleanup logic in `onDestroy` (event listeners, timers, allocated resources) will be skipped. Use `destroy(obj)` for full cleanup.
+- Prefer the standalone `instantiate()` and `destroy()` functions over `GameObject.instantiate()` / `GameObject.destroy()` — the standalone versions are the current API
 - `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
+- `AssetReference.getOrCreateFromUrl()` caches by URL — loading the same URL twice returns the same Object3D. Use `.instantiate()` or `loadAsset()` with `{ context }` for multiple independent copies
 
 ---
 
 ## References
 
-For detailed API usage, read these reference files:
+Read these **only when needed** — don't load them all upfront:
 
-- [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
+- 📖 [Full API Reference](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/api.md) — read when writing component code (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) — read when integrating with React, Svelte, Vue, or vanilla JS
+- 🐛 [Troubleshooting](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/troubleshooting.md) — read when debugging errors or unexpected behavior
+- 🧩 [Component Template](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/templates/my-component.ts) — use as a starting point for new components
 
 ## Important URLs