Disclaimer
This is an English translation of my original Japanese post on Qiita (https://qiita.com/yanosen_jp/items/8362f1ca36f9012ac923).
Introduction
Needle Engine is a web-based 3D engine designed to run advanced 3D content in a browser environment. It easily integrates with existing 3D creation tools like Unity or Blender, allowing you to embed interactive 3D scenes into your projects without much friction. Because it's built on modern web standards, any browser supporting WebGL can run the engine on desktops, mobile devices, and VR/AR headsets.
Use cases include browser-based games, interactive promotional websites, 3D product viewers, educational and training VR content, AR demonstrations, and more. Since Needle Engine supports both multi-user functionality and WebXR, it’s also suitable for real-time collaboration and digital twins.
While you can upload and host your Needle Engine scenes on Needle Cloud, you can also host them yourself. In this post, we’ll cover the basics of Needle Engine and walk through preparing a scene in Unity and publishing it to Vercel.
Overview of Needle Engine
Needle Engine is a fully featured 3D engine that runs in the browser
(Feature Overview | Needle Engine Documentation)
offering rich 3D experiences on the web. You can integrate it into traditional web workflows (HTML/CSS/JavaScript) while leveraging interactive 3D capabilities. For example, you can embed a responsive 3D scene in a webpage and use React or plain HTML/CSS to control interface elements, enabling interactive web content such as 3D model manipulation or scroll-driven 3D animations.
From the start, Needle Engine is designed with XR (AR/VR) in mind, using the WebXR Device API to support VR headsets and AR-enabled browsers. With a single codebase, you can deliver AR experiences on mobile or immersive VR experiences on headsets.
Developing with Needle Engine and Unity
In Unity, developers build scenes by attaching scripts (components) to objects. With Needle Engine, these scripts are written in TypeScript/JavaScript. In the Unity Editor, each script appears as a placeholder C# component; at runtime on the web, the TypeScript components run natively within the Needle Engine’s component system. The workflow also supports hot reload and Editor Sync, meaning you can see your scene updates in the browser almost instantly (usually within a second) when editing in Unity.
Hosting the Sandbox Scene on Vercel
Next, let’s look at the process of publishing the default Sandbox scene from Needle Engine to a personal Vercel site. Needle Engine provides ready-made components for Glitch, itch.io, GitHub Pages, etc. Here, we’ll focus on a more high-performance deployment on Vercel.
Prerequisites
- You’ll need a (free) Vercel account.
- A supported Unity version: Unity 2021.3 LTS or 2022.3 LTS, Unity 6.
- A Node.js environment is required. Needle Engine recommends Node.js 20 LTS or 22 LTS. (For installation instructions, see, for example, this reference in Japanese.)
1. Setting Up Needle Engine
Let’s install Needle Engine in our Unity project and open the Sandbox scene.
Render Pipeline
Universal Render Pipeline (URP) and Built-In Render Pipeline (BiRP) are supported. If you’re creating a new project, choose either the “Universal 3D” or “3D (Built-In Render Pipeline)” template in Unity.
Installing the Needle Engine Package
Go to the Needle Engine official site and download the Unity .unitypackage. Then, import it into your existing Unity project by either double-clicking the file or dragging it into the Project window.
During import, necessary files will be added automatically. If you see a notification like "A new scoped registry...", you can safely click “Close”.
When it finishes importing, you’ll see a welcome message. Click Create New Scene With Template and save it.
This will open the Sandbox scene (you can also manually create it via File > New Scene, then pick a Needle template). Notice that Networking and XR are already in the Hierarchy, indicating that multiplayer and XR features are included by default.
Needle Engine Project Settings
Select Export in the Hierarchy, and then look at Needle Engine (Project & Export) in the Inspector.
Usually, the defaults are fine, but set the Project Folder if needed. Also, leaving Template as Vite is recommended until you’re comfortable with Needle.
Next, open the Project Validation window. You might see a warning like "Needle Engine EULA needs to be accepted before you can start using Needle Engine." Click "Open EULA Window", check all the boxes in the popup, then click I agree to EULA.
Now click Generate Project. Unity will install necessary Node modules and other components, generating the project. After that, it should automatically launch a local server on your machine and open the Sandbox scene in a browser.
If your browser doesn’t open automatically, check the Terminal window: you should see something like:
You’ll see Vite running on https://localhost:3000. If you navigate to https://localhost:3000 manually, your browser might warn you about an untrusted certificate (e.g., “Your connection is not private”). Select Advanced -> Proceed to localhost (the specific wording varies by browser) to proceed. You should see the Sandbox scene:
Back in Unity, you might see a note under Needle Editor Sync:
"@needle-tools/editor-sync package is not installed - click the button below to add it to your web project".
Click Install Editor Sync Package. Your Terminal will install it and restart the Vite server:
Editor Sync is experimental and only works in Chrome, but it’s handy since changes made in the Unity Scene window (even without saving the scene file) will quickly appear in the browser.
2. Deploying to Vercel
Now let’s deploy the project to Vercel. Typically, you’d push your code to a GitHub repository and configure Vercel to build and deploy, but in the default Needle Engine setup, certain local dependencies aren’t included in version control, causing potential deployment issues. Hence, we’ll do the following steps:
- Navigate to your project’s root directory in a terminal.
- Run these commands (adjusting as needed):
nvm use stable
npm install vite
npx vite --host
If nvm use stable doesn’t work, try:
nvm install 22
nvm use 22
Afterward, npx vite --host should serve the scene at https://localhost:3000.
Create a Vercel account if you haven’t already.
Install the Vercel CLI to deploy from your local environment:
npm install -g vercel
- Log in and set up your Vercel project:
vercel login
vercel
- Set up and deploy? -> yes
- Which scope should contain your project? -> press Enter
- Link to existing project? -> N (No) (we’ll create a new project)
-
Which directory is your code located in? -> default
./ -
Vercel will detect your Vite settings:
Auto-detected Project Settings (Vite): - Build Command: vite build - Development Command: vite --port $PORT - Install Command: (npm install, yarn install, etc.) - Output Directory: dist -
When asked "Want to modify these settings?", choose no. The deployment will start.
🔗 Linked to ***projects/*** (created .vercel and added it to .gitignore) 🔍 Inspect: https://vercel.com/***projects/***/*** [4s] ✅ Production: https://***-projects.vercel.app [4s] 📝 Deployed to production. Run `vercel --prod` to overwrite later.
That’s it! Open the Production URL shown in your terminal to see your deployed scene.
You’ll notice the URL has room=... in it. By sharing this URL with others, you can easily have multiple players sharing the same space. However, if your Vercel project defaults to private, viewers who are not logged into your Vercel account may not see the page. In that case, go to your Vercel Dashboard, open Settings -> Deployment Protection, and toggle off Vercel Authentication for that project.
“Open on Quest” indicates VR support.
Updating the Project
Whenever you make changes to your project, simply run:
vercel --prod
to create a new production deployment. Note that the production URL may change with each deploy. If you’d like a stable URL, run:
vercel inspect <your-production-url>
You’ll see something like:
General
id dpl_B+**************3
name u+*******3
target production
status ● Ready
url https://*****-projects.vercel.app
created Tue Feb 11 2025 23:29:24 GMT+0900 (Japan Standard Time) [7m ago]
Aliases
─ https://******3.vercel.app
─ https://*******3-*****projects.vercel.app
─ https://*****3-*****-projects.vercel.app
Among the Aliases, the top-level domain (without random strings) always points to the most recent deployment. You can share that link with others.
Conclusion
One major advantage of Needle Engine is the ability to build lightweight VR apps for the browser. While the workflow differs from traditional engines like Unity or Unreal, hopefully this guide helps you get started with multiplayer WebXR content. Happy creating!
Top comments (0)