6.0.0-alpha.1

Needle Engine

Added

• GaussianSplat component (experimental) — load .ply / .spz / .sog splats via Spark, with LOD and correct raycasting/bounds
• WebXR: anchors (useAnchors) are now enabled by default

Changed

• Updated bundled three.js to r185
• Updated MaterialX runtime
• Improved XR error messaging when a session can't start

Fixed

• WebXR: setSession now works with WebXR emulators/polyfills that supply a non-native session (falls back to the XRWebGLLayer path)
• Bounds are reported as incomplete for still-loading async objects, and GroundProjection re-fits once they're ready
• Raycasting and bounds now work for non-Mesh objects (e.g. splats)
• Custom model loaders are no longer tree-shaken out in code-only projects
• SSR: various import/emit fixes
• Postprocessing: pipeline build failures are now surfaced instead of failing silently

Unity Integration

• Updated build pipeline to @needle-tools/gltf-build-pipeline 4.0 — adds compressed splat (SOG) support and replaced-source events

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.7

Needle Engine

• AR: scenes now stay anchored to the real world (WebXR anchors, on by default) — placement survives tracking loss and keeps user adjustments; falls back to plain placement where unsupported
• XR: clearer error when the device or browser blocks AR/VR (instead of a misleading "configuration not supported")
• SSR: fixed builds in SvelteKit, Next.js and Nuxt ("Entry module cannot be external") and a navigator crash during server-side rendering
• Vite: hint for PRO licenses on multi-team Needle Cloud accounts, and guidance for a known Rolldown crash in Vite 8.1
• Updated MaterialX to 1.7.4 (instancing transforms in nodegraph functions, stable glossy reflections with prefiltered KTX2 environments)

Unity Integration

• WebXR component: Use XR Anchor is now enabled by default for new components and scene templates. Existing scenes keep their saved value — enable the checkbox to opt in.

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.5

Needle Engine

Changed

• DragControls: improved 2D rotation
• XR: networked controllers and hands now sync by handedness for more reliable multiplayer avatars

Unity Integration

• Unity 6000.5 support

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.4

Needle Engine

Fixed

• iOS AR: more reliable Needle App Clip launch from the Enter AR button
• Needle Go: AR screenshots via screenshot2 — capture and share photos of your AR experience right from the session
• GroundProjection: AR background blending stays intact when the camera clears the background

Unity Integration

• Login: console login prompts are now clickable, with a one-time auto-login on Play

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.3

Needle Engine

Fixed

• Audio sources now clone correctly

• Objects with HideFlags export reliably

• Corrected the default camera field of view

• Added: the bundled dist/three now exposes the full Three.js API for import-map setups

• Changed: updated MaterialX to 1.7.1:

  • Environment radiance sampling (PMREM & importance sampling)
  • Automatic tangent generation
  • Upgraded runtime to MaterialX 1.39.5
  • Improved texture, alpha, and environment handling
  • Uses the app's Three.js via import maps (no duplicate three) — shares Needle Engine's Three.js
  • Runs in the browser, Node, Deno, and Bun

Unity Integration

• DragControls options are now available in the inspector

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.2

Needle Engine

Fixed

• SyncedTransform: added world scale support — networked objects now keep the correct scale across clients, even when nested under scaled parents, with smooth interpolation
• AR & XR improvements: networked avatars now use the correct scale, stale avatars are reliably removed after a peer disconnects, and remote hands display correctly in Screen AR

Unity Integration

• Fix: MaterialX importer in the editor

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.0

⭐ Highlights

Scene Bindings — Fully Typed Scenes (preview)

Your glTF and GLB scenes now come with auto-generated TypeScript types. Access nodes, components, and properties with full autocomplete and type checking via ctx.sceneData or the new needle shorthand — no configuration required. Types regenerate automatically whenever your scene files change, and it works with local files, remote URLs, and Needle Cloud assets alike.

const cam   = ctx.sceneData.MyScene.MainCamera.$object;                      // THREE.PerspectiveCamera
const orbit = ctx.sceneData.MyScene.MainCamera.$components.OrbitControls;    // typed!
orbit.autoRotate = true;

First-Class Framework Support (preview)

Needle Engine now feels at home in any modern web stack. SSR support lets you import the engine in SvelteKit, Next.js, and Nuxt without crashes, JSX type declarations bring full autocomplete to React, Preact, SolidJS, and friends, and the new needle shorthand gives you instant access to the current context from anywhere — components, button handlers, or plain JavaScript.

import { needle } from "@needle-tools/engine";
needle.scene.traverse(obj => { ... });   // access the three.js scene
needle.renderer;                          // access the WebGLRenderer

Embed Anywhere with <needle-app>

Drop a published Needle Engine app into any web page with a single element — no build setup, custom code, or framework required. It handles cross-origin loading for you and works inside iframes.

<needle-app src="https://your-app.needle.run"></needle-app>

Animation & Timelines from Code (preview)

A new set of builder APIs lets you create animations, animator controllers, and timelines entirely in code, with typed keyframes and inline track definitions. Great for procedural content, runtime-generated sequences, and tooling.

