How to build for uploading to the web

Needle Engine is tightly integrated into the Unity Editor:
Open File/Build Settings and select Needle Engine for options!

To build your web project for deployment you can click Build in the Unity Editor Build Settings Window. You can enable the Development Build checkbox to omit compression (see below) which requires toktx to be installed on your machine.

Note: Nodejs is only required during development. The distributed website (using the vite template) is a static page, doesn't rely on Nodejs and can be put on any regular web server. Nodejs is required if you want to run our minimalistic networking server on the same web server (automatically contained in the Glitch deployment process).

Building a development distribution

See notes above on how to access. The main difference to a production build is that it does not perform ktx2 and draco compression. Both can reduce file-size drastically. We generally recommend making builds using the production option.

Building a production distribution (optimized and compressed)

To make a production build you need to have toktx to be installed, which provides texture compression using the KTX2 supercompression format. Please go to the toktx Releases Page and download and install the latest version (v4.1.0-rc3 at the time of writing, there might be a newer one). You may need to restart Unity after installing it.
If you're sure that you have installed toktx and it's part of your path but it still can't be found, please restart your machine and try again.

If you plan on adding your own custom glTF extensions, building for production requires handling those in gltf-transform. See @needle-tools/gltf-transform-extensionsw for reference.

Deploy to Glitch 🎏

Glitch provides a fast and free way for everyone to host small and large websites. We're providing an easy way to remix and deploy to a new Glitch page (based on our starter), and also to run a minimalistic networking server on the same Glitch page if needed.

1. Add the Deployment component to the GameObject that also has the ExportInfo component.

2. Click the Remix on glitch button on the component

3. Your browser will open the glitch project template

4. Find and click the Remix another button on the glitch website
   

5. Glitch will now create a remix of the template. Copy the URL from your browser
   

6. Open Unity again and paste the URL in the Project Name field of your Deployment component
   

7. On Glitch open the .env file and enter a password in the field Variable Value next to the DEPLOY_KEY
   

8. Add the same password in Unity
   

Deploy to itch.io

1. Create a new project on itch.io

2. Set Kind of project to HTML
   

3. Add the DeployToItch component to your scene and click the Build button
   

4. Wait for the build to finish, it will open a folder with the final zip when it has finished

5. Upload to final zip to itch.io
   

6. Select This file will be played in the browser
   

7. Save your itch page and view the itch project page.
   It should now load your Needle Engine project 😊

Optional settings

Troubleshooting itch.io

Failed to find index.html

If you see this error after uploading your project make sure you do not upload a gzipped index.html. You can disable gzip compression in vite.config.js in your Needle web project folder. Just remove the line with viteCompression({ deleteOriginFile: true }). The build your project again and upload to itch.

Deploy to FTP

1. Add the DeloyToFTP component¹ on a GameObject in your scene (it is good practice to add it to the same GameObject as ExportInfo - but it is not mandatory)
2. Assign an FTP server asset and fill out server, username, and password if you have not already ²
   This asset contains the access information to your FTP server - you get them when you create a new FTP account at your hosting provider
3. Click the Build & Deploy button on the DeployToFTP component to build your project and uploading it to your FTP account

¹ Deploy to FTP component

² FTP Server asset containing the access information of your FTP user account

Deploy To FTP component after server asset is assigned. You can directly deploy to a subfolder on your server using the path field

Deploy to FTP (manual upload)

1. Open File > Build Settings, select Needle Engine, and click on Build
2. Wait for the build to complete - the resulting dist folder will open automatically after all build and compression steps have run.
3. Copy the files from the dist folder to your FTP storage.

That's it! 😉

Note: If the result doesn't work when uploaded it might be that your web server does not support serving gzipped files. You have two options to fix the problem:
Option 1: You can try enabling gzip compression on your server using a htaccess file!
Option 2: You can turn gzip compression off in the build settings at File/Build Window and selecting the Needle Engine platform.

Note: If you're getting errors during compression, please let us know and report a bug! If your project works locally and only fails when doing production builds, you can get unstuck right away by doing a Development Build. For that, simply toggle Development Build on in the Build Settings.

---

Cross-Platform Deployment Workflows

It's possible to create regular Unity projects where you can build both to Needle Engine and to regular Unity platforms such as Desktop or even WebGL. Our "component mapping" approach means that no runtime logic is modified inside Unity - if you want you can regularily use Play Mode and build to other target platforms. In some cases this will mean that you have duplicate code (C# code and matching TypeScript logic). The amount of extra work through this depends on your project.

Enter Play Mode in Unity
In Project Settings > Needle Engine, you can turn off Override Play Mode and Override Build settings to switch between Needle's build process and Unity's build process: