Needle Engine + three.js

Welcome! If you're here because you know three.js, you're in the right place. Needle Engine is a web-based 3D engine built on top of three.js that makes it easier and faster to create interactive 3D experiences for the web.

What is Needle Engine?

Think of Needle Engine as three.js with superpowers:

• All the power of three.js (since it's built on it)

• Plus a component system for better code organization

• Plus built-in features like physics, XR, networking, and particles

• Plus visual editing tools (Unity and Blender integrations)

• Plus automatic optimization and compression

All three.js APIs remain fully accessible – you can write vanilla three.js code, use any three.js-compatible library, or mix and match as needed.

:::tip Try It in 30 Seconds Want to see what Needle Engine can do? Create a new project instantly:

🚀 engine.needle.tools/new - Opens a ready-to-go project in StackBlitz

No installation, no setup. Just click and start experimenting with three.js + Needle Engine in your browser! :::

Why Choose Needle Engine Over Vanilla three.js?

Enhanced Developer Experience:

• 🧩 Component system for organizing and reusing 3D logic

• ⚡ Built-in features like physics, XR, networking, particles, and UI

• 🎨 Editor integrations with Unity and Blender for visual scene creation

• 🚀 Optimized build pipeline with automatic 3D asset compression and optimization

• 💨 Faster development with less boilerplate and better tooling

Full Flexibility: Whether you're building a simple scene with pure three.js or a complex application with Needle's components, you have complete freedom. The component system is an enhancement, not a replacement – use what makes sense for your project.

:::tip Want Visual Editing? Check out our editor integrations for powerful visual creation workflows:

• Unity Integration – Full-featured 3D editor with C# scripting support

• Blender Integration – Open-source 3D creation suite with Python scripting :::

:::tip Inspect and Debug Use the Needle Inspector Chrome extension to inspect, debug, and edit any three.js scene directly in your browser – perfect for development and learning. :::

[[toc]]

---

Quick Start: Web Component

The easiest way to get started is using the <needle-engine> web component. Display rich, interactive 3D scenes directly in HTML with just a few lines of code.

Basic Example

<!-- Import the component -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js"></script>

<!-- Use it like any other HTML element -->
<needle-engine
    src="https://cloud.needle.tools/-/assets/Z23hmXBZ21QnG-Z21QnG-world/file"
    background-color="transparent">
</needle-engine>

Open this example on StackBlitz • View all web component attributes

---

Extending with Vanilla three.js

The web component works seamlessly with vanilla three.js code. Use Needle Engine's lifecycle hooks to access the scene and add your own three.js objects, modify materials, or write custom logic.

Adding Objects with onStart

<!-- Import Needle Engine -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js"></script>

<!-- Add the web component -->
<needle-engine src="your-scene.glb"></needle-engine>

<!-- Extend with vanilla three.js -->
<script type="module">
  import { onStart } from 'https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js';
  import * as THREE from 'three';

  onStart(context => {
    // Access the three.js scene
    console.log("Scene loaded:", context.scene);

    // Add objects using vanilla three.js
    const geometry = new THREE.BoxGeometry(1, 1, 1);
    const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    cube.position.set(0, 0.5, 0);

    context.scene.add(cube);
  });
</script>

Animating Objects with onUpdate

import { onStart, onUpdate } from '@needle-tools/engine';
import * as THREE from 'three';

let rotatingCube;

onStart(context => {
  // Create a rotating cube
  const geometry = new THREE.BoxGeometry(1, 1, 1);
  const material = new THREE.MeshStandardMaterial({ color: 0xff0000 });
  rotatingCube = new THREE.Mesh(geometry, material);
  context.scene.add(rotatingCube);
});

onUpdate(context => {
  // Rotate every frame using deltaTime
  if (rotatingCube) {
    rotatingCube.rotation.y += context.time.deltaTime;
  }
});

Modifying Loaded Scene Objects

import { onStart } from '@needle-tools/engine';

onStart(context => {
  // Find and modify objects from your loaded glb
  const myObject = context.scene.getObjectByName("MyObjectName");
  if (myObject) {
    myObject.position.y = 2;
    myObject.scale.setScalar(1.5);
  }

  // Or traverse the entire scene
  context.scene.traverse(obj => {
    if (obj.isMesh && obj.material) {
      // Modify all materials in the scene
      obj.material.metalness = 0.5;
      obj.material.roughness = 0.3;
    }
  });
});

Available Lifecycle Hooks

Hook	When it's called
onInitialized(callback)	When the context is initialized (before first frame)
onStart(callback)	At the beginning of the first frame after scene loads
onUpdate(callback)	Every frame (perfect for animations)
onBeforeRender(callback)	Before the scene renders
onAfterRender(callback)	After the scene renders

Context Object Properties:

All hooks provide the context object with access to:

• context.scene - The three.js Scene

• context.camera - The active Camera

• context.renderer - The WebGLRenderer

• context.time - Time data (deltaTime, frame count, etc.)

• And much more...

:::tip Learn More About Scripting

• Scripting Documentation - Detailed information about lifecycle hooks

• Scripting Examples - More code samples and patterns

• Custom Components - Build reusable components :::

---

Installation Options

Install from CDN

Use Needle Engine directly with vanilla JavaScript – no bundler required. The prebundled version includes core components, physics, particles, networking, XR, and more.

<script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js">
</script>

When to use:

• Quick prototypes and experiments

• Simple integrations into existing websites

• Learning and exploring Needle Engine

• Projects without a build pipeline

Install from NPM

For projects using modern JavaScript tooling and bundlers:

npm install @needle-tools/engine

When to use:

• Production applications

• Projects using bundlers (Vite, Webpack, etc.)

• TypeScript projects

• When you need tree-shaking and optimal bundle size

Example usage:

import { NeedleEngine } from '@needle-tools/engine';
import * as THREE from 'three';

// Your code here

---

Development Setup

Rapid Prototyping on StackBlitz

For quick experiments, create a new project instantly:

🚀 engine.needle.tools/new - Start a new project in seconds

📚 StackBlitz Collection - Browse example projects

Perfect for:

• Learning and experimentation

• Sharing code snippets

• Quick proof-of-concepts

• Testing ideas without local setup

Local Development with VS Code

For more control and offline development:

Setup:

1. Open your project folder in Visual Studio Code

2. Install the Live Server extension

3. Click Go Live in the VSCode footer

4. Open http://localhost:5500 in your browser (usually opens automatically)

Benefits:

• Full control over your development environment

• Works offline

• Better performance for large projects

• Easier integration with version control

:::tip Sample glTF Files Need a test scene? Download this sample glb to get started quickly. :::

---

Complete HTML Example

Here's a minimal but complete example showing how to use Needle Engine with vanilla HTML:

@code

View on GitHub • View on StackBlitz

---

three.js Compatibility

Needle Engine uses a fork of three.js that includes additional features and improvements, especially for:

• WebXR - Enhanced XR session management and features

• Animation - Improved animation playback and blending

• USDZ Export - Better support for iOS AR

Full Compatibility: All standard three.js functionality is available in Needle Engine. You can:

• Use any three.js-compatible library

• Follow three.js tutorials and examples

• Import existing three.js code

• Mix vanilla three.js with Needle components

---

Next Steps

Learn More:

• Web Component Attributes - Configure the <needle-engine> component

• Scripting Guide - Create custom scripts and components

• Scripting Examples - Code samples and patterns

• Needle DevTools - Debug and inspect scenes

Build Bigger:

• Unity Integration - Visual editing with full-featured 3D editor

• Blender Integration - Open-source 3D creation workflow

• Features Overview - See what's possible with Needle Engine

Get Help:

• Forum - Ask questions and share projects

• Discord - Join the community

• Examples - Browse sample projects

---

:::tip Using Editor Integrations Did you know that Needle Engine seamlessly integrates with Blender and Unity? Create complex 3D scenes visually and export them directly to the web. Perfect for large projects and team collaboration.

Learn about Unity Integration • Learn about Blender Integration :::