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.10] - 2026-08-07

Add: turn the whole postprocessing stack on or off at runtime with PostProcessing.enabled
Fix: scene brightness no longer shifts when XR hand models are shown or hidden
Fix: the showHandModels toggle now reliably shows or hides XR hand models
Change: SyncedRoom warns (in development) when a room-name URL parameter overrides the roomName set on the component, making it easier to diagnose ending up in an unexpected room

[5.1.9] - 2026-07-30

Added

WebXRImageTracking: friendlier addImage API for registering marker images
Clearer diagnostics for iOS App Clip AR sessions (Needle Go), surfaced to developers (See also /.node_modules/.needle/logs)
Dev warning when a tracked image has an invalid marker size

Fixed

iOS App Clip AR (Needle Go): WebXRImageTracking tracked images are no longer dropped on the first AR entry, and markers now register correctly even when AR starts before the scene has finished loading
iOS App Clip AR (Needle Go) now respects the session's framebuffer scale for correct rendering resolution

[5.1.8] - 2026-07-23

Docs: clarified VR teleport targeting — the teleport ray hits rendered meshes, not physics colliders, so a TeleportTarget needs a visible mesh but no collider

[5.1.7] - 2026-07-17

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)