razchek / unispect

A mono type definition and field inspector for Unity games compiled with mono.

Development on hold until I decide to pick it up again. :) Should work as is, leave an issue if not. Glhf!

Unispect

Unispect is a mono type definition and field inspector targeting Unity games compiled with mono. It does so by accessing the remote process's memory.

The design choice of accessing the process memory to gather the definitions was made with the intention of being able to access the run-time type definitions as well as accurate field definition information.

Download

Head over to the releases page.

Features

• Display type definitions from classes, structures, interfaces and enums
• Display field definitions including offsets, types and static values *¹
• Automatic deobfuscation of obfuscated names *²
• Save definitions to a formatted document for manual digestion
• Save definitions into a shareable database which can then be loaded back into Unispect anytime
• Plugin interface for custom memory access implementations
• Track types in more detail in the inspector by simply clicking on the base or extended type
• Fast definition collection. Only a few seconds even when using the native memory implementation.
• Drag & drop definitions from the Type Definition Inspector into apps like Notepad++, Chrome, etc *³

*¹ Static values are still being implemented

*² The deobfuscated names should match between users. I need collaborative results to validate this.

*³ The standard notepad only accepts files, I did not want to create a temporary file (or otherwise) to accomodate for that.

Drag & Drop

From the Type Inspector view (see below) simply click and drag a Type Definition or Field Definition into your desired application's text input box. That action will produce either:

Type Definition output:
[Class] BehaviourMachine.ObjectRandom : ActionNode
    [00][S] onNodeTick : System.Action<ActionNode>
    [10] m_Status : System.Int32
    [18] m_Branch : BehaviourMachine.BranchNode
    [20] m_Self : UnityEngine.GameObject
    [28] m_Owner : BehaviourMachine.INodeOwner
    [30] instanceID : Int32
    [38] name : String
    [40] objects : BehaviourMachine.ObjectVar[]
    [48] storeObject : BehaviourMachine.ObjectVar

Field Definition output:
BehaviourMachine.ObjectRandom->m_Branch // Offset: 0x0018 (Type: BehaviourMachine.BranchNode)

Planned features (these aren't definite, but likely):

• The ability to drag desired type hierarchies into a project view
• Save project state so you can review the information at a later time
• Export a .NET Framework dynamic link library using the project information
• Changes to the application interface, more UI elements to make swift browsing more accessible

Current Limitations & Thoughts

• Currently only tested on Unity 2018 and Unity 2019 builds. When I push the Assembly Export feature, I will also convert the static structures used to read all of the remote information into dynamic structures and allow the offsets to be customized with a JSON file. This will allow Unispect to target a broader spectrum of Unity versions.

• Currently only games using mono bleeding edge (mono-2.0-bdwgc) are supported. Standard mono is in the scope of this project and will be looked at in the near future.

• Only works with Unity Scripting Backend: Mono. IL2CPP may be supported in the future.

• Only works with x64 systems and software. I might (unlikely) add support for x32 in the future.

• Static, constant and enum values are not shown. Still figuring those out.

• Method definitions are not collected. This is intentional, but I may implement it in the future with good reason.

• You can only view a type definition from another MonoImage if it's the parent of one from the current MonoImage.

  (I will probably change the code to iterate over all modules and collect all information in the future)

• Unispect's 'Deobfuscation' only targets the most common obfuscation seen on Unity's managed assemblies.

Check out the issues tab for more.

Tech

Unispect uses these projects (or plans to):

• MahApps.Metro - A toolkit for creating modern WPF applications. Lots of goodness out-of-the box.
• Fody.Costura - Merges IL assemblies together, makes things more portable!
• [DynamicStructs] (Currently Private) - A dynamic struct generator written by me. :)

Installation

Unispect requires the .NET Framework v4.8 or higher to be installed in order to run. I currently have no plans on porting it to other frameworks or platforms.

Example file output (small snippet):

