optimize-web

Performance Notes

• Take your time to do this thoroughly.
• Quality is more important than speed.

Running C# in the Editor

unity-cli

com.unity.pipeline

• You need

  eval

  in particular, not just a reachable Editor. Confirm it appears in the catalog. Its presence depends on the Pipeline package version, not on the CLI, so a healthy install can still lack it — if it's missing, say so and stop.
• Player Settings can be read from

  ProjectSettings/ProjectSettings.asset

  in a pinch, but do not write them that way. The serialized names don't match the API names, several of these settings are per-build-target, and a hand-edited value silently disagrees with what the build actually uses. An unreachable Editor is a stop for the write steps.

unity command eval --code '<snippet>'

unity command

Passing C# to

eval

eval

• No

  using

  directives. The compiler reads

  using UnityEditor;

  as a resource-disposal statement and rejects it (

  CS0210

  ).
• Types must be fully qualified. A bare

  PlayerSettings

  does not resolve (

  CS0246

  ), and a bare

  Object

  is ambiguous with

  object

  (

  CS0104

  ).

Reading the settings this skill audits

var target = UnityEditor.Build.NamedBuildTarget.WebGL;
var w = new System.Collections.Generic.List<string>();
w.Add($"activeBuildTarget={UnityEditor.EditorUserBuildSettings.activeBuildTarget}");
w.Add($"compressionFormat={UnityEditor.PlayerSettings.WebGL.compressionFormat}");
w.Add($"decompressionFallback={UnityEditor.PlayerSettings.WebGL.decompressionFallback}");
w.Add($"stripEngineCode={UnityEditor.PlayerSettings.stripEngineCode}");
w.Add($"managedStrippingLevel={UnityEditor.PlayerSettings.GetManagedStrippingLevel(target)}");
w.Add($"il2cppCodeGeneration={UnityEditor.PlayerSettings.GetIl2CppCodeGeneration(target)}");
w.Add($"apiCompatibilityLevel={UnityEditor.PlayerSettings.GetApiCompatibilityLevel(target)}");
w.Add($"exceptionSupport={UnityEditor.PlayerSettings.WebGL.exceptionSupport}");
w.Add($"debugSymbolMode={UnityEditor.PlayerSettings.WebGL.debugSymbolMode}");
w.Add($"dataCaching={UnityEditor.PlayerSettings.WebGL.dataCaching}");
w.Add($"wasm2023={UnityEditor.PlayerSettings.WebGL.wasm2023}");
w.Add($"initialMemorySize={UnityEditor.PlayerSettings.WebGL.initialMemorySize}");
w.Add($"maximumMemorySize={UnityEditor.PlayerSettings.WebGL.maximumMemorySize}");
w.Add($"memoryGrowthMode={UnityEditor.PlayerSettings.WebGL.memoryGrowthMode}");
w.Add($"targetFrameRate={UnityEngine.Application.targetFrameRate}");
w.Add($"vSyncCount={UnityEngine.QualitySettings.vSyncCount}");
return string.Join("\n", w);

PlayerSettings.GetManagedStrippingLevel(NamedBuildTarget.WebGL)

PlayerSettings.managedStrippingLevel

UnityEditor.WebGL.UserBuildSettings.codeOptimization

PlayerSettings.WebGL.codeOptimization

PlayerSettings.WebGL.optimizationLevel

PlayerSettings.GetIl2CppCodeGeneration(NamedBuildTarget.WebGL)

UserBuildSettings

Applying the settings

[MenuItem]

eval

Assets/Editor/

UnityEditor.EditorApplication.ExecuteMenuItem("Tools/Apply Web Release Settings");

using

eval

0. Pre-Flight

1. Confirm Web build target: Read, with the Pre-Flight snippet above,

   EditorUserBuildSettings.activeBuildTarget

   — must be

   WebGL

   ; if not, warn the user.
2. Read compression and stripping settings: Read

   compressionFormat

   ,

   decompressionFallback

   ,

   stripEngineCode

   and the managed stripping level with the Pre-Flight snippet above. Note the stripping level is

   PlayerSettings.GetManagedStrippingLevel(NamedBuildTarget.WebGL)

   — there is no

   PlayerSettings.managedStrippingLevel

   property.
3. Read exception and optimization settings: Read

   PlayerSettings.WebGL.exceptionSupport

   from the Pre-Flight snippet above. For the wasm code optimization level use

   UnityEditor.WebGL.UserBuildSettings.codeOptimization

   — the

   PlayerSettings.WebGL.codeOptimization

   and

   optimizationLevel

   spellings do not exist and will not compile.
