unity_helper

Runtime inspection toolkit for Unity IL2CPP applications — explore classes, methods, fields, and live objects in real time.

---

✨ Overview

unity_helper is a Python toolkit for runtime inspection of Unity applications using the IL2CPP scripting backend. It provides reflection-like capabilities, allowing you to dynamically explore and interact with internal game structures directly from Python.

---

🚀 Features

• Inspect Unity assemblies (images)
• Explore classes, methods, and fields
• Call methods dynamically at runtime
• Read and modify field values
• Interact with live Unity objects (Camera, Rigidbody, etc.)
• Designed specifically for IL2CPP environments

---

⚡ Quick Start

from unity_helper import Il2cpp

ref = Il2cpp()

# Get a Unity class
time = ref.get_class_from_name(
    'UnityEngine.CoreModule.dll',
    'UnityEngine.Time'
)

print(time.name)

---

📦 Installation

pip install -U unity_helper

# optional: assembly support
pip install unity_helper[asm]

---

🧰 Requirements

• Windows (64-bit)
• Python 3.11+
• Target application using Unity IL2CPP

---

🧪 Examples

🔹 Class & Method Inspection

time = ref.get_class_from_name(
    'UnityEngine.CoreModule.dll',
    'UnityEngine.Time'
)

print('Time info:', time.cls, time.name, time.object, time.type, time.instance)

for method in time.list_methods():
    print(
        'Method info:',
        method.name,
        method.address,
        method.methodInfo,
        method.is_static,
        method.param_count
    )

---

🔹 Calling Methods

import ctypes

set_timeScale = time.find_method('set_timeScale')
set_timeScale = time.method.set_timeScale # Getting a method the lazy way

if not set_timeScale.is_static:
    time.instance = 123456789

set_timeScale(ctypes.c_float(5)) # Invoke set_timeScale with an explicit native float type
set_timeScale_m(5.0) # Invoke set_timeScale with automatic type conversion

Using ctypes directly (most consistent):

new_set_timeScale = ctypes.WINFUNCTYPE(
    ctypes.c_void_p,
    ctypes.c_float
)(set_timeScale.address)

new_set_timeScale(5.0)

---

🔹 Field Access

for field in time.list_fields():
    print('Field:', field.name, field.type, field.is_static)

example_field = time.find_field('example_field')
example_field = time.field.example_field # Getting a field the lazy way


if not example_field.is_static:
    time.instance = 123456789

example_field.value = 9999

---

🔹 Working with Unity Objects

main_cam = ref.get_mainCamera()
rigidbody = unity_helper.objects.Rigidbody(123456789)

Rigidbody

velocity = rigidbody.velocity
velocity.y = 10
rigidbody.velocity = velocity

pos = rigidbody.position
print(pos.x, pos.y, pos.z)

Camera

fov = main_cam.fov
main_cam.fov = fov + 10.0

main_cam.enabled = not main_cam.enabled
print(main_cam.name)

---

🔹 Finding Objects

player = ref.find_object('Player')
player = ref.find_object_with_tag('Player')

---

🔹 Assemblies & Classes

for image in ref.list_assemblies():
    print(image.name, image.filename)

for clazz in ref.list_classes_in_image('Assembly-CSharp.dll'):
    print(clazz.name)

---

🎯 Common Use Cases

• Runtime debugging of Unity applications
• Reverse engineering IL2CPP builds
• Building tooling and automation scripts
• Inspecting and modifying live game state
• Creating game mods

---

⚠️ Important Notes

• This is a Python script that must be executed within the game's process.
• It does not work as a standalone script and cannot interact with external processes.
• Running it outside of the game environment will not work.
• Directly calling a MonoMethod can lead to inconsistencies due to the vast number of underlying engine data types. For best results, dynamically create a WINFUNCTYPE or CFUNCTYPE wrapper and invoke it that way.

---

🔴 Known issues

• None! All known bugs have been squashed. If you run into any unexpected behavior or crashes, please feel free to open an Issue on GitHub.

---

📝 Future Roadmap / TODO

• Eliminate the pylocalmem dependency by reimplementing all required functions in memory.py using ReadProcessMemory, ensuring crash safety.
• Add obfuscation detection and implement basic name de-obfuscation. (Experimental / Tentative)

---

📄 License

MIT License