const timeline = TimelineBuilder.create("MyTimeline")
    .animationTrack("Walk", animator).clip(walkClip, { duration: 2 })
    .activationTrack("FX", vfxObject).activate({ start: 1, duration: 0.5 })
    .build();
director.playableAsset = timeline;

A More Powerful Compression Pipeline

The build pipeline gets a major upgrade with new ways to shrink your builds automatically. Audio compression turns heavy WAV files into compact, web-friendly clips, and HDRi → PMREM (FastHDR) compression converts environment maps into a format that loads up to 10× faster and uses a fraction of the GPU memory — all on top of the existing Draco/meshopt geometry and KTX2 texture compression. Smaller downloads, faster loads, no manual work.

DragControls — A Big Upgrade

DragControls received a major overhaul with a new constraint system: keep-scale, two-touch scaling with min/max limits, refined hit regions, and a dedicated screen-space drag mode for AR. Single-touch dragging is now more predictable, and reliability is improved across snapping, side views, and multi-input scenarios.

MaterialX — Faster & Richer

The bundled MaterialX runtime jumps to 1.7.0 with faster environment lighting (new radiance sampling modes and PMREM support), better Three.js integration, and overall performance improvements. MaterialX export from Needle Engine projects no longer requires a PRO license.

Needle AI in the Editor

Needle AI is integrated directly into the Unity inspector and hierarchy, with awareness of your local Unity and web project so its assistance is relevant to what you're actually building.

Needle Engine

Added

• Scene Bindings (preview) — auto-generated, fully typed access to your scenes via ctx.sceneData / needle.sceneData
• SSR support (preview) for SvelteKit, Next.js, and Nuxt, plus JSX type declarations for React, Preact, SolidJS and more
• needle shorthand (preview) for quick access to the current engine context from anywhere
• <needle-app> — embed a published Needle Engine app in any web page (docs)
• Context.events — a typed event bus for decoupled component communication:

  context.events.on("scene-content-changed", e => console.log(e.object));
  context.events.emit<{ pts: number }>("scored", { pts: 10 });

• autoCleanup on Behaviour — register disposables and cleanup tied to the component lifecycle
• Builder APIs (preview) — TimelineBuilder, AnimatorControllerBuilder, and AnimationBuilder for defining timelines, controllers, and animations in code with typed keyframes and inline tracks
• DragControls: new constraint system with keepScale, two-touch scale limits, refined hit regions, a screen-space AR drag mode, and EventList support
• Skybox: new background-rotation / environment-rotation attributes and background-image-loaded / environment-image-loaded events
• WebXRImageTracking: per-frame imageTracked event with typed access to the tracked object, plus resetImage / resetAllImages to re-arm markers without restarting XR
• AudioClip type with standalone playback control, AudioSource spatial blend and .opus support
• context.lights array and context.mainLight getter for quick access to scene lighting
• NeedleXRSession.appClipUrl — launch a custom-branded Needle AppClip experience on iOS AR (provide your registered appclip.needle.tools/x/… URL or experience id) for your own App Clip card title and image
• Physics raycast includeTriggers option
• Unsubscribe functions returned from Input, Networking, and XR event subscriptions
• needlePlugins() can now be called without arguments — the Vite command is resolved automatically

Changed

• OrbitControls now uses lookAtTarget / lockLookAtTarget, with smoother focus and camera transitions
• Postprocessing moved to core (context.postprocessing); tonemapping-only setups skip the extra pass
• Timeline track classes renamed for consistency (e.g. AnimationTrackHandler → TimelineAnimationTrack)
• GroundProjectionEnv.applyOnAwake now defaults to true, matching Unity and Blender

Fixed & Improved

• Major DragControls reliability improvements across snap points, AR drag, side views, and multi-input handover
• More reliable camera handling (fallback camera, fitCamera, scene clearing)
• More efficient Skybox attribute handling and load deduplication
• Smoother, more reliable progressive LOD loading and disposal, including texture-only LODs that update correctly with camera distance
• AudioSource on iOS now survives a device lock / audio-session interruption and resumes automatically
• SceneSwitcher: ?scene= honored for in-scene object references, with prefab preview support
• VoIP improvements including better iOS mic handling and shared AudioContext
• Faster initial loading via improved dependency chunking
• General reliability and stability improvements throughout the engine and Vite plugin

MaterialX

• Updated bundled MaterialX runtime to 1.7.0 — faster environment lighting (new radiance sampling modes, PMREM support), better Three.js integration (texture sampling, environment rotation, alpha modes), and overall performance improvements
• MaterialX export in Needle Engine projects no longer requires a PRO license

Unity Integration

• Updated build pipeline with WAV audio compression and HDRi → PMREM (FastHDR) compression for smaller, faster-loading builds
• Needle AI chat integration with inspector and hierarchy context menus, pulling context from your local Unity and web project for more relevant assistance
• SceneSwitcher improvements: drag-and-drop, per-scene toggle buttons, unload button, preview, and scene closing
• WebXRImageTracking component now exposes an imageTracked UnityEvent
• Component Compiler: new // @header directive emits a Unity [Header(...)] attribute to group and label fields in the inspector (works alongside // @tooltip):

  // @header Movement Settings
  @serializable()
  speed: number = 1;

