Needle Engine

Needle Engine is a web-first 3D framework built on three.js for building games, configurators, AR/VR experiences, and interactive websites.

Built-in: Rapier Physics | WebXR (incl. iOS) | Multiplayer & VOIP | Blender & Unity Integration

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.

Quick Links

Changelog | Documentation | Samples | Showcase | API Reference

Getting Started

npm install @needle-tools/engine

Try it now on StackBlitz | Getting Started Guide

Code Examples

Custom Component

import { Behaviour, serializable } from "@needle-tools/engine";

export class MyComponent extends Behaviour {

    @serializable()
    speed: number = 1;

    start() {
        console.log("Component started on:", this.gameObject.name);
    }

    update() {
        this.gameObject.rotateY(this.context.time.deltaTime * this.speed);
    }
}

Physics with Rapier (built-in)

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

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)

import { onStart, onUpdate } from "@needle-tools/engine";

onStart((context) => {
    console.log("Engine started!");
});

onUpdate((context) => {
    // Called every frame
});

Key Features

WebXR & AR — immersive experiences on Android and iOS

WebXR support including WebXR on iOS
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 / hierarchies by URL
AssetReference — runtime asset loading by URL
Multi-scene support with dynamic content loading

Physics & Interaction — Built-in Rapier physics engine

Rigidbody, BoxCollider, SphereCollider, MeshCollider — full physics simulation
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
Low level networking events for full control

Rendering & Effects

Advanced PBR rendering with lightmap support
Post-processing (Bloom, DepthOfField, SSAO, ChromaticAberration, Tonemapping 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

Framework Integration — works with React, Vue, Svelte, or vanilla JS/TS

See all features

Editor Integrations

Needle Engine works standalone with just npm — no editor required. For asset-heavy workflows, use our editor integrations:

Examples

Example	Description	Links
Multiuser Cross device experience, Desktop, AR & VR (Sandbox)	Real-time collaborative multiplayer sandbox experience with WebXR on Android and iOS
Image Tracking AR	AR image tracking example (iOS and Android). See docs
Scrollytelling Bike Example	Timeline Animation using ScrollFollow, ViewBox and FocusRect	Project on Github
See-Through Walls	See-Through component sample
Cursor Follow	Cursor Follow sample
Animate Anything	Interactive animation system	Code on Stackblitz • three.js Example
Postprocessing Effects	Custom magnifier effect with post-processing	Code on Stackblitz
Unity ShaderGraph to MaterialX & mtlx materials	Using @needle-tools/materialx
Camera Focus DIV 1	Responsive layout with camera focus	Code on Stackblitz
Camera Focus DIV 2	Click-to-move camera focus example	Code on Stackblitz
FastHDR Loading	10x faster than EXR, non-blocking, 95% less GPU memory	Code on Stackblitz • Learn more
Scrollytelling Example	Scroll, physics and cursor interaction: a playful 3D interactive scrollytelling website	Included in Samples Package
AR Restaurant	Interactive AR restaurant experience	Code on Github
Custom Loading Overlay	Wait for LODs with custom loading states	Code on Stackblitz
React Shopping Cart	E-commerce integration with React	Code on Stackblitz

👋 More examples on samples.needle.tools, docs.needle.tools and in the Needle Engine Stackblitz Collection

Contact ✒️

🌵 Needle • Github • Twitter • Discord • Forum • Youtube

Recent Changes

[5.1.0-alpha.2] - 2026-04-13

NEW: Scene Bindings (experimental) — auto-generated TypeScript types from your glTF scenes, providing typed access to nodes, components, and properties via ctx.sceneData or needle.sceneData. Types are generated automatically by a Vite plugin whenever your scene files change — no configuration needed. Works with both local and remote (Needle Cloud) assets. The API shape (particularly $components and $object accessors) may evolve based on feedback. Can be disabled with dts: { enabled: false } in your Vite plugin config.
```
// fully typed, with autocomplete for every node and component
const cam = ctx.sceneData.MyScene.MainCamera.$object;                      // THREE.PerspectiveCamera
const orbit = ctx.sceneData.MyScene.MainCamera.$components.OrbitControls;  // typed!
```
NEW: SSR support (experimental) — import Needle Engine in Node.js/SSR frameworks (SvelteKit, Next.js, Nuxt) without ReferenceError crashes. The engine now provides SSR-safe base classes and skips browser-dependent initialization on the server. Core rendering still happens client-side — SSR support means your app can import and reference engine code server-side without errors.
NEW: JSX type declarations for <needle-engine> and other web components — first-class support for React, Preact, SolidJS, and other JSX-based frameworks with full autocomplete and type checking
NEW: context.lights array and context.mainLight getter for easy access to all scene lights and the primary directional light
Add: needlePlugins() can now be called without arguments — the Vite command is resolved automatically. This simplifies setup in frameworks like SvelteKit where defineConfig doesn't expose the command:
```
export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
```
Fix: BloomEffect and Sharpening were pulling in the entire postprocessing library even in projects that don't use postprocessing, increasing bundle size unnecessarily
Fix: SceneSwitcher now shows the object name in the URL when referencing scene objects (instead of just an index)
Improved: Vite plugin reliability (fewer unnecessary reloads, cleaner log output)

[5.1.0-alpha.1] - 2026-04-10

Add: AnimatorControllerBuilder for building animator controllers from code (experimental)
Add: XR global events now return an unsubscribe function + onBeforeXRSessionRequest event
Add: getComponent by string name (experimental)
Add: FastHDR (PMREM) support for GroundProjection
Fix: setParamWithoutReload losing URL hash
Fix: Physics treeshaking when used in code-only projects
Improved: Vite logger with "latest" symlink, mobile fix, and more readable timestamps (at node_modules/.needle/logs). This is useful for local AI to help debug

[5.1.0-alpha] - 2026-04-07

Networking

Add: VOIP volume property and speaking event
Add: onSyncInstantiate and onSyncDestroy callbacks
Change: requestOwnership now returns a Promise
Change: addComponent generates deterministic component GUIDs for reliable networking of runtime-added components
Change: syncInstantiate automatically adds to prefabProvider and assigns GUID

Rendering

Add: MaterialX Voronoi node "cell" output
Add: Postprocessing tests
Change: Postprocessing moved to core — accessible via context.postprocessing and exported from @needle-tools/engine
Improved: Tonemapping without other postprocessing effects is now applied directly to the renderer, avoiding an unnecessary postprocessing pass
Fix: MaterialPropertyBlock multimaterial change from opaque to transparent

XR

Improved: iOS AppClip AR session now opens reliably on first visit and first tap
Fix: XR light intensity in scaled sessions

UI

Fix: HTML mobile icon not rendering
Fix: UI Text component absolute font URL handling

[5.0.2] - 2026-04-03

Updated @needle-tools/materialx to 1.6.0:
- UV coordinate convention handling (glTF ↔ OpenGL) — fixes UV-dependent effects like displacement and procedural noise in the browser
- Material-level ambient occlusion for gltf_pbr materials per the glTF specification
- Visual graph editor for interactive MaterialX authoring
Fix: Light intensity in scaled AR session