# Needle Engine

**Needle Engine** is a web-first 3D framework built on [three.js](https://threejs.org/) 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](https://github.com/needle-tools/needle-engine-support/releases) | [Documentation](https://docs.needle.tools) | [Samples](https://samples.needle.tools) | [Showcase](https://engine.needle.tools/samples/?overlay=showcase) | [API Reference](https://engine.needle.tools/docs/api/latest)

## Getting Started

```bash
npm install @needle-tools/engine
```

[Try it now on StackBlitz](https://engine.needle.tools/new) | [Getting Started Guide](https://docs.needle.tools/getting-started)

## Code Examples

### Custom Component

```typescript
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)

```typescript
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

```typescript
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)

```typescript
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](https://engine.needle.tools/docs/how-to-guides/xr/ios-webxr-app-clip.html)
- `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](https://rapier.rs/) 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](https://github.com/nicolo-ribaudo/glTF/tree/animation-pointer/extensions/2.0/Khronos/KHR_animation_pointer)

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

[See all features](https://docs.needle.tools/features)

## Editor Integrations

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

- [Download Unity Integration](https://engine.needle.tools/downloads/unity)
- [Download Blender Integration](https://engine.needle.tools/downloads/blender)
- [Code-only workflow docs](https://engine.needle.tools/docs/three/)

## Examples

| Preview | Example | Description | Links |
|---------|---------|-------------|-------|
| [![](https://cloud.needle.tools/-/media/WI0Q0s961BjdXgUEQHxifQ.gif)](https://engine.needle.tools/samples/collaborative-sandbox) | [Multiuser Cross device experience, Desktop, AR & VR (Sandbox)](https://engine.needle.tools/samples/collaborative-sandbox) | Real-time collaborative multiplayer sandbox experience with WebXR on Android and iOS |
| [![](https://cloud.needle.tools/-/media/vRUf9BmqW_bgNARATjmfCQ.gif)](https://engine.needle.tools/samples/image-tracking/?room=needle110) | [Image Tracking AR](https://engine.needle.tools/samples/image-tracking/?room=needle110) | AR image tracking example (iOS and Android). [See docs](https://docs.needle.tools/image-tracking) |
| [![](https://cdn.needle.tools/static/images/changelog/scrollytelling-bike-thumbnail.jpg)](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/) | [Scrollytelling Bike Example](https://scrollytelling-bike-z23hmxb2gnu5a.needle.run/) | Timeline Animation using ScrollFollow, ViewBox and FocusRect | [Project on Github](https://github.com/needle-engine/needle-engine-bike-scrollytelling) |
| [![](https://cdn.needle.tools/static/images/changelog/see-through-walls-thumbnail.jpg)](https://engine.needle.tools/samples/see-through) | [See-Through Walls](https://engine.needle.tools/samples/see-through) | See-Through component sample |
| [![](https://cdn.needle.tools/static/images/changelog/follow-cursor-thumbnail.jpg)](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header) | [Cursor Follow](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header) | Cursor Follow sample |
| [![](https://cdn.needle.tools/static/images/changelog/khr_animation_pointer-thumbnail.jpg?1)](https://khr-animation-pointer-zubcksz2dgy3k.needle.run/) | [Animate Anything](https://khr-animation-pointer-zubcksz2dgy3k.needle.run/) | Interactive animation system | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-animate-anything?file=src%2Fmain.ts) • [three.js Example](https://threejs.org/examples/?q=gltf#webgl_loader_gltf_animation_pointer) |
| [![](https://cdn.needle.tools/static/images/changelog/magnifier-postprocessing-example-thumbnail.jpg)](https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/) | [Postprocessing Effects](https://antialiasing-and-postprocessing-zubcksz1o8daw.needle.run/) | Custom magnifier effect with post-processing | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-postprocessing) |
| [![](https://cloud.needle.tools/-/media/Xc99R6zbaD-kpoTw1cMRKA.gif)](https://engine.needle.tools/samples/material-x) | [Unity ShaderGraph to MaterialX & mtlx materials](https://engine.needle.tools/samples/material-x/) | Using [@needle-tools/materialx](https://www.npmjs.com/package/@needle-tools/materialx) |
| [![](https://cdn.needle.tools/static/images/changelog/4.8.8-focus-thumbnail.jpg)](https://responsive-layout-z23hmxb22no6t.needle.run/) | [Camera Focus DIV 1](https://responsive-layout-z23hmxb22no6t.needle.run/) | Responsive layout with camera focus | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-camera-focus-rect?file=src%2Fsidebar.ts,index.html,src%2Fmain.ts) |
| [![](https://cdn.needle.tools/static/images/changelog/4.8.8-focus-2-thumbnail.jpg)](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/) | [Camera Focus DIV 2](https://responsive-layout-click-example-z23hmxbzuyk6y.needle.run/) | Click-to-move camera focus example | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-camera-focus-rect-click-to-move?file=index.html,src%2Fmain.ts) |
| [![](https://cdn.needle.tools/static/images/changelog/fasthdr-thumbnail.jpg?1)](https://fasthdr-needle-engine-zubcks1li2iy.needle.run/) | [FastHDR Loading](https://fasthdr-needle-engine-zubcks1li2iy.needle.run/) | 10x faster than EXR, non-blocking, 95% less GPU memory | [Code on Stackblitz](https://stackblitz.com/edit/needle-fast-hdri-needle-engine) • [Learn more](https://cloud.needle.tools/hdris) |
| [![](https://cdn.needle.tools/static/images/changelog/scrollytelling-2-thumbnail.jpg)](https://scrollytelling-2-z23hmxby7c6x.needle.run/) | [Scrollytelling Example](https://scrollytelling-2-z23hmxby7c6x.needle.run/) | Scroll, physics and cursor interaction: a playful 3D interactive scrollytelling website | [Included in Samples Package](https://samples.needle.tools) |
| | [AR Restaurant](https://ar-restaurant-example-zubcks1t14le.needle.run/) | Interactive AR restaurant experience | [Code on Github](https://github.com/needle-engine/ar-restaurant-example) |
| | [Custom Loading Overlay](https://lods-loading-overlay-z23hmxbz29h8vr.needle.run/) | Wait for LODs with custom loading states | [Code on Stackblitz](https://stackblitz.com/edit/needle-engine-wait-for-lods) |
| | [React Shopping Cart](https://reactshoppingcart-z23hmxbzcfkmf.needle.run/) | E-commerce integration with React | [Code on Stackblitz](https://stackblitz.com/edit/needle-react-shopping-cart-2) |
<br/>

👋 More examples on [samples.needle.tools](https://samples.needle.tools/), [docs.needle.tools](https://docs.needle.tools) and in the [Needle Engine Stackblitz Collection](https://stackblitz.com/@marwie/collections/needle-engine)

<br />

# Contact ✒️
<b>[🌵 Needle](https://needle.tools)</b> • 
[Github](https://github.com/needle-tools) • 
[Twitter](https://twitter.com/NeedleTools) • 
[Discord](https://discord.needle.tools) • 
[Forum](https://forum.needle.tools) • 
[Youtube](https://www.youtube.com/@needle-tools)