Gimp Online

Appearance

Understanding Unity WebGL Build Output ​

When you build a Unity project for WebGL, the engine generates several files that together enable your game or application to run smoothly in a web browser. Understanding these files and their roles can help you optimize performance, debug issues, and better grasp how Unity handles WebGL deployments.

Overview of WebGL Build Files ​

A typical Unity WebGL build produces the following files and folders:

  • index.html
  • Build folder
    • <ProjectName>.json
    • <ProjectName>.data
    • <ProjectName>.wasm
    • UnityLoader.js (for older Unity versions)
    • <ProjectName>.js
    • <ProjectName>.framework.js
    • Compression files (optional)

Let's delve into each of these components to understand their purpose.

Detailed Breakdown ​

index.html ​

This is the default HTML file that loads your Unity content. It sets up the basic HTML structure and includes necessary scripts to initialize and run your WebGL build within the browser.

Key Points:

  • Contains a <canvas> element where your Unity content is rendered.
  • Includes script tags to load Unity's WebGL runtime and your build files.
  • Can be customized to fit into your website's design or to add additional functionality.

Build Folder ​

This folder houses the core files required for your Unity content to function in a web environment.

<ProjectName>.json ​

A JSON file that contains configuration and build information.

Key Points:

  • Stores data such as the Unity version, build settings, and compression formats.
  • Used by the loader scripts to properly initialize your application.

<ProjectName>.data ​

A binary data file that includes all your project's assets and scenes.

Key Points:

  • Contains serialized assets like textures, models, audio, and compiled game scripts.
  • Unity packages all necessary resources into this file to streamline loading.
  • Proprietary format not intended for manual editing or parsing.

<ProjectName>.wasm ​

A WebAssembly binary that includes the compiled Unity engine code.

Key Points:

  • WebAssembly (Wasm) allows high-performance code execution in web browsers.
  • Contains the Unity runtime and your game's logic compiled from C# to Wasm via IL2CPP.
  • Browsers execute this file to run your game efficiently.

UnityLoader.js (Unity 2018 and earlier) ​

A JavaScript file responsible for loading and initializing your Unity content.

Key Points:

  • Manages fetching and setting up the data and Wasm files.
  • Handles compatibility checks and error reporting.
  • Not present in newer Unity versions, replaced by other scripts.

<ProjectName>.js and <ProjectName>.framework.js ​

JavaScript files generated in newer Unity versions (2019 onwards).

Key Points:

  • <ProjectName>.js acts as the entry point, handling module loading and initialization.
  • <ProjectName>.framework.js includes supporting JavaScript code that interfaces between the Wasm module and the browser.
  • Work together to bootstrap the WebAssembly code and manage runtime behavior.

Compression Files (Optional) ​

Depending on your build settings, you might see compressed versions of the above files, such as .gz or .br extensions for Gzip or Brotli compression.

Key Points:

  • Compressing build files reduces download sizes, improving load times.
  • Browsers must support the respective compression formats to decompress and use these files.
  • Server configuration is required to serve compressed files correctly.

How Unity Handles WebGL Builds ​

Asset Packaging ​

Unity serializes and packs all required assets into the .data file during the build process.

  • Optimization: Only assets referenced in scenes or via code are included, reducing unnecessary bloat.
  • Streaming Assets: Large files or assets needed at runtime can be placed in the StreamingAssets folder, but accessing them in WebGL builds requires special handling due to browser security restrictions.

Code Compilation ​

C# scripts are compiled using the IL2CPP backend for WebGL builds.

  • Intermediate Language (IL): Your C# code is first compiled to IL.
  • C++ Translation: IL is then converted to C++ code.
  • WebAssembly Output: Finally, the C++ code is compiled to WebAssembly (.wasm), allowing efficient execution in browsers.

Runtime Initialization ​

When the user accesses your Unity WebGL content:

  1. HTML Page Loads: The index.html page loads in the browser.
  2. Scripts Execute: Loader scripts initialize and set up the Unity canvas.
  3. Assets and Code Fetching: The .json, .data, and .wasm files are fetched.
  4. Decompression: If files are compressed, the browser decompresses them.
  5. WebAssembly Instantiation: The Wasm module is compiled and instantiated.
  6. Game Starts: Your game or application begins executing within the browser context.

Optimizing Your WebGL Build ​

Here are some tips to enhance performance and reduce the size of your WebGL builds:

Enable Compression ​

  • Gzip/Brotli: Use compression to significantly reduce file sizes.
  • Server Configuration: Ensure your web server is set up to serve compressed files and includes the correct MIME types and headers.

Strip Unused Code ​

  • Engine Code Stripping: Enable engine code stripping in Player Settings to remove unnecessary Unity engine features.
  • Managed Code Stripping: Use managed code stripping to eliminate unused script code.

Optimize Assets ​

  • Texture Compression: Use appropriate texture compression formats for WebGL.
  • Asset Bundles: Load assets on demand using Asset Bundles to keep initial load times low.
  • Reduce Resource Sizes: Optimize models, audio files, and other assets to be as small as possible without sacrificing quality.

Build Settings ​

  • Development Build: Disable development build for production to optimize performance.
  • Exceptions Handling: Set exception support to a reasonable level; full exception support increases build size.

Common Challenges and Solutions ​

Browser Compatibility ​

  • WebGL Support: Ensure the target browsers support WebGL 2.0 for better performance.
  • Feature Detection: Use Unity's built-in checks or custom scripts to inform users if their browser isn't supported.

Memory Management ​

  • Memory Allocation: Set an appropriate memory size in Player Settings; too low can cause crashes, too high can waste resources.
  • Profiling: Use the Unity Profiler to identify and fix memory leaks or excessive allocations.

Debugging ​

  • Error Handling: Use browser developer tools to inspect console logs and debug issues.
  • Exception Support: Temporarily enable full exception support to get detailed stack traces during development.

Conclusion ​

Understanding the output of a Unity WebGL build is crucial for optimizing your game or application's performance and ensuring a smooth user experience. By knowing the roles of each generated file and how they work together within the browser environment, you can make informed decisions about asset management, code optimization, and deployment strategies.

Remember to:

  • Leverage Unity's optimization features.
  • Keep abreast of the latest Unity updates for WebGL improvements.
  • Test your builds across different browsers and devices to ensure broad compatibility.

With careful planning and optimization, your Unity WebGL projects can reach a wide audience with engaging, high-performance content right in their web browsers.

References: