Optimization & Compression

Make your Needle Engine projects load faster and run smoother. Learn about compression formats, build types, and optimization techniques to deliver the best experience to your users.

Also See

Understanding Build Types

Development Builds

Development builds are optimized for fast iteration during development:

  • No texture compression (KTX2) – faster build times
  • No mesh compression (Draco) – faster build times
  • No progressive loading – simpler debugging
  • Larger file sizes – not suitable for production

When to use: During active development and testing.

Production Builds

Production builds are optimized for performance and file size:

  • Texture compression using KTX2 (ETC1S or UASTC)
  • Mesh compression using Draco or Meshopt
  • Progressive texture loading for faster initial load
  • Automatic mesh LODs for better performance
  • Minimal file sizes for fast loading

When to use: For deployment to production websites.

See guides in your Editor (Unity or Blender) for accessing build options.

Production Build Setup

Required: Install toktx

To make production builds, you need toktx installed for texture compression using the KTX2 supercompression format.

Installation:

  1. Go to the toktx Releases Page
  2. Download and install the latest version (v4.1.0 or newer)
  3. Restart Unity after installation

Troubleshooting

If you've installed toktx and it's in your PATH but can't be found, restart your machine and try building again.

Troubleshooting: Toktx cannot 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.

Default install location: C:\Program Files\KTX-Software\binEnvironment Variables

Advanced: Custom glTF extensions

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

Texture Compression

Production builds compress textures using KTX2 (ETC1S or UASTC) or WebP depending on your settings and quality requirements.

Choosing Between ETC1S, UASTC and WebP

FormatETC1SUASTCWebP
GPU Memory UsageLowLowHigh (uncompressed)
File SizeLowHighVery low
QualityMediumVery highDepends on quality setting
Typical usageWorks for everything, best for color texturesHigh-detail data textures: normal maps, roughness, metallicFiles where ETC1S quality is insufficient but UASTC is too large

Quick Guide:

  • Color textures, UI: Use ETC1S for small file size
  • Normal maps, detail textures: Use UASTC for maximum quality
  • Photography, detailed textures: Use WebP if ETC1S quality isn't sufficient

Setting Compression Per Texture

You can override compression settings for individual textures using the Needle Texture Importer (Unity) or Material tab (Blender).

Unity: Global compression settings

Configure default compression for all textures:

Unity Compression Settings

Unity: Per-texture compression overrides

Use the Compression & LOD Settings component to override settings for specific textures. Assign all textures you want to override in the component.

Unity Individual Texture Settings

Blender: Per-texture compression settings

Select the Material tab to see compression options for all textures used by that material.

Texture Compression in Blender

Mesh Compression

Production builds compress meshes to reduce file size and improve loading times.

Choosing Between Draco and Meshopt

FormatDracoMeshopt
GPU Memory UsageMediumLow
File SizeLowestLow
Animation compressionNoYes

Quick Guide:

  • Static meshes: Use Draco for smallest file size
  • Animated meshes: Use Meshopt (supports animation compression)

By default, production builds use Draco compression. Use the MeshCompression component to choose between Draco and Meshopt per exported glTF.

Unity: Mesh compression settings

Use the Compression & LOD Settings component to select compression type:

Unity Mesh Compression Options

  • Current scene: Add component anywhere in your root scene
  • Prefab or NestedGltf: Add to a GltfObject or the prefab referenced by your components
  • Referenced scene: Add to the referenced scene that is exported
Unity: Mesh simplification to reduce vertex count

Use the Compression & LOD Settings component to configure mesh simplification for production builds. Append ?wireframe to your URL to preview meshes in the browser.

Unity Mesh Compression Options

Progressive Texture Loading (Texture LODs)

Significantly reduce initial loading time by loading low-resolution textures first, then upgrading to full quality when visible.

Add the Progressive Texture Settings component anywhere in your scene to enable progressive loading for all textures. Progressive loading is not applied to lightmaps or skybox textures.

Benefits:

  • Much faster initial load times
  • Full quality loaded on-demand
  • Seamless quality transitions
Unity: Enable progressive texture loading

Use the Compression & LOD Settings component to enable progressive loading globally. Can be disabled or enabled for individual textures as needed.

Unity Compression Settings

Automatic Mesh LODs (Level of Detail)

Since Needle Engine 3.36, mesh LODs are automatically generated during builds and chosen at runtime based on mesh density and screen size.

Key Benefits:

  • Faster initial loading time
  • Better rendering performance (fewer vertices on screen)
  • Faster raycasting with LOD meshes
  • Automatic on-demand loading
Unity: Control LOD generation

Use the Compression & LOD Settings component to control LOD generation for all meshes or individual meshes.

Unity Mesh Compression Options

Build Options

UnityUnity Build Window

Open File → Needle Engine → Build Window:

Unity Build Window

Available Options:

  • Build to Disk – Create production build in the dist folder
  • Preview Build – Build and start a local server to preview the final result
  • Development Build – Disable compression for debugging (not recommended for production)

Node.js is only required during development

The distributed website (using our default Vite template) is a static page that doesn't rely on Node.js and can be hosted on any regular web server.

Node.js is only required if you want to run our minimalistic networking server for multiplayer experiences.

Optimization Best Practices

Texture Optimization

File size matters:

  • Use the smallest texture resolution that looks good
  • Enable progressive loading for large textures
  • Use appropriate compression format (ETC1S vs UASTC vs WebP)
  • Avoid unnecessarily large texture atlases

GPU memory matters:

  • Use KTX2 formats (ETC1S or UASTC) instead of WebP when possible
  • WebP textures are uncompressed in GPU memory

Mesh Optimization

Reduce vertex count:

  • Use mesh simplification in production builds
  • Enable automatic LOD generation
  • Remove unnecessary geometry before export

Reduce draw calls:

  • Combine meshes when possible
  • Use instancing for repeated objects
  • Minimize unique materials

Scene Optimization

Reduce initial load time:

  • Enable progressive texture loading
  • Use automatic mesh LODs
  • Load large scenes progressively with SceneSwitcher
  • Use AssetReference for on-demand loading

Improve runtime performance:

  • Optimize physics colliders (simpler shapes when possible)
  • Disable unnecessary components
  • Use object pooling for frequently spawned objects
  • Profile with browser DevTools and Needle Inspector

Troubleshooting

Build errors during compression

Problem: Production build fails during compression

Solution:

  1. Toggle Development Build on in Build Settings to get unstuck immediately
  2. Report the bug to Needle support
  3. Check that toktx is installed and in your PATH

Website doesn't work after upload

Problem: Deployed website shows errors or doesn't load

Solution:

  • Option 1: Enable gzip compression on your server (see .htaccess example)
  • Option 2: Turn off gzip compression in File → Needle Engine → Build Window

Build Options Gzip