4. Read frame rate settings: Read, with the Pre-Flight snippet above,

   Application.targetFrameRate

   and

   QualitySettings.vSyncCount

   .
5. Read additional player settings: Read, with the Pre-Flight snippet above,

   PlayerSettings.WebGL.dataCaching

   ,

   PlayerSettings.WebGL.debugSymbolMode

   ,

   PlayerSettings.WebGL.maximumMemorySize

   , and

   PlayerSettings.GetApiCompatibilityLevel

   .
6. Proceed only after compression, stripping, frame rate, and player settings are confirmed.

1. Assess Current State

1. Check Build Report: Instruct the user to open

   Window > General > Build Report

   after a build and identify the largest asset and code size contributors.
2. Verify server configuration: Ask the user to confirm whether the hosting server sends

   Content-Encoding: br

   (Brotli) or

   Content-Encoding: gzip

   headers, and whether

   Content-Type: application/wasm

   is set for

   .wasm

   files.
3. Check frame rate config: Confirm, with the Pre-Flight snippet above,

   Application.targetFrameRate

   — should be

   -1

   for Web (let the browser drive).
4. Check memory settings: Read, with the Pre-Flight snippet above,

   PlayerSettings.WebGL.initialMemorySize

   and

   PlayerSettings.WebGL.memoryGrowthMode

   .
5. Report findings before making recommendations.

2. Understand Request

OnDemandRendering

targetFrameRate = -1

3. Web Build Optimization Workflow

IMPORTANT: One-click optimization script

Assets/Editor/WebOptimizer.cs

try/catch

Player Settings audit

eval

try/catch

requestAnimationFrame

Compression and server configuration

• Serve

  .br

  files with

  Content-Encoding: br

  .
• Serve

  .gz

  files with

  Content-Encoding: gzip

  .
• Set

  Content-Type: application/wasm

  for

  .wasm

  ,

  application/javascript

  for

  .js

  .
• Enable HTTP/2 or HTTP/3 to parallelize chunk fetches.

Content-Encoding

Exception handling

Remove unused resources

Packages/manifest.json

Edit > Project Settings > Graphics

com.unity.web.stripping-tool

Quality settings for Web

Edit > Project Settings > Quality

• Use Very Low or Low as the default Web quality level.
• Set it with

  eval

  :

  UnityEngine.QualitySettings.SetQualityLevel(0, true);

  where 0 = Very Low.
• Consider creating a Web-specific quality level that disables features unnecessary in-browser (real-time shadows, post-processing effects, high particle counts).

Frame rate on Web

• Set it with

  eval

  :

  UnityEngine.Application.targetFrameRate = -1;

  — let the browser use

  requestAnimationFrame

  .
• Note: Safari caps at 60 fps in WebGL; high-refresh targets do not apply.
• Use

  OnDemandRendering.renderFrameInterval

  to drop to 5–10 fps on static/idle screens to save battery.

KTX / Basis Universal textures

com.unity.cloud.ktx

toktx

basisu

--assign_oetf linear

--genmipmap

KtxTexture.LoadFromStreamingAssets

KtxTexture.LoadFromBytes

--lower_left_maps_to_s0t0

toktx

Streaming on Web

• Use Addressables with remote groups hosted on a CDN with Brotli / Gzip.
• Avoid bundling the entire game into the initial download; stream levels on demand.
• Target < 30 MB initial download for "instant play"; level data follows.
• For streamed textures targeting mixed GPU hardware, prefer KTX2 bundles over per-platform variants — one bundle serves all browsers.

Profiling Web builds

Player Settings > Publishing > Debug Symbols

using UnityEditor;
using UnityEditor.Build;
using UnityEditor.Build.Reporting;

public class WebProfilingBuildProcessor : IPreprocessBuildWithReport
{
    public int callbackOrder => 0;
    public void OnPreprocessBuild(BuildReport report)
    {
        PlayerSettings.SetAdditionalIl2CppArgs("--compiler-flags=--profiling-funcs");
    }
}

PlayerSettings.WebGL.emscriptenArgs

--cpuprofiler

--memoryprofiler

--threadprofiler

about:memory

about:memory

Web memory directives

• Disable Read/Write Enabled on textures and meshes — it duplicates data into the WASM heap.
• Reduce

  .data

  file size by moving assets to Addressables or AssetBundles.
