Il2CppGG Usage Guide (il2cpp analysis, editing, hooking, dumping, etc.)

[VieGG]

-- Il2CppGG by LeThi9GG
require("Il2CppGG")

-- Usage Instructions:
-- This script demonstrates the core functionalities of Il2CppGG, a Lua-based toolkit for inspecting and manipulating Il2Cpp structures in GameGuardian.
-- It covers image retrieval, class searching, method and field access, value modification, class dumping, and memory hooking.
-- Prerequisites: Ensure GameGuardian is running and the target application uses Il2Cpp. Load this script in GameGuardian for execution.
-- Note: Addresses and values are examples; adapt them to your specific game or application.
-- For detailed API documentation, refer to the project's README.md or wiki.

-- Example: Retrieve Image by Name
-- Description: Fetches an Il2Cpp image (assembly) by its name. Use Il2Cpp.Image() without arguments to get all images.
local Assembly = Il2Cpp.Image("Assembly-CSharp")  -- Retrieves the "Assembly-CSharp" assembly.

-- Example: Find Class within an Image
-- Description: Searches for a class in the specified image using namespace and class name. Namespace can be nil for root-level classes.
local PlayerScript = Assembly:Class(nil, "PlayerScript")  -- Parameters: (namespace, classname)

-- Alternative: Find Class by Name, Address, or Index
-- Description: Directly searches for a class by name (recommended to use GetIndex() for performance optimization).
--local PlayerScript = Il2Cpp.Class("PlayerScript")
--print(PlayerScript:GetIndex())  -- Outputs the class index for faster future access.

-- Example: Find Methods in a Class
-- Description: Retrieves a specific method by name or lists all methods with GetMethods().
local LateUpdate = PlayerScript:GetMethod("LateUpdate")  -- Finds the "LateUpdate" method.
local addPoints = PlayerScript:GetMethod("addPoints")    -- Finds the "addPoints" method.

-- Example: Find Fields in a Class
-- Description: Retrieves a specific field by name or lists all fields with GetFields().
local points = PlayerScript:GetField("points")  -- Finds the "points" field.

-- Alternative: Find Field by Name or Address
-- Description: Global search for a field by name or direct address.
--local points = Il2Cpp.Field("points")  -- Searches globally by name.

-- Alternative: Find Method by Name or Address
-- Description: Global search for a method by name or direct address.
--local AddPoints = Il2Cpp.Method("AddPoints")  -- Searches globally by name.

-- Example: Modify a Field Value
-- Description: Locates an instance of the class and sets a new value for the field.
local obj = PlayerScript:GetInstance()  -- Retrieves instances of the class.
points:SetValue(obj, 1000)              -- Sets the "points" field to 1000 in the instance.

-- Example: Dump Class to C# Format
-- Description: Outputs the class structure in C# syntax for reverse engineering purposes.
--print(PlayerScript:Dump())  -- Dumps the class definition, including fields, methods, and offsets.

-- Hooking Examples
-- Description: Demonstrates memory hooking for real-time modifications using the Hook module.
-- Hooks allow intercepting and altering method calls, parameters, and fields.

-- Hook a Field via a Method (e.g., hook "points" field using "LateUpdate" method)
-- Description: Modifies the field value every time the method is called.
local _LateUpdate = LateUpdate:field()                        -- Initializes hook on the method for field modification.
_LateUpdate:setValues({{offset = points.offset, flags = "int", value = 9999}})  -- Sets the field to 9999.
gg.sleep(10000)                                               -- Pauses for 10 seconds to observe the effect.
_LateUpdate:off()                                             -- Disables the hook and restores original behavior.

-- Hook Parameters of a Method (e.g., hook parameters of "addPoints")
-- Description: Alters the parameter values passed to the method.
local _addPoints = addPoints:method()                         -- Initializes hook on the method for parameter modification.
_addPoints:param({{param = 1, flags = "int", value = 999999}})  -- Sets the first parameter to 999999.
gg.sleep(10000)                                               -- Pauses for 10 seconds.
_addPoints:off()                                              -- Disables the hook.

-- Hook a Method Call (e.g., call "addPoints" from "LateUpdate")
-- Description: Injects a call to another method with custom parameters during execution.
local _addPoints = LateUpdate:call()(addPoints)               -- Initializes hook to call "addPoints" from "LateUpdate".
_addPoints:setValues({{param = 1, flags = "int", value = 999}})  -- Sets the parameter for the called method.
gg.sleep(10000)                                               -- Pauses for 10 seconds.
_addPoints:off()                                              -- Disables the hook.

Il2CppGG

Telegram

Youtube

[Aname_Maralen]

Looks pretty powerful you’ve got everything for Il2Cpp work: class lookup, dumping, field edits, and hooking. Personally, I’d say it’s great for learning and reverse-engineering, but I’d be careful using it on live games because of the legal and ethical side.

[kurutokaizu]

how this work? 

[VieGG]

On 9/23/2025 at 11:44 PM, kurutokaizu said:

how this work? 

In Github

[VieGG]

Video test

[VieGG]

Update

- Support metadata obfuscator

- Dumper all class

- Patch method

 

Input:

require("Il2CppGG")
Il2Cpp()

Method:

— auto select type (int, bool, float, double) or pointer

local method = Il2Cpp.Method("methodName")

method:SetValue(999)
--off
method:RestoreValue()

Dumper:

— If path is nill then it will automatically create path according to game info
— Default image is all, or optional image e.g. {Il2Cpp.Image("Assembly-CSharp")}

--[[
-- one
local klass = Il2Cpp.Class("Camera")
print(klass:Dump())
]]

-- all
Il2Cpp:Dumper({
    DumpField = true,
    DumpProperty = true,
    DumpMethod = true,
    DumpFieldOffset = true,
    DumpMethodOffset = true,
    DumpTypeDefIndex = false,
}, {
    path = nil,
    image = nil
})