unity-helper 1.2.4

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

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

---

🧰 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')

if not set_timeScale.is_static:
    time.instance = 123456789

set_timeScale(ctypes.c_float(5))

Using ctypes directly:

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')

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)

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.

---

🔴 Known issues

• Accessing the scene property on a GameObject returns an invalid scene object
• Calling a method via the built in call can lead to unexpected behavior sometimes

--

📝 TODO

• Add functions to dump image data at runtime, similar to the Il2CppDumper tool.

📄 License

MIT License