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 ⚡
Make sure node.js and Unity are installed - see details
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.
Download our installer• Alternative
Our installer is a
.unitypackagethat will set everything up for you.
Install by dropping into Unity
Drop the downloaded
.unitypackagefile into a Unity project and confirm that you want to import it.
This will set up Needle Engine and Needle Exporter for Unity.
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.
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.
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
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!
Add our registry to Package Manager
Edit/Project Settingsand select
Add a new scoped registry:
Add the Exporter package
Open the Unity Package Manager via
In the dropdown in top left corner of the window select
Needle Engine Exporterand click install in the bottom right corner.
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.
- Click on
File > New Scene
- Select one of the templates with (needle) in their name and click
- 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.
Create a new empty scene
Set up your scene for exporting
Add an empty GameObject, name it "Exporter" and add an
ExportInfocomponent 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.
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.
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.
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.
Generate your web project
Wait a moment for the installation to finish — you can see a progress indicator in the bottom right corner of the editor.
View your project in a browser After a few seconds of installation, your project should automatically run and a new browser window opens.
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
Proceed to Site. Now you should see your scene in the browser!
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.
- Create a new empty GameObject
- Add a
GltfObjectcomponent to it. This component marks parts of your hierarchy to be exported as glTF file.
- Add an object (e.g.
Create/3D Object/Cube) as a child to the
GltfObjecthierarchy and save.
- Your browser should refresh and your object is visible.
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.
- Select your
- Add a new
OrbitControlscomponent to it
- Press play or save your scene
- Your browser should refresh and you can now move the camera around.
- Select your
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.
No cube on your website?
Make sure it's a child of your GltfObject root.
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
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.
👉 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!