• Use compressed texture formats (KTX2/Basis) to reduce both download and decoded memory cost.

iOS Safari memory limits

• iOS < 18: WebContent process limit ~1.5 GB. WASM memory (Gigacage) capped at 2 GB. Typed arrays share this pool. On iPhone X (iOS 16) heap growth caps at ~512 MB, but setting Initial Memory Size to 512 MB–1.5 GB upfront works.
• iOS 18+: Limits largely lifted; iPhone 11 can allocate ~4 GB.
• On iOS, set Initial Memory Size to the target peak rather than relying on growth — Safari handles large upfront allocations better than incremental growth.
• WASM heap > 300 MB risks crashes on older iOS; target < 200 MB for broad compatibility.

Video and audio on Web

• Video: Playback only works from a URL (server with CORS enabled) or from StreamingAssets. On iOS the server must support HTTP range requests for streaming. Use browser-compatible formats (MP4/H.264).
• Audio: AudioEffects (mixer effects) require compute shaders — not available on WebGL. Mixers and MixerGroups work for volume control only. Set audio to Mono to improve loading. If

  about:memory

  shows web audio > 100 MB, audio is likely uncompressed — switch to Vorbis.

Canvas and DPI

devicePixelRatio

4. Validation

1. Re-read the Player Settings with the Pre-Flight snippet (compression, stripping, exceptions, targetFrameRate).
2. Rebuild the player and compare Build Report file sizes with baseline.
3. Verify in at least Chrome and Safari (GC and JIT behavior differ).
4. Max 3 iterations before asking the user for feedback.

5. Troubleshooting

Build still large after enabling Strip Engine Code

1. Is Managed Stripping Level set to Medium or Low? → Set to High for release.
2. Are plug-ins using reflection to access engine modules that would otherwise be stripped? → Add a

   link.xml

   to preserve needed symbols.
3. Is Exceptions set to Full? → Full adds the largest code overhead; switch to None or Explicitly Thrown Only.

Brotli not working — Decompression Fallback required

1. Is the server sending

   Content-Encoding: br

   ? → Without this header the browser won't decompress; the fallback JS decompressor is then needed.
2. Is the build hosted over HTTP (not HTTPS)? → Brotli requires a secure context; degrade to Gzip for HTTP hosting.

Stutter in Safari but not Chrome

1. Does the project set

   Application.targetFrameRate = 60

   ? → On Safari WebGL this conflicts with browser pacing; set to

   -1

   .
2. Are there shaders that behave differently on Safari's WebGL implementation? → Test on device; Safari's WebGL/Wasm runtime differs from Chromium — some GLSL constructs are handled differently.

Memory growth slow path triggered

1. Is Initial Memory Size too small for the project's peak? → Wasm memory growth requires a full buffer copy; set Initial Memory Size to a realistic peak estimate.
2. Is Memory Growth Mode set to Linear? → Switch to Geometric for saner growth curve.

Frame rate set to 60 but browser runs erratically

1. Is

   Application.targetFrameRate = 60

   set in code? → On Web this conflicts with

   requestAnimationFrame

   browser pacing. Set to

   -1

   .
2. Is

   vSyncCount

   non-zero? → Set to 0; the browser handles pacing.

Firefox cache rejecting large files

browser.cache.disk.max_entry_size

about:config

Local dev server setup

# Python (HTTP)
python -m http.server 55553 -d path/to/build

# Node.js (install serve-handler)
npx serve path/to/build -l 3001

6. Completion

• Summarize: initial download size delta, settings changed (compression, stripping, exceptions, targetFrameRate), server configuration confirmed.
• List follow-up actions: CDN setup for Addressables remote groups, Safari testing, Wasm 2023 feature set upgrade when browser baseline allows.

See also

• Addressables package — remote groups served over a CDN, when the download budget needs content moved out of the initial payload.
• Unity Profiler, connected to the browser — the cross-platform profiling methodology. Section 3 covers the Web-specific part of attaching it.
• Shader variant stripping (Graphics settings → Shader Stripping, and

  ShaderVariantCollection

  ) — variant count feeds directly into Wasm size, so it is worth checking when stripping alone hasn't moved the number.
• Project Settings → Player — the same flags this skill reads, if the user would rather see them in the inspector than have them reported.
• Mobile browser battery behaviour follows the same frame-rate and quality-level guidance in Sections 3 and 4; there is no separate mobile path here.