Getting started 🎈

These steps will get you started with Needle Engine for Unity.
After following them, you'll have a fully functional project.
From here, you can dive deeper into Scripting, VR and AR, Networking, or the various Samples and Modules.

You can either watch our Getting Started video or continue reading below 😊

Quick Start ⚡

1. Make sure node.js and Unity are installed - see details

2. Create a new Unity project
   Open Unity Hub and create a new project. 2021.3 recommended!
   Make sure to switch it to Linear color space in Project Settings > Player.

3. Download our installer

   • Alternative

   Our installer is a .unitypackage that will set everything up for you.

4. Install by dropping into Unity
   Drop the downloaded .unitypackage file into a Unity project and confirm that you want to import it.
   This will set up Needle Engine and Needle Exporter for Unity.

5. Wait for the installation to finish
   You may have to click Assets > Refresh once or focus another app and then focus Unity again.

   Note: A window may open stating that "A new scoped registry is now available in the Package Manager.". This is our Needle Package registry where packages are downloaded from. You can safely close that window.

6. Create a new scene from a template
   Select File > New Scene and choose from one of the Needle templates.
   We recommend the Collab Sandbox template which is a great way to get started with interactivity, multiplayer, and adding assets.

7. Continue here to make it your own.
   Learn how to iterate, test, build and publish your projects.

Option 2: Start from Scratch 🐢 — Manual Setup

Create a new project

1. Set up a new project
   Create a new Unity project via the Hub.
   We recommend 2021.3 LTS. Make sure to switch to Linear color space!

2. Add our registry to Package Manager
   Open Edit/Project Settings and select Package Manager.
   Add a new scoped registry:

   • Name: needle
   • URL: https://packages.needle.tools
   • Scope(s):
     com.needle
org.khronos
     

3. Add the Exporter package
   Open the Unity Package Manager via Window/Package Manager.
   In the dropdown in top left corner of the window select My Registries.
   Select Needle Engine Exporter and click install in the bottom right corner.

Note

You only need to install Needle Engine Exporter – other packages will automatically be installed as dependencies.

Create a new scene from a Scene Template

We provide a number of Scene Templates for quickly starting new projects.
These allow you to go from idea to prototype in a few clicks.

1. Click on File > New Scene
2. Select one of the templates with (needle) in their name and click Create.
3. Continue here.

Create a new scene from scratch

If you don't want to start from a scene template, you can follow these steps.
Effectively, we're going to recreate the "Minimal (Needle)" template that's shipping with the package.

1. Create a new empty scene

2. Set up your scene for exporting
   Add an empty GameObject, name it "Exporter" and add an ExportInfo component to it.
   In this component you create and quickly access your exported runtime project.
   It also warns you if any of our packages and modules are outdated or not locally installed in your web project.

Note

By default, the project name matches the name of your scene. If you want to change that, you can enter a Directory Name where you want to create your new runtime project. The path is relative to your Unity project.

3. Choose a web project template
   Now, select a web project template for your project. The default template is based on Vite, a fast web app bundler.

4. Continue here.

Generate a web project and add content

Needle Engine is a web-based runtime, and so there's always two projects: your Unity project and a web project that contains regular HTML and CSS. Needle Exporter brings these together into a fast, iterative workflow.
Usually, one Unity Scene with ExportInfo has one web project, so we're going to generate one now.

1. Generate your web project
   On the ExportInfo component, click Generate Project.
   Wait a moment for the installation to finish — you can see a progress indicator in the bottom right corner of the editor.

2. View your project in a browser After a few seconds of installation, your project should automatically run and a new browser window opens.

Note

You might see a warning in your browser about SSL Security depending on your local configuration.
This is because while the connection is encrypted, by default there's no SSL certificate that the browser can validate.
If that happens: click Advanced and Proceed to Site. Now you should see your scene in the browser!

Note

Keep an eye for console warnings! We log useful details about recommended project settings and so on. For example, your project should be set to Linear color space (not Gamma), and we'll log an error if that's not the case.

⭐ Congratulations! You just started your first project using Needle Engine! We're excited what you'll build.

---

3. Add content

   1. Create a new empty GameObject
   2. Add a GltfObject component to it. This component marks parts of your hierarchy to be exported as glTF file.
   3. Add an object (e.g. Create/3D Object/Cube) as a child to the GltfObject hierarchy and save.
   4. Your browser should refresh and your object is visible.

4. Make it interactive
   Needle Engine comes with a set of prebuilt components that you can use to easily make your scene interactive. One of those components is OrbitControls, which we're going to use to make the camera interactive.

   1. Select your Main Camera GameObject
   2. Add a new OrbitControls component to it
   3. Press play or save your scene
   4. Your browser should refresh and you can now move the camera around.

Note

The local server does not start / no website in your browser?
Make sure you read and followed the Prerequisites.
Also check the console and ExportInfo component for warnings or errors.
And last but not least, press Play to start the local server.

Note

No cube on your website?
Make sure it's a child of your GltfObject root.

---

Prerequisites 💿

Below each tool, you find quick links to download the latest version at the time of writing.

Install these tools for development

Node.js (16.x or 18.x) – for running a local development server (required)
Windows 16.7 • MacOS Universal

VS Code – for code editing (recommended)
Windows • MacOS Universal

Unity 2020.3.16+, 2021.3+ or 2022.2+ – for setting up your scene and components (required)
Universal Render Pipeline or Built-In Render Pipeline
Linear Colorspace

Install these tools for production builds

toktx 4.1 – for texture compression (recommended)
Windows x64 • MacOS x64 • Mac OS with Apple Silicon • Other

After installing the tools above, you might have to restart your machine so that all environment variables are properly updated.

What's next?

👉 Continue reading about exporting 3D objects and content, scripting or learn about how to deploy your website to the web!

In case you need more troubleshooting help, please see the Questions and Answers section.
You can also join our Discord Community!