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.
Add the
Deployment
component to the GameObject that also has theExportInfo
component.Click the
Remix on glitch
button on the componentYour browser will open the glitch project template
Find and click the
Remix another
button on the glitch websiteGlitch 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 yourDeployment
componentOn Glitch open the
.env
file and enter a password in the fieldVariable Value
next to the DEPLOY_KEYAdd the same password in Unity
Deploy to itch.io
Create a new project on itch.io
Set
Kind of project
toHTML
Add the
DeployToItch
component to your scene and click theBuild
buttonWait for the build to finish, it will open a folder with the final zip when it has finished
Upload to final zip to itch.io
Select
This file will be played in the browser
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
- 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) - 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
ยน 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)
- Open
File > Build Settings
, selectNeedle 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 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: