Deployment and Optimization
Last updated
Last updated
Deployment is the process of making your application available to the public on a website. Needle Engine ensures that your project is as small and fast as possible by using the latest compression techniques such as KTX2, Draco, and Meshopt.
Great for spatial web apps and sharing assets.
Great for experimentation and hacking on server-side code.
Great for hosting your own website and custom domain names.
Often used for games.
Free static page hosting.
Platform for frontend developers
Deploy directly to any server with FTP support. Both FTP and SFTP are supported.
When building to a folder, you can upload the files to any web server or other hosting service.
Games platform on Facebook and Facebook Messenger.
::: tip Feel something is missing? Please let us know in our ! :::
See guides above on how to access the options from within your Editor (e.g. Unity or Blender).
We generally recommend making production builds for optimized file size and loading speed (see more information below).
Production builds will by default compress textures using KTX2 (either ETC1S or UASTC depending on their usage in the project) but you can also select WebP compression and select a quality level.
How do I choose between ETC1S, UASTC and WebP compression?
GPU Memory Usage
Low
Low
High (uncompressed)
File Size
Low
High
Very low
Quality
Medium
Very high
Depends on quality setting
Typical usage
Works for everything, but best for color textures
High-detail data textures: normal maps, roughness, metallic, etc.
Files where ETC1S quality is not sufficient but UASTC is too large
You have the option to select texture compression and progressive loading options per Texture by using the Needle Texture Importer in Unity or in the Material tab in Blender.
By default, a production build will compress meshes using Draco compression. Use the MeshCompression component to select between draco and mesh-opt per exported glTF.
Additionally you can setup mesh simplification to reduce the polycount for production builds in the mesh import settings (Unity). When viewing your application in the browser, you can append ?wireframe to your URL to preview the meshes.
How do I choose between Draco and Meshopt?
GPU Memory Usage
Medium
Low
File Size
Lowest
Low
Animation compression
No
Yes
:::details How can I set draco and meshopt compression settings? Add the MeshCompression component to select which compression should be applied per exported glTF.
To change compression for the current scene just add it anywhere in your root scene.
To change compression for a prefab or NestedGltf add it to a GltfObject or the prefab that is referenced / exported by any of your components.
To change compression for a referenced scene just add it to the referenced scene that is exported :::
You can also add the Progressive Texture Settings component anywhere in your scene, to make all textures in your project be progressively loaded. Progressive loading is not applied to lightmaps or skybox textures at this point.
With progressive loading textures will first be loaded using a lower resolution version. A full quality version will be loaded dynamically when the texture becomes visible. This usually reduces initial loading of your scene significantly.
:::details How can I enable progressive texture loading?
Since Needle Engine 3.36 we automatically generate LOD meshes and switch between them at runtime. LODs are loaded on demand and only when needed so so this feature both reduces your loading time as well as performance.
Key Beneftis
Faster initial loading time
Faster rendering time due to less vertices on screen on average
Faster raycasting due to the use of LOD meshes
You can either disable LOD generation for your whole project in the Progressive Loading Settings component or in the Mesh Importer settings.
You can deploy to glitch by adding the DeployToGlitch component to your scene and following the instructions.
Note that free projects hosted on glitch may not exceed ~100 MB. If you need to upload a larger project consider using a different deployment target.
:::details How do I deploy to Glitch from Unity?
Add the DeployToGlitch component to the GameObject that also has the ExportInfo component.
Once the Deploy Key has been received you can click the Build & Deploy button to upload to glitch.
:::
:::details How do I deploy to Glitch from Blender?
Find the Deploy To Glitch panel in the Scene tab
Click the Remix on glitch button on the component
Your browser will open the glitch project template
Wait for Glitch to generate a new project
Copy paste the project URL in the Blender DeployToGlitch panel as the project name (you can paste the full URL, the panel will extract the necessary information)
On Glitch open the .env file and enter a password in the field Variable Value next to the DEPLOY_KEY
Enter the same password in Blender in the Key field
Click the DeployToGlitch button to build and upload your project to glitch. A browser will open when the upload has finished. Try to refresh the page if it shows black after having opened it.
:::
Troubleshooting Glitch
:::details How do I deploy to Netlify from Unity?
Just add the DeployToNetlify component to your scene and follow the instructions. You can create new projects with the click of a button or by deploying to existing projects.
Create a new project on vercel
Add your web project to a github repository
Add the repository to your project on vercel
:::details How do I deploy to itch.io from Unity?
Wait for the build to finish, it will open a folder with the final zip when it has finished
Save your itch page and view the itch project page. It should now load your Needle Engine project 😊
Optional settings
:::details Itch.io: failed to find index.html
Failed to find index.html
:::
:::details How do I deploy to my FTP server from Unity?
Add the DeployToFTP 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)
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
Click the Build & Deploy button on the DeployToFTP component to build your project and uploading it to your FTP account
:::details How do I deploy to my FTP server manually?
Open File > Build Settings, select Needle Engine, and click on Build
Wait for the build to complete - the resulting dist folder will open automatically after all build and compression steps have run.
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 Buildon in the Build Settings.
:::
Enabling gzip using a .htaccess file
To enable gzip compression on your FTP server you can create a file named .htaccess in the directory you want to upload to (or a parent directory).
Insert the following code into your .htaccess file and save/upload it to your server:
:::details How do I deploy to Github Pages from Unity?
:::
Troubleshooting github pages
I deployed to github pages but no action is running / the website is not live
If you deployed for the first time it can take a few minutes until your website becomes available. You can check the Actions tab on github (/actions) to see the deployment process.
If your website is not live after a few minutes or you don't see any workflow run in the Actions tab on github then go to the Github Pages settings page (/settings/pages) and make sure the Branch is set to gh-pages
With Needle Engine you can build to Facebook Instant Games automatically No manual adjustments to your web app or game are required.
:::details How do I deploy to Facebook Instant Games from Unity?
Click the Build For Instant Games button
After the build has finished you will get a ZIP file that you can upload to your facebook app.
That's it - you can then click the Play button next to each version to test your game on facebook.
:::
:::details How do I create a app on Facebook (with Instant Games capabilities)
In Unity open File/Build Settings and select Needle Engine for options:
To build your web project for uploading to any web server 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.
To locally preview your final build you can use the Preview Build button at the bottom of the window. This button will first perform a regular build and then start a local server in the directory with the final files so you can see what you get once you upload these files to your webserver.
Nodejs is only required during development. The distributed website (using our default vite template) is a static page that 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).
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.
Needle Engine for Unity supports various commandline arguments to export single assets (Prefabs or Scenes) or to build a whole web project in batch mode (windowsless).
The following list gives a table over the available options:
-scene
path to a scene or a asset to be exported e.g. Assets/path/to/myObject.prefab or Assets/path/to/myScene.unity
-outputPath <path/to/output.glb>
set the output path for the build (only valid when building a scene)
-buildProduction
run a production build
-buildDevelopment
run a development build
-debug
open a console window for debugging
The main difference to a production build is that it does not perform and compression (for reduction of file size and loading speed) as well as the option to progressively load high-quality textures.
To make a production build, you need to have installed, which provides texture compression using the KTX2 supercompression format. Please go to the and download and install the latest version (v4.1.0 at the time of writing). 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 still can't be found, please restart your machine and try build again.
:::details Advanced: Custom glTF extensions
If you plan on adding your own custom glTF extensions, building for production requires handling those in gltf-transform. See for reference.
:::
:::details Unity: How can I set per-texture compression settings? :::
:::details Blender: How can I set per-texture compression settings? Select the material tab. You will see compression options for all textures that are being used by that material. :::
:::details Toktx can not be found
Windows: Make sure you have added toktx to your system environment variables. You may need to restart your computer after adding it to refresh the environment variables. The default install location is C:\Program Files\KTX-Software\bin
:::
:::details Where to find mesh simplification options to reduce the vertex count when building for production? Select a Mesh and open the Needle importer options to see available options for the selected mesh: :::
:::
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.
Click the Create new Glitch Remix button on the component
Glitch will now create a remix of the template. Copy the URL from your browser
Open Unity again and paste the URL in the Project Name field of your Deploy To Glitch component
Wait a few seconds until Unity has received your deployment key from glitch (this key is safely stored in the .env file on glitch. Do not share it with others, everyone with this key will be able to upload to your glitch website)
If you click Create new Glitch Remix and the browser shows an error like there was an error starting the editor you can click OK. Then go to and make sure you are signed in. After that you then try clicking the button again in Unity or Blender.
:::
See our for the project configuration
Create a new project on
Set Kind of project to HTML
Add the DeployToItch component to your scene and click the Build button
Upload to final zip to itch.io
Select This file will be played in the browser
:::
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 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 :::
Add the DeployToGithubPages component to your scene and copy-paste the github repository (or github pages url) that you want to deploy to.
Add the Deploy To Facebook Instant Games component to your scene:
On Facebook add the Instant Games module and go to Instant Games/Web hosting
You can upload your zip using the Upload version button (1). After the upload has finished and the zip has been processed click the Stage for testing button to test your app (2, here the blue button) or Push to production (the button with the star icon)
and select Other. Then click Next
Select type Instant Games
After creating the app add the Instant Games product
Here you can find on facebook. Note that all you have to do is to create an app with instant games capabilities. We will take care of everything else and no manual adjustments to your Needle Engine website are required. :::
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:
