Troubleshooting

This page helps you collect the right information when an obfuscated build does not behave as expected. Most issues come from names that Unity or another package still needs at runtime.

Start With This Checklist

  1. Make a normal build with the default Obfuscator settings.
  2. Test the build on the target platform.
  3. Enable one extra setting.
  4. Build and test again.
  5. If something breaks, check the log and keep the affected name stable with an attribute or a namespace rule.

This makes it much easier to find the setting that caused the problem.

Where To Find The Log

By default, the log is written to:

Assets/GUPS/Obfuscator/Log/{BuildTarget}.txt

For example, a Windows build may write a log for StandaloneWindows64.

You can set a custom log path in Project Settings -> GuardingPearSoftware -> Obfuscator -> Optional -> Logging.

What The Log Can Tell You

The log records the build steps and warnings from the Obfuscator. A warning does not always mean the build is broken. Many warnings explain why a name was kept unchanged.

Common reasons are:

  • A UnityEvent, animation event, or coroutine needs the original method name.
  • A field is serialized by Unity or JSON.
  • A third-party package needs a class or method name.
  • A setting or attribute told the Obfuscator to skip a name.
  • A dependency could not be resolved and needs to be added in the Assembly settings.

Not Obfuscated Causes

In development builds, the Obfuscator can add internal information that explains why a member was not obfuscated. This is mainly for debugging and support. You normally do not need to use this attribute yourself.

If support asks why a class, method, field, property, or event was not renamed, send the log and mention that it was a development build.

Mapping Files

A mapping file connects original names with obfuscated names. It is useful for crash logs and for keeping names stable between builds.

Use this workflow:

  1. Enable Save an obfuscation mapping file in Optional -> Renaming.
  2. Build the game.
  3. Store the mapping file with the exact build version.
  4. Keep the mapping file private.
  5. Use the ErrorStack window to read obfuscated stack traces.

Each build should have its own mapping file. Do not use a mapping file from a different build version.

When Unity Data Breaks

Unity scenes, prefabs, ScriptableObjects, and Inspector fields can store names. If those names are changed, Unity may not connect the saved data correctly.

If this happens:

  1. Find the affected class, method, field, or property.
  2. Add DoNotRename to the single member if only the name must stay the same.
  3. Add DoNotObfuscateClass if the whole class and its members must keep their names.
  4. Use namespace skipping if a full namespace belongs to DTOs, save data, networking, or another name-based system.
  5. Rebuild and test again.

When A Third-Party Package Breaks

First check the Compatibility tab. Enable the matching package setting if one exists.

If the package is not listed, check whether it uses:

  • JSON data.
  • Reflection.
  • RPC or network message names.
  • Inspector-assigned callbacks.
  • Generated code.

If it does, keep those names stable with attributes or namespace skipping.

What To Send To Support

Please include:

  • The Obfuscator log file.
  • The Unity Console error, if there is one.
  • The target platform and scripting backend.
  • The Obfuscator version.
  • The Unity version.
  • The settings you recently changed.
  • A short description of what you expected and what happened instead.

If the issue is a crash log, also include the matching mapping file path or confirm that mapping was enabled for that build.