What does deployment mean?

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.

Available Deployment Targets

Feel something is missing?

Please let us know in our discordopen in new window!

Deploying to the web from Unity

Open File/Build Settings and select Needle Engine for options!

Where do I find the Build Options in Unity?

image
image

To build your web project for deployment to a 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.

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).

Development Builds

See guides above on how to access the options from within your Editor (e.g. Unity or Blender).

The main difference to a production build is that it does not perform ktx2open in new window and dracoopen in new window compression (for reduction of file size and loading speed) as well as the option to progressively load high-quality textures.

We generally recommend making production builds for optimized file size and loading speed (see more information below).

Production Builds

To make a production build, you need to have toktxopen in new window installed, which provides texture compression using the KTX2 supercompression format. Please go to the toktx Releases Pageopen in new window 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.

Advanced: Custom glTF extensions

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

Optimization and Compression Options

Texture compression

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?

FormatETC1SUASTCWebP
GPU Memory UsageLowLowHigh (uncompressed)
File SizeLowHighVery low
QualityMediumVery highDepends on quality setting
Typical usageWorks for everything, but best for color texturesHigh-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.

Unity: How can I set per-texture compression settings?

image
image

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.
Texture Compression options in Blender

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
image

Progressive Texture loading

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.

How can I enable progressive texture loading?

Progressive textures can be enabled per texture
or for all textures in your project:

image

Enable for all textures in the project that don't have any other specific setting:

image

Mesh compression and simplification

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?

FormatDracoMeshopt
GPU Memory UsageMediumLow
File SizeLowestLow
Animation compressionNoYes
How can I set draco and meshopt compression settings?

Add the MeshCompression component to select which compression should be applied per exported glTF.

image

  • 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
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:
image

Deployment Options

Deploy to Glitch ๐ŸŽ

Glitchopen in new window 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.

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.

How do I deploy to Glitch from Unity?
  1. Add the DeployToGlitch component to the GameObject that also has the ExportInfo component.

  2. Click the Create new Glitch Remix button on the component image

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

  4. Open Unity again and paste the URL in the Project Name field of your Deploy To Glitch component
    image

  5. 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)
    waiting for the key

  6. Once the Deploy Key has been received you can click the Build & Deploy button to upload to glitch.

How do I deploy to Glitch from Blender?

Deploy To Glitch from Blender component

  1. Find the Deploy To Glitch panel in the Scene tab
  2. Click the Remix on glitch button on the component
  3. Your browser will open the glitch project template
  4. Wait for Glitch to generate a new project
  5. 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)
  6. On Glitch open the .env file and enter a password in the field Variable Value next to the DEPLOY_KEY
  7. Enter the same password in Blender in the Key field
  8. 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

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 glitch.comopen in new window and make sure you are signed in. After that you then try clicking the button again in Unity or Blender.

Deploy to Netlify

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 deployt to existing projects.

Deploy to netlify component

Deploy to netlify component

Deploy to Vercel

  1. Create a new project on vercel
  2. Add your web project to a github repository
  3. Add the repository to your project on vercel

See our sample projectopen in new window for the project configuration

Deploy to itch.io

How do I deploy to itch.io from Unity?
  1. Create a new project on itch.ioopen in new window

  2. Set Kind of project to HTML
    image

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

  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
    20220920-104629_Create_a_new_project_-itch io-_Google_Chrome-needle

  6. Select This file will be played in the browser
    image

  7. Save your itch page and view the itch project page.
    It should now load your Needle Engine project ๐Ÿ˜Š

Optional settings

image

Itch.io: failed to find index.html

Failed to find index.html

image
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

How do I deploy to my FTP server from Unity?
  1. 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)
  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 in Unity
ยน Deploy to FTP component

Deploy to FTP server asset
ยฒ FTP Server asset containing the access information of your FTP user account

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

How do I deploy to my FTP server manually?
  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! ๐Ÿ˜‰

20220830-003602_explorer-needle

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.

Unity build window showing Needle Engine platform

Deploy to Github Pages

How do I deploy to Github Pages from Unity?

Add the DeployToGithubPages component to your scene and copy-paste the github repository (or github pages url) that you want to deploy to.
Deploy To github pages component

Deploy to Facebook Instant Games

With Needle Engine you can build to Facebook Instant Games automatically
No manual adjustments to your web app or game are required.

How do I deploy to Facebook Instant Games from Unity?
  • Add the Deploy To Facebook Instant Games component to your scene: Deploy to facebook instant games component
  • 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.
  • On Facebook add the Instant Games module and go to Instant Games/Web hostingHosting a facebook instant games
  • 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) Upload the zip to facebook instant games
  • That's it - you can then click the Play button next to each version to test your game on facebook.
How do I create a app on Facebook (with Instant Games capabilities)
  1. Create a new appopen in new window and select Other. Then click NextCreate facebook instant games app

  2. Select type Instant GamesCreate facebook instant games app

  3. After creating the app add the Instant Games product Add instant games product

Here you can find the official instant games documentationopen in new window 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.


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:
image

Needle Engine Commandline Arguments for Unity

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:

-scenepath 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)
-buildProductionrun a production build
-buildDevelopmentrun a development build
-debugopen a console window for debugging