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 by URL
  • AssetReference — runtime asset loading by URL
  • NestedGltf — lazy-load GLB files on demand within a scene
  • Multi-scene support with dynamic content loading

Physics & Interaction — Built-in Rapier physics engine

  • Rigidbody, BoxCollider, SphereCollider, MeshCollider — full physics simulation
  • CharacterController — movement with gravity, slopes, and steps
  • 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

Rendering & Effects

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

[4.16.1] - 2026-03-09

  • Fix: Regression causing error in react

[4.16.0] - 2026-03-05

  • NEW: makeFilesLocal build option overhauled — builds can now be fully self-contained and work offline. The plugin downloads external CDN assets at build time and bundles them locally. This is essential for playable ads, app stores that require single-origin or self-contained bundles, offline-capable PWAs, and restricted hosting environments. Supports auto-detection of used features, per-feature opt-in/opt-out, and platform presets. Covers Draco decoders, KTX2 transcoders, MaterialX, WebXR input profiles, skybox/environment textures, Google Fonts, third-party scripts, and more. Example in vite.config.js:
    needlePlugin({
      makeFilesLocal: "auto" // auto-detect and download only what your project uses
    })
    // or with fine-grained control:
    needlePlugin({
      makeFilesLocal: {
        enabled: true,
        features: ["draco", "ktx2", "fonts"],
        excludeFeatures: ["xr"]
      }
    })
  • Add: showBalloonMessage now supports duration, once, and key options for controlling message display duration and updating existing messages
  • Add: needleAI vite plugin — when using Claude Code in a Needle Engine project, the engine automatically provides a project-aware AI skill with Needle Engine context
  • Add: DragControls now warns when used on static objects that won't update their transforms
  • Add: AR overlay support for AppClip sessions
  • Improve: Stable three.js chunk names in production builds, enabling CDN import maps with predictable URLs
  • Improve: USDZ export now uses "string" type for input variable names for better spec compatibility
  • Improve: Gizmo rendering uses consistent font from CDN
  • Improve: needle-menu layout with correct padding and minimum width for icon-only elements
  • Improve: Vite project template aligned with online template
  • Improve: Updated MaterialX dependency
  • Improve: JSDoc documentation
  • Fix: ReflectionProbe support for Blender workflows
  • Fix: Mac build error ("-50" error)
  • Fix: PWA defaults when package name is missing
  • Fix: Improved error handling in MaterialX importer

[4.15.0] - 2026-02-27

  • NEW: Accessibility support with screen reader overlay. The engine now maintains a visually-hidden DOM tree mirroring 3D scene objects with ARIA roles and labels. Components like Button, Text, DragControls, and USDZ behavior components automatically register accessible elements.
  • Add: AccessibilityManager accessible via context.accessibility for managing accessible elements, focus, and hover announcements
  • Add: ReflectionProbe now supports assigning a URL string as texture (for Blender workflows)
  • Update: Networking backend migrated to Cloudflare Durable Objects for improved scalability, per-room isolation, and reduced latency
  • Improved MaterialPropertyBlock documentation with examples for material swapping behavior and override management
  • Improved documentation for Networking, OneEuroFilter, and needle-button web component

[4.14.0] - 2026-02-19

  • Add: MaterialPropertyBlock support. This allows you to change material properties of objects without breaking batching and instancing.
    It can be used by calling const block = MaterialPropertyBlock.get(myObject); and then set or remove overrides on the block.
    This even supports the same material being rendered as transparent for one object and opaque for another.
  • Add: Support of ReflectionProbe + Lightmap rendering on the same object
  • Add: CustomShader (Unlit) support with VideoPlayer component
  • Improved ?stats console logs with info about shaders and used memory
  • Improved documentation

For all changes visit Github Releases

Settings

Member Visibility

On This Page

Contact ✒️Recent Changes