• Add: context menu action to compress the output directory (useful when a scene uses SceneSwitcher with dependencies)
• Updated needle-cloud CLI to version 2 with security hardening
• Sample search now matches tags and ranks results by relevance
• Improved editor connection stability with better error recovery and cleanup

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.0-alpha.9

Needle Engine

Added

• <needle-app> — embed a published Needle Engine app in any web page (with custom code etc) (docs)

Changed

• <needle-app>: improved cross-origin handling and src parsing
• ScrollFollow: now works inside an iframe (uses the top window)

Fixed

• iOS audio: AudioSource playback now survives a device lock / audio-session interruption and resumes automatically on unlock
• SceneSwitcher: ?scene= is now honored for scenes referenced as in-scene Object3Ds; scene preview loading supports prefabs and correct parenting under the SceneSwitcher
• DragControls: widened the two-pointer scale clamp range and now reads world scale from the matrix columns
• EventList: corrected the arguments passed to overridden methods
• serializeObject: fixed Color / Euler / object-reference serialization, and OneEuroFilter.reset()
• Prevented a TypeError when a scene-data error proxy is coerced to a string

Unity Integration

Fixed

• Needle Component menu: fixed a null-reference on non-GameObject inspectors, handling of multiple targets and locked inspectors, and the "Add Needle Component" button is now hidden for objects flagged NotEditable

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

4.16.11

Needle Engine

• Fix: iOS audio — AudioSource playback now survives a device lock / audio-session interruption and resumes automatically on unlock
• Fix: typeof window/globalThis !== undefined guards were always true and could throw outside a browser (SSR / Node)

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples

5.1.0-alpha.7

Highlights:

• Major DragControls upgrade — new constraint system with scale limits, refined regions, and a dedicated AR drag mode
• Updated MaterialX runtime with faster environment lighting and PMREM support
• Updated Unity build pipeline with WAV audio and HDRi (FASTHDR) compression

Needle Engine

Added

• DragControls received a substantial round of improvements with a new constraint system, including a keepScale option, a two-touch scale constraint with min/max limits, refined hit regions, and a dedicated screen-space AR drag mode
• Skybox: new background-rotation and environment-rotation HTML attributes, plus background-image-loaded and environment-image-loaded events to react to skybox load completion
• Input: input cancellation support (e.g. when a pointer is disconnected mid-interaction)
• loadPMREM: auto-detects image format for extensionless URLs
• AudioSource: .opus clip URLs are now supported
• GroundProjectionEnv.applyOnAwake now defaults to true, matching Unity and Blender behaviour

Changed

• OrbitControls: lockLookAtTarget now preserves the pointer target when double-clicking to focus
• PostProcessing: pixelation granularity adapts dynamically to device pixel ratio
• DragControls: rotation is now limited to two-touch and XR controller input for more predictable single-touch dragging
• Hardened internal logging: secrets (API keys, tokens, JWTs, PEM keys, URL credentials, …) are now redacted before logs are written to disk — a defensive measure so log files shared during debugging never leak credentials

Fixed

• DragControls: improved reliability across snap points, screen-space AR drag mode, double-click handling, XZPlane side-view and Y-axis behaviour, multi-input rotation, and touch handover (NE-4418, NE-5413, NE-5887, NE-5891)
• Camera: improved fallback camera and CameraUtils lifecycle handling, and fitCamera stability when meshes are parented to the target camera
• Context.clear() now resets mainCamera and fallbackCamera so they always point at live cameras after a scene wipe
• Skybox: more efficient attribute handling — load cycles are deduplicated, background-intensity is honoured, and magic-name skyboxes resolve correctly when attributes are set at mount time
• VideoPlayer.isPlaying now reports streamed sources and file playback independently and correctly
• DropListener: loadFromFile now always resolves
• Progressive LOD: more reliable instancing, request scheduling, vertex count handling, texture LOD tracking, and disposal lifecycle
• VoIP: better mic stream handling on iOS, accurate setMuted for incoming streams, clamped volume, shared AudioContext, and coalesced concurrent connect() calls
• Custom model loaders: MIME type check moved earlier so custom loaders reliably take over
• General reliability improvements across webmanifest handling, dependency watcher, DTS generation, AI helper install, and file logger

MaterialX

• Updated bundled MaterialX runtime to 1.7.0 with faster environment lighting (new radiance sampling modes, PMREM support), better integration with Three.js (texture sampling, environment rotation, alpha modes), and overall performance improvements
• Unity: MaterialX export in Needle Engine projects no longer requires a PRO license

Unity Integration

• Updated to @needle-tools/gltf-build-pipeline 3.0 — a major version bump that adds WAV audio compression and HDRi → PMREM (FASTHDR) compression to the build pipeline
• Updated to needle-cloud CLI version 2 with security hardening
• Add: context menu action to compress the output directory (required when a scene uses SceneSwitcher with dependencies)

---

Links

Download for Unity • Download for Blender • Documentation • API • Live Samples