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