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

Preview 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.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

[5.0.0] - 2026-03-27

  • NEW: Compression support for EXR skybox and environment textures (powered by Needle's FastHDR):
    • 10x faster than EXR
    • 95% less GPU memory
    • Zero framedrops
  • NEW: Support for Vite 8, now powered by Rolldown (Rust) for extremely fast bundling
  • NEW: MaterialX Lights and Magic update:
    • Lights and shadow suppport: point lights, spot lights, directional lights
    • Displacement: full support for offset and vector displacement
    • Transparency Modes: auto-detection and support for opaque, transparent, and masked material rendering modes
    • See
  • Change: OrbitControls now uses lookAtTarget and lockLookAtTarget instead of a LookAtConstraint component. The LookAtConstraint component has been deprecated.
  • Change: EventList addEventListener now returns a method that can be called to remove the callback function again: const remove = myEventList.addEventListener(() => { ... })
  • Change: Rapier Physics colliders will now just be disabled instead of removed from the physics world when a Collider component becomes inactive.
  • Change: Postprocessing now has an adaptiveResolution option (default true) which can automatically scale down resolution slightly for Retina or high pixel density screens if performance drops (See the Volume component for more information)
  • Improved: Networking types (Typescript)
  • Improved: Dependencies chunking for faster loading and improved LCP score(Largest Contentful Paint)
  • Fix: NextJS support

For all changes visit Github Releases

Settings

Member Visibility

On This Page

Contact ✒️Recent Changes