Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Reduce Web startup time with progressive asset loading

Use progressive asset loading to reduce the startup time for Web builds.
Read time 4 minutesLast updated 19 days ago
Progressive asset loading reduces load time for Web builds by downloading assets on a per-scene basis instead of downloading all assets at once. In this loading model, only assets needed to initialize and render the first scene are downloaded synchronously before the game starts. All other assets needed for later scenes are downloaded asynchronously in the background.
Enable Progressive Asset Loading in the Web Player settings (menu: Edit >
Project Settings

?

> Player > Publishing Settings > Progressive Asset Loading).

Review the Build output

Progressive asset loading changes how Unity packages the Web build. Instead of a single 
.data
file, Unity writes multiple files that it downloads independently.
You can review the startup and background asset lists in the generated 
index.html
file of your Web build.
If progressive asset loading is enabled while file compression is disabled, the build output will be larger than a build that doesn't use progressive asset loading. To avoid increasing the build output size, it's important to enable Compression Format in the Player settings.

Understand loading priority

To get the application running as quickly as possible, Unity first downloads only the content required to:
  • Initialize the player
  • Load and render the first scene
Unity downloads all content unique to later scenes after the first scene is active.

Decide when to use progressive asset loading

Progressive asset loading is most effective when startup is constrained by asset download time and the first scene requires only a subset of the project’s content.
Use progressive asset loading when:
  • Your project includes multiple scenes, such as a menu scene followed by gameplay scenes.
  • The first scene is lightweight.
  • Large assets, such as textures, meshes, audio, or video, are used mainly in later scenes.
  • Startup is limited by asset download time, especially on slower or high-latency networks.
Progressive asset loading is less effective when:
  • Your project uses only a single scene.
  • Most assets are required in the first scene.
  • Many assets are shared across all scenes.
  • Startup is limited mainly by the size of the 
    .wasm
    file.

Organize content for better results

Project structure directly impacts the effectiveness of progressive asset loading. To maximize performance:
  • Keep the first scene as lightweight as possible.
  • Place large scene-specific assets in later scenes.
  • Minimize the size of globally required assets.

Choose between asynchronous and synchronous scene loading

If the application switches to a scene whose assets are still downloading, Unity delays the transition until those assets are available.
When loading scenes:
  • Use 
    SceneManager.LoadSceneAsync
    : Asynchronous loading allows the application to remain interactive or display a custom loading UI while assets arrive.
  • Avoid 
    SceneManager.LoadScene
    : Synchronous loading can stall the frame and prevent user interaction until the download completes.

Display a synchronous scene loading indicator

If you need to use synchronous scene loading, display a loading indicator in your Web template to make the experience clearer for users. The indicator helps signal that loading is in progress, rather than making it seem as though the game has frozen. While synchronous scene loading is in progress, the Canvas doesn't update and users can't interact with it.
The Default and PWA templates include a loading indicator. If you use a custom template, you must implement this yourself, though you can use the built-in templates as a reference. As with the initial load of your game, if you load a scene whose assets haven't finished downloading, the 
onProgress
callback provided to 
createUnityInstance
 is invoked with a numeric argument between 0.0 and 1.0 indicating the loading progress of the new scene.
Because the loading indicator is not part of the Unity 
canvas
, special care must be taken to ensure it appears on the screen in fullscreen mode. In your custom Web template, create an HTML element with a unique 
id
attribute that will serve as the fullscreen container. Ensure the Unity 
canvas
element and your loading indicator are descendants of this container, and specify the container element ID as the 
fullscreenElementID
property of the 
config
 parameter when calling 
createUnityInstance
.
<html><!-- ... --><body>    <div id="unity-fullscreen-container">        <canvas id="unity-canvas" width="{{{ WIDTH }}}" height="{{{ HEIGHT }}}" tabindex="-1"></canvas>        <div id="unity-loading-container">            <!-- loading container contents -->        </div>    </div>    <script>        const canvas = document.getElementById("unity-canvas");        const config = {            fullscreenElementID: "unity-fullscreen-container",            // other config properties...        }        createUnityInstance(canvas, config, (progress) => {            // update loading indicator        });    </script></body></html>
Use the provided Default and PWA templates as a reference.

Limitations

Progressive asset loading isn’t compatible with the following Player settings:
  • Name Files as Hashes
  • Decompression Fallback
For more information on these Player settings, refer to Web Player settings.

Additional resources