Troubleshooting and Gotchas

Troubleshooting and Gotchas

This guide details runtime bugs, decompiler quirks, and diagnostic traps encountered during IL2CPP porting, formatted by Symptom → Cause → Fix.

---

1. Scene Data Search Fails in Shipped Builds

Symptom

Running grep or searching a text editor for scene names (like RealRoom or InGame) inside shipped binary build files returns zero matches, leading you to believe the scene was omitted from the build.

Cause

Unity scene data inside .data files is LZ4-compressed. Searching raw binary strings against compressed bytes produces false negatives.

Fix

Dump the binary bytes around the search area or use tools like AssetRipper / UnityPy to decompress LZ4 blocks. Do not rely on literal string grep against packed Unity data files.

---

2. Reconstructed Symbols Missing in Compiled .wasm

Symptom

Searching a decompressed WebGL .wasm binary for your C# class or method names returns MISSING for all symbols, leading you to believe your scripts failed to compile into the WebGL build.

Cause

IL2CPP does not store managed type or method name strings inside the WebAssembly binary (.wasm). It stores type metadata inside global-metadata.dat, which ships inside the WebGL build's .data package.

Fix

Search global-metadata.dat inside the WebGL output folder rather than .wasm. Checking global-metadata.dat returns all expected class and method symbols.

---

3. Main Menu Panel Entirely Invisible on Launch

Symptom

After decompiling and importing a project, launching the game opens a blank screen. The UI canvas is present in the hierarchy, but 107 of 108 menu buttons are hidden.

Cause

Out of 4,903 stripped methods in the project, two specific empty methods caused this:

1. Menu.Start(): The original script activates the menu UI panel on start (gameObject.SetActive(true)). In the decompiled export, the menu panel defaults to activeSelf = false, and Menu.Start() is an empty stub.
2. ButtonMouseClick.OnPointerEnter / OnPointerClick: Stripped stub bodies prevent pointer events from reaching eventClick.

Fix

Implement these two method bodies by hand:

// Inside Menu.cs
private void Start()
{
    if (menuPanel != null)
    {
        menuPanel.SetActive(true);
    }
    Cursor.lockState = CursorLockMode.None;
    Cursor.visible = true;
}

Activating the panel restores all 107 menu buttons and their surviving UnityEvent chains.

---

4. Loading Screen Progress Bar Stuck / Not Animating

Symptom

The loading screen progress bar remains static, and you suspect .anim animation clips were broken during asset import.

Cause

Inspecting the loading scene reveals zero Animator components and zero legacy Animation components. The loading bar was never animation-driven—it was driven entirely by a script updating AsyncOperation.progress.

Fix

Rebuild the script driver directly using surviving RectTransform geometry (e.g., a 500×10 track with a left-edge pivot) and update its size delta against loading progress:

private IEnumerator LoadSceneRoutine(string sceneName)
{
    AsyncOperation op = SceneManager.LoadSceneAsync(sceneName);
    while (!op.isDone)
    {
        float progress = Mathf.Clamp01(op.progress / 0.9f);
        if (progressBarRect != null)
        {
            progressBarRect.SetSizeWithCurrentAnchors(RectTransform.Axis.Horizontal, progress * 500f);
        }
        yield return null;
    }
}

---

5. NullReferenceException Thrown Every Frame on Object Highlight

Symptom

When aiming at an interactive object, the console spams NullReferenceException every frame, causing severe frame drops.

Cause

The third-party object outline highlighting package was stripped during IL2CPP compilation. Its OutlineParameters property getter was compiled into return null;. Any code accessing outline.OutlineParameters.Color attempts to dereference null.

Fix

Add explicit null guards around stripped package property getters:

if (outline != null && outline.OutlineParameters != null)
{
    // Access parameters safely
    Color highlightColor = outline.OutlineParameters.Color;
}
else
{
    // Fallback highlighting logic
}

---

6. Unity WebGL Server Decompression Error

Symptom

Serving a WebGL build with python -m http.server causes the browser to throw a decompression error on .wasm.br or .data.br.

Cause

Unity WebGL builds output Brotli-compressed files (.br). Browsers reject Brotli files unless the HTTP response carries Content-Encoding: br and proper MIME types. Standard http.server serves them as raw opaque octet streams without encoding headers.

Fix

Use tools/serve-webgl.py, which binds to 127.0.0.1 and injects the required Brotli and WASM headers:

python tools/serve-webgl.py "C:\Path\To\WebGLBuild" 8080