+

Needle Engine is three.js

Needle Engine is built on top of three.js and provides a component-based architecture for creating interactive 3D web experiences. 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.

The key benefits of using Needle Engine over vanilla three.js include:

• Component system for organizing and reusing 3D logic
• Built-in features like physics, XR, networking, and particles
• Editor integrations with Unity and Blender for visual scene creation
• Optimized build pipeline with automatic 3D asset optimization
• Faster development with less boilerplate

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

On this page, you'll learn how to use Needle Engine with vanilla JavaScript and HTML – perfect for integrating 3D into existing web projects or building from scratch without a 3D editor.

Want visual editing? Check out our editor integrations:

• Unity Integration – Full-featured 3D editor with C# scripting support
• Blender Integration – Open-source 3D creation suite with Python scripting

<needle-engine> web component

Needle Engine provides an easy-to-use web component that can be used to display rich, interactive 3D scenes directly in HTML with just a few lines of code.

Quick Start

<!-- 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 needle-engine 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:

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

Install from CDN

While our default template uses vite, Needle Engine can also be used directly with vanilla Javascript – without using any bundler.

You can add a complete, prebundled version of Needle Engine to your website with just a line of code. This includes our core components, physics, particles, networking, XR, and more. Use this if you're not sure!

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

Install from NPM

You can work directly with Needle Engine without using any Integration. Needle Engine uses three.js as scene graph and rendering library, so all functionality from three.js is available in Needle as well.

You can install Needle Engine from NPM by running:

npm i @needle-tools/engine

Many examples can be found on StackBlitz.

Local Development with VS Code

If you want to work with Needle Engine without any integration, then you'll likely want to run a local server for your website. Here's how you can do that with Visual Studio Code:

1. Open the folder with your HTML file in Visual Studio Code.
2. Install the LiveServer extension.
3. Start live-server (there's a button "Go Live" in the footer of VSCode)
4. Open http://localhost:5500 in your web browser, if it doesn't open automatically.

three.js and Needle Engine

Since Needle Engine uses three.js as scene graph and rendering library, all functionality from three.js is available in Needle as well and can be used from component scripts. We're using a fork of three.js that includes additional features and improvements, especially in relation to WebXR, Animation, and USDZ export.

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <link rel="icon" href="favicon.ico">
    <meta name="viewport" content="width=device-width, user-scalable=no">
    <title>Made with Needle</title>

    <!-- importmap -->
    <script type="importmap">
        {
          "imports": {
            "three": "https://cdn.jsdelivr.net/npm/three/build/three.module.js",
            "three/": "https://cdn.jsdelivr.net/npm/three",
          }
        }
    </script>
    <!-- the .light version does not include dependencies like Rapier.js (so no physics) to reduce the bundle size, if your project needs physics then just change it to needle-engine.min.js -->
    <script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js"></script>

    <style>
        body {
            margin: 0;
            background-color: rgba(200, 250, 200);
        }

        needle-engine {
            position: absolute;
            width: 100%;
            height: 100%;
        }
    </style>

</head>

<body>

    <!-- load a gltf or glb here as your scene -->
    <needle-engine src="https://cloud.needle.tools/-/assets/Z23hmXB27L6Db-world/file" camera-controls
        background-color="transparent" environment-image="studio"></needle-engine>

</body>

<script type="module">
    import { onStart } from 'https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js';
    onStart((context) => {
        console.log('Hello Needle');
    });
</script>

</html>

View on github - View on Stackblitz

Rapid Prototyping on StackBlitz

For quick experiments, we provide a convenient link to create a new project ready to start: engine.needle.tools/new
A large collection of examples are also available in our Needle Engine Stackblitz Collection

Next Steps

• Learn more about the web component attributes
• Learn how to extend Needle Engine with custom scripts and components
• Use Needle DevTools for three.js to inspect and debug your scenes