@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
171 lines (127 loc) • 10.4 kB
Markdown
# 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://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://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://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://engine.needle.tools/samples/see-through) | [See-Through Walls](https://engine.needle.tools/samples/see-through) | See-Through component sample |
| [](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://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://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://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://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://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://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://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)