[Class] GPUInstancer.SpaceshipMobileController : MonoBehaviour
    [00][S] OffsetOfInstanceIDInCPlusPlusObject : Int32     // Static fields are marked with [S]
    [00][C] objectIsNullMessage : String                    // Constant fields are marked with [C]
    [00][C] cloneDestroyedMessage : String
    [10] m_CachedPtr : IntPtr
    [18] spaceShipJoystick : GPUInstancer.SpaceshipMobileJoystick
    [20] rigidbody_0x20 : UnityEngine.Rigidbody             // Deobfuscated fields are named like this
    [28] emissionModule_0x28 : -.ParticleSystem.EmissionModule
    [30] emissionModule_0x30 : -.ParticleSystem.EmissionModule
    [38] light_0x38 : UnityEngine.Light
    [40] engineTorque : Single
    [44] enginePower : Single
    [48] single_0x48 : Single
    [4C] single_0x4C : Single
    [50] single_0x50 : Single
    [54] single_0x54 : Single
    [58] single_0x58 : Single
    [5C] single_0x5C : Single
[Class] GPUInstancer.SpaceshipMobileJoystick : MonoBehaviour, IPointerDownHandler, IEventSystemHandler, IPointerUpHandler, IDragHandler
    [00][S] OffsetOfInstanceIDInCPlusPlusObject : Int32
    [00][C] objectIsNullMessage : String
    [00][C] cloneDestroyedMessage : String
    [10] m_CachedPtr : IntPtr
    [18] image_0x18 : UnityEngine.UI.Image
    [20] image_0x20 : UnityEngine.UI.Image
    [28] inputDirection : UnityEngine.Vector3
    [34] vector2_0x34 : UnityEngine.Vector2

Plugins

• Start a new Class Library (.NET Framework) project and replace your starting code with the code from MemoryPluginTemplate.cs
• Add a reference to Unispect.exe (Project > Add Reference... > Browse)
• Change your Build Platform target to x64
• Edit the code to your hearts content
• Compile the class library and place the .dll into Unispect's plugins folder (Unispect\Plugins)
• Open Unispect and click "Load Plugin". Look for your class name and then select it by clicking on it.

Build

• Visual Studio 2019: Build > Build Solution (F6)
• Visual Studio 2017: Remove the 'Fody.Costura' NuGet package then Build > Build Solution (F6)

Support

Contribute? Nice! Fork and request a pull. Or feel free to buy me a coffee!

Before requesting a pull, be sure to test the target changes. If the testing fails, feel free to create an issue instead.

License

---

All code, NuGets and binaries are under the MIT License (MIT)

unispect's Issues

Obfuscated generics do not show their parameter types

Current:
GClassABF0 : Parent, Extends
SomeField : GClassABF0 Fields were fixed with commit d5089ca

Expected:
GClassABF0<SomeType, ...> : Parent, Extends
SomeField : GClassABF0<SomeType, ...> Fields were fixed with commit d5089ca

Unknown field names from fields of generic types use the type cast expression.

Current:
type<Int32, SomeClass, Int64>_0x0 : Type<Int32, SomeClass, Int64>

Expected:
type_0x0

Unispect dumps only classes without fields

Can be reproduced only on ReviOS (21H1), official windows versions works fine. vc++ redist and .net framework is installed.
Handle: EscapeFromTarkov (mod: Assembly-CSharp)

Expected:

[Class] -.DebugRotateNode : ActionNode
    [00][S] onNodeTick : System.Action<ActionNode>
    ... other fields

Current:

[Class] -.DebugRotateNode : ActionNode
[Class] - // other class

The standard mono module is sometimes used and may require support.

Discussed here: #1 (comment)

While Unispect currently supports Mono Bleeding Edge, some games ship with a standard mono module with different structures.

This needs to be researched further to add support.

In the meantime if anyone finds a game made with Unity 2018 or later that uses the standard mono module (mono.dll instead of mono-2.0-bdwgc.dll) then please let me know.

ValueType class fields are offset by +0x10 unless they're static

I need to perform some more validation tests, but this seems to be the case so far.
There does not seem to be any mention of this in the mono bleeding edge source code.

Perhaps I just do not clearly understand the type structure for ValueType type definitions in memory.

Enum Types are listed as their base type in field definitions.

As the title suggests.

Current:
[00] SomeEnum : System.Int32

Expected:
[00] SomeEnum : TheEnumType

Constants and enum values come up as fields with a zero offset

This is partially expected behavior, however I need to define the value of the constants and enum values, then format the views appropriately.

Current:
[00] SomeConstantField : SomeType
[00] EnumEntryName : SomeType

Expected:
[Constant] SomeConstantField = Value : SomeType
[EnumValue] EnumEntryName = Value : SomeType