Zombie Object Detector
Scripts to detect and diagnose zombie objects.
Description of Zombie Objects
The best description of what we mean by a "zombie" object is in a 2014 blog post here https://blogs.unity3d.com/2014/05/16/custom-operator-should-we-keep-it/. Specifically the paragraph labelled "purpose two".
To recap: Many C# classes in the
UnityEngine namespace act as wrappers to instances of corresponding C++ classes, which hold the actual data. The class
UnityEngine.GameObject is an example. Zombie objects are instances of these C# classes that have outlived their C++ counterpart. The C++ instances are destroyed in an entirely deterministic fashion, for example on scene transition. On the other hand the C# instances are garbage collected just like any other C# object. This means that there is an opportunity for the C# object to remain in existence by being referenced by other objects, static variables, etc.
How this tool determines Zombie Objects
The tool attempts to traverse every instance of every class. From any one object, it uses reflection to obtain every field of that object, and simply recurses into each one. It does this until it has examined every object in memory.
An object is considered a zombie if its
ToString function returns the string
"null". (i.e. the string containing the four characters
l, rather than a null string).
TODO There is a better way that does not generate a temporary string:
GameObject go = ... ; object o = go; bool zombie = (go == null) && (o != null);
- Copy the
.csfiles from this repository into your own project.
This repository contains an example project that contains various examples of Zombie objects. These examples are simple and easy to fix. In larger projects this is not always the case. This tool will help you find them, and give you a trace of where and what is keeping them alive.
Basic In-Editor Tests
Run the game in editor, and load and unload scenes.
Right click in the scene hierarchy and add a zombie detector.
Select the Zombie Detector, and in the inspector click Log Zombies.
Wait for it to complete, console will show all zombies found, it will also be saved to a log file.
Right click in the scene hierarchy of a scene that will persist between loads and add a zombie detector.
Set the desired log key in the zombie detector's inspector.
Build and launch the game.
Load scenes as normal
Press Log Zombie Key
This will be saved to the .ZombieLogs folder (dependent on platform)
- Note: It will fail to write if it doesn't have permissions to dataPath(i.e. Packaged Console Builds) It will still output to the Debug Console however.
Log Save Location
Logs are written to
Application.dataPath, in a subdirectory called
|IgnoredMembers||Shows member variables that have been ignored.|
|FieldInfoNotFound||Shows reflection fieldinfo on a member that hasn't been found, this usually means reflection is confused about what type of member it is.|
|MemberType||Shows member variables type: Field, Method, etc.|
|FieldType||Shows what type of field it is; Array or default Other.|
|AlreadySearched||Shows objects that have already been searched, so wont be searched again.|
|InvalidType||Shows types that are considered invalid, NumericTypes, Pointers, GenericParameters, and anything in the Ignored types list.|
|Exceptions||Shows exceptions that can generally be ignored, for example the exception caused by a bad Equals implementation.|
|ListBadEquals||Shows a list of all classes that have bad implementations of the Equals function.|
|ListScannedObjects||Shows a list of all objects scanned (Not All types*)|
|StaticFieldZombieCount||Shows how many objects each static field has connected to it.|
|FullZombieStackTrace||Outputs the full stack trace from zombie object all the way back to the original static field.|
Inserts the tag into the filename.
Types to Scan
The whitelist of types that will have their initial statics scanned, it doesn’t reduce subsequent scans. Useful if wishing to only check a specific static field’s zombies. Leave empty to scan all objects.
Types to ignore
The blacklist of types that will be ignored at every stage, initial statics and all subsequent object scans.
Zombie Logging Key Code
A simple way of hooking up a keycode for starting zombie logging.
Unsafe pointer: requires Unity 2017.1 or for the msc.rsp file to be declared with -unsafe. https://stackoverflow.com/questions/39132079/how-to-use-unsafe-code-unity/39132664#39132664
BadEqualImplementation: Equals is overridden with a bad example that causes it to get ignored.
FalsePositive: Override of ToString() causing zombie check to fail.
IgnoredTypeParam: IgnoredTypeParam : MonoBehaviour where T : MonoBehaviour, the derived classes are still scanned, and all member variables still getting scanned.
Arrays, Lists, Stacks and Dictionaries:
Events: Lambda and normal function attachment.
References: static and sub references
Most of the work was done by Stewart McCready (@StewMcc), with some help by Peter Pimley (@peter-pimley-unity).