Needle Engine for Unity
+ 
Needle Engine for Unity
Needle Engine for Unity allows you to create highly interactive, flexible and lightweight web applications right inside Unity. Use the powerful tools of the Unity editor to visually setup your 3D scenes, animate and design. Needle Engine for Unity takes care of exporting your scene to glTF and integrates easily with any web frontend framework.
Install the Unity Package
Download Needle Engine for Unity
Drop the downloaded .unitypackage file into a Unity project and confirm that you want to import it.
Wait a moment for the installation and import to finish. A window may open stating that "A new scoped registry is now available in the Package Manager.". This is our Needle Package registry. You can safely close that window.
Explore Samples. Select the menu option
Needle Engine > Explore Samplesto view, open and modify all available sample scenes.
Quickstart Video Tutorial
Start from a Sample
There are 100+ samples that cover a wide range of topics, use cases, and industries. For a quick overview, take a look at our Samples page.
All of these samples are available directly in Unity:
Go to
Needle Engine > Explore Samplesto browse for samplesClick "Install Samples" to install the samples package right inside your editor (or download the samples unitypackage to manually install the package)
Choose any sample and click on
Open Scene.
:::tip The Samples are read-only – that makes them easy to update. Our samples scenes are part of a UPM package in Unity. This means that you can't edit the assets and scripts in them directly – they are read-only. To edit an asset from the samples package, copy it into your project's Assets folder. To edit a script from the samples package, copy it into your web project's src folder. :::
Start 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 SceneSelect one of the templates with (needle) in their name and click
Create. We recommend the Collaborative Sandbox template which is a great way to get started with interactivity, multiplayer, and adding assets.Click Play to install and startup your new web project.
Start 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 the
Needle Enginecomponent to it (formerly namedExport Info). 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.::: tip Project Name and Scene Name By default, the project name matches the name of your scene. If you want to change that, you can pick or enter a
Directory Namewhere you want to create your new web 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.
Click Play to install and start your new web project
:::tip Define your own templates If you find yourself creating many similar projects, you can create your own local or remote templates using the Project View context menu under Create/Needle Engine/Project Template. Templates can either be local on disk (a folder being copied) or github repositories (a git repository being cloned). :::
Project Folders and Files
:::: file-tree name="Unity Project" showall="true" ::: file Assets/ This is where project specific/exclusive assets live. ::: ::: file Packages/ This is where packages installed for this project live. A package can contain any asset type, and can be added to multiple Unity projects. It therefore is a great method to share code or assets. To learn more about packages, see the Unity documentation about packages. ::: ::: file Packages/Needle Engine/ Needle Engine for Unity is a package that contains all the necessary files to export your Unity scene to a web project. It also contains the built-in components and tools for creating interactive web projects. You can update the package via the Unity Package Manager. ::: ::: file Packages/Needle Engine/Core/ ::: ::: file Packages/Needle Engine/Core/Runtime/ ::: ::: file Packages/Needle Engine/Core/Runtime/Components/ Contains all built-in components for Needle Engine. You can learn more about them in the Components Reference. Looking at samples and going through this folder are great ways to see what components are available and how they can be used in your projects. ::: ::::
When creating a new web project in Unity, you can choose to create it from a local template (by default we ship a Vite based web template).
Use web projects directly from Github
Besides the web project templates that already ship with the Unity integration you can setup your web project directly from github by entering the Github repository URL in the Project Folder field.
When creating a new web project the repository will be cloned (or downloaded if you don't have git installed). The repository is then searched for a needle.config.json file. If none can be found in the cloned repository the root directory will be used.
Examples of remote template projects can be found on github.com/needle-engine
Temporary Projects
If you're planning to only add custom files via NpmDefs and not change the project config (e.g. for a quick fullscreen test), you can prefix the project path with Library. The project will be generated in the Unity Project Library and does not need to be added to source control (the Library folder should be excluded from source control). We call these projects temporary projects. They're great for quickly testing out ideas!
Typescript in Unity
With Needle Engine for Unity your typescript code get's converted into C# stub component that can be attached to components. You can write your typescript classes like you would in any other web project. If a property is public and marked with @serializable it will be exposed to the Unity editor and you can attach it to objects in the scene, modify it's properties and setup object references.
:::tip Needle Engine makes it easy splitting work between development and design where a web developer can write components and manage the web project while the 3D scene, content and settings are managed and can be visually edited by designers in a familiar and powerful environment. Both can see the results of their work in seconds. :::
Option 1: Scripts directory
Once you have your web project setup (see steps above) you can add your Needle Engine components in the scripts folder (this is usually at src/scripts inside your web project). This is usually sufficient for most projects.
Simply create a .ts file and add a Needle Engine component. The coresponding C# component will be generated automatically to be used in Unity.
import { Behaviour, serializable } from "@needle-tools/engine";
import { Object3D } from "three";
export class MyComponent extends Behaviour {
@serializable(Object3D)
otherObject: Object3D;
start() {
console.log("Hello World", this.otherObject);
}
}
Option 2: Npmdef — NPM packages in Unity
NPM Definitions are NPM packages tightly integrated into the Unity Editor, which makes it easily easy to share scripts between multiple web- or Unity projects.
C# component stubs for TypeScript files will also be automatically generated for scripts inside NpmDef packages.
Creating and installing an NpmDef
To create a NPM Definition (Npmdef), right click in the Unity Project browser and select Create/NPM Definition.
Next install the Npmdef package to your web project by selecting your Needle Engine component (formerly Export Info) and adding it to the dependencies list
:::tip Adding or installing a Npmdef package to your web project dependencies in Unity effectively just adds the local NPM package to your package.json in the dependencies array. This is the same as you would do it manually or by running npm i <path/to/package> :::
Don't forget to install the newly added package by e.g. clicking Install on the ExportInfo component and also restart the server if it is already running
To edit the code inside a Npmdef package just double click the asset Npmdef asset in your project browser and it will open the vscode workspace that comes with each npmdef.
Unity C# components for Needle Engine components inside the Npmdef package will be generated automatically.
Next Steps
Last updated