Game HUD modding reference: mod packs and Lua scripts

Write mod packs (.ghmod) and Lua scripts for Game HUD: switches, sliders and buttons, Unity edits, code patches, speed, and the full gg and gh function list.

iOS 16 – 17Tested on iOS 16.3.1 and 17.1

Game HUD's mod menu can run two kinds of mods that anyone can write and share: mod packs, short .ghmod text files of switches, sliders and buttons for one game, and Lua scripts that use the same gg functions as GameGuardian, plus gh functions for iOS. This page covers both. For using the menu itself, see the Game HUD guide.

Note: Mods only change what a game keeps on your iPhone. Coins, gems and purchases in online games live on the game's servers and can't be changed, and changing an online game can get your account banned. Write and share mods for offline games.

Before you start

  • Game HUD 1.4.0 or later, with Mods opened at least once in the game so the menu knows it. See Set it up.
  • The game's bundle ID, like com.example.game. In the menu, ⋯ → Copy Example Mod Pack gives you a starting pack with it already filled in.
  • For Unity mods, the class and method names. Find them on the Unity tab: search a word like Coins, tap a method and choose Copy as Mod Pack Entry.
  • For code patches, the module, offset and bytes for the exact game version you have.

Where mods live

Each game has its own folder:

/var/jb/var/mobile/Library/GameHUD/Mods/<bundle ID>/

.ghmod files there show up on the Mods tab, .lua files on the Lua tab, and .dylib files under Mod Files. Copy Folder on the Mods tab copies the path, and Filza can open it. You don't have to use the folder: Paste Mod and Paste Script save what's on the clipboard there for you.

Paste Mod accepts the text of a pack, the text of a Lua script, or an https link to either. A link must return the raw text (under 4 MB), so link to the raw file, not a web page around it.

Write a mod pack

A pack is a JSON object. This one has one of each kind of mod:

{
  "name": "Sky Dash mods",
  "author": "you",
  "description": "Lives, damage and speed for Sky Dash.",
  "game": "com.example.skydash",
  "gameVersion": "2.4.1",
  "mods": [
    {
      "name": "Infinite lives",
      "description": "Lives never go down.",
      "unity": [ { "class": "PlayerStats", "method": "get_Lives", "params": 0, "return": "99" } ]
    },
    {
      "name": "No damage",
      "patches": [ { "module": "UnityFramework", "offset": "0x1A2B3C", "bytes": "00 00 80 52 C0 03 5F D6" } ]
    },
    {
      "name": "Game speed",
      "type": "slider",
      "min": 0.5, "max": 3, "step": 0.25, "default": 1,
      "target": "speed"
    },
    {
      "name": "Fill coins",
      "type": "button",
      "fields": [ { "class": "Bank", "field": "coins", "value": "50000" } ]
    }
  ]
}

Pack fields

  • name: shown as the pack's title and used as its file name.
  • author and description: optional, shown under the title.
  • game: the bundle ID the pack is for. A pack for a different game can't be switched on. Leave it out only for packs that work in any game.
  • gameVersion: optional. When it doesn't match the installed version, the pack still works but shows a warning, because code patches usually move between versions. Unity mods usually keep working.
  • mods: the list of switches, sliders and buttons, in the order they appear.

Every mod has a name (unique within the pack) and an optional description. Game HUD remembers what you switched on by name, so renaming a mod resets it.

Switches

A mod without a type, or with "type": "toggle", is a switch. Turning it on does everything listed; turning it off puts it all back. A switch left on applies again every time the game opens. It can combine any of these:

  • patches: a list of code patches. Each has module (blank or left out for the game's own code; Unity games usually use UnityFramework), offset (a hex string like "0x1A2B3C" or a number) and bytes (hex pairs like "1F 20 03 D5"). Optional name. The original bytes come back when it's switched off.
  • unity: a list of Unity method changes. Each has class, method and return, plus optional params, the number of parameters, to pick one version of an overloaded method. return is a number, true or false, null for objects, or nothing for methods that return nothing (which skips the method entirely).
  • fields: a list of Unity static fields to set. Each has class, field and value. When switched off, the field goes back to what it was, or to off if you give one.
  • speed: a game speed, like 2. Switching off restores the speed from before.
  • lua: Lua code to run when switched on. luaOff runs when switched off.

If a patch or Unity change fails, for example a method that doesn't exist in this version, the switch's other patches and Unity changes are taken back too, and the switch shows why.

Sliders

"type": "slider" with min, max, step (0 for smooth) and default. Moving the slider sends its value to one target:

  • "target": "speed": the game speed. Shown with a × after the number.
  • "target": { "class": "Player", "method": "get_MaxHealth" }: the method returns the slider's value. Optional params. Back at default, the method goes back to normal.
  • "target": { "class": "Bank", "field": "coins" }: the static field is set to the slider's value.
  • No target and a lua string: the code runs with a variable named value set to the slider's value.

A slider only acts once you move it. After that, its value applies again each time the game opens, until you move it back to default or tap Switch Everything Off.

Buttons

"type": "button" runs once each time it's tapped. Give it fields to set static fields, lua to run code, or both. Buttons are good for one-off actions like "fill coins" or a script that asks what to change.

Unity class names

Use the class name as the Unity tab shows it. A bare name like Bank works when only one class has that name. Add the namespace to be exact, like Game.Economy.Bank, and use / for nested classes, like Game.Player/Stats. Property getters are methods named get_ plus the property, like get_Coins.

Unity mods wait for the game's Unity engine to start, so they may apply a second or two after the game opens.

Test and share a pack

  1. Copy the pack's text, open the game, and tap Paste Mod on the Mods tab. Pasting a pack with the same name replaces the old one.
  2. Turn each mod on and check it in the game. A mod that failed shows the reason in pink under its name.
  3. Close and reopen the game to check that what you left on comes back.
  4. Share the text, or host the raw file and share the link.

Tap Share Mine to start a pack from what you've already done: it turns your own patches and Unity changes for this game into a pack, with the game and version filled in.

Write a Lua script

Scripts run Lua 5.4 on their own thread inside the game, so dialogs and gg.sleep never freeze the game. Open the Lua tab, tap New Script, and tap Check to find mistakes before you Save. Tap Run to start a script and Stop Script to end it. print writes to the log under the scripts.

This script asks for your coins and changes them, the same pattern as most GameGuardian scripts:

local r = gg.prompt({'Coins you have now', 'Coins you want'}, nil, {'number', 'number'})
if not r then return end
-- With results left over from last time, this narrows them down.
gg.searchNumber(r[1], gg.TYPE_DWORD)
local n = gg.getResultsCount()
if n == 0 then
  gg.clearResults()
  gg.alert('Nothing found. Try a different number.')
elseif n > 50 then
  gg.alert(n .. ' matches. Spend some coins, then run it again with the new number.')
else
  gg.editAll(r[2], gg.TYPE_DWORD)
  gg.toast('Changed ' .. n .. ' values')
  gg.clearResults()
end

Code patches and Unity changes a script makes stay in place after it finishes, until you tap Undo Changes on the Lua tab or the game closes. Values written with gg.editAll or gg.setValues are ordinary memory writes and stay until the game changes them.

Search text

gg.searchNumber, gg.refineNumber and the Search box understand the same text:

  • 100 finds exactly 100. Decimals match loosely, so 1.5 finds 1.45 to 1.55.
  • 10~20 finds anything from 10 to 20.
  • 100;250;7 finds those numbers stored within 512 bytes of each other. End with ::64 to require that order within 64 bytes.
  • A type letter after a number mixes types: B byte, W word, D Int 32, Q Int 64, F float, E double. For example 1.5F;20D.
  • 0x1F or 1Fh is hexadecimal.

gg functions

Searching:

  • gg.searchNumber(text, type, encrypted, sign, from, to): searches the game's memory. If results already exist, it narrows them instead, like GameGuardian. type defaults to gg.TYPE_AUTO. sign supports gg.SIGN_EQUAL, gg.SIGN_GREATER_OR_EQUAL and gg.SIGN_LESS_OR_EQUAL. from and to limit results to an address range. Encrypted (TYPE_XOR) searches aren't supported.
  • gg.refineNumber(text, type, encrypted, sign, from, to): narrows the current results.
  • gg.startFuzzy(type): starts an unknown-value search.
  • gg.searchFuzzy(difference, sign): narrows an unknown-value search. gg.SIGN_FUZZY_GREATER means it went up, gg.SIGN_FUZZY_LESS down, gg.SIGN_FUZZY_NOT_EQUAL changed, and gg.SIGN_FUZZY_EQUAL the same. A difference other than "0" means it changed by exactly that much.
  • gg.getResultsCount() (or gg.getResultCount()), gg.getResults(max, skip), gg.clearResults(), gg.loadResults(items), gg.removeResults(items).

Results are tables with address, value and flags (the type), the same shape GameGuardian uses. gg.getResults returns an empty list while an unknown-value search hasn't been narrowed yet.

Editing and the Saved tab:

  • gg.editAll(value, type): writes one value to every result and returns how many were written. It refuses to run on an unknown-value search that hasn't been narrowed.
  • gg.getValues(items) reads fresh values; gg.setValues(items) writes each item's value.
  • gg.addListItems(items) adds items to the Saved tab. An item with freeze = true is frozen, and name labels it. gg.getListItems(), gg.removeListItems(items) and gg.clearList() work on the same list.

Dialogs and the menu:

  • gg.alert(text, positive, negative, neutral) returns 1, 2 or 3 for the button tapped. Every script dialog also has a Stop Script button.
  • gg.choice(items, selected, title) returns the chosen key or nil. gg.multiChoice(items, selected, title) returns a table of chosen keys set to true, or nil.
  • gg.prompt(labels, defaults, types) returns the answers or nil. Types are number, text, checkbox and speed.
  • gg.toast(text) shows a short message over the game.
  • gg.isVisible(), gg.setVisible(visible) check and show or hide the mod menu.
  • gg.showUiButton(), gg.hideUiButton(), gg.isClickedUiButton(): a floating script button the player can tap while the script loops. gg.isClickedUiButton() returns true once per tap.
  • gg.sleep(ms) waits without freezing the game.

Game and system:

  • gg.setSpeed(speed), gg.getSpeed(): game speed, from 0.1 to 10.
  • gg.getTargetPackage() returns the bundle ID. gg.getTargetInfo() returns packageName, label, versionName, versionCode, x64, processName and pid.
  • gg.getRangesList(filter) lists the game's loaded modules with start, end, name and internalName. Android filters like libil2cpp.so match UnityFramework.
  • gg.getRanges(), gg.setRanges(ranges) are accepted for compatibility. Game HUD always searches the game's writable memory.
  • gg.copyText(text), gg.getFile(), gg.getLine(), gg.getLocale(), gg.bytes(text).
  • gg.makeRequest(url, headers, body) fetches a URL (a POST when body is given) and returns code, message, content and headers, or an error message.
  • os.exit() ends the script quietly.

Accepted but do nothing on iOS: gg.processPause, gg.processResume, gg.processToggle, gg.skipRestoreState, gg.gotoAddress, gg.clearHistory and gg.require. gg.isProcessPaused() always returns false.

Not available on iOS (they return the message "Not available on iOS."): gg.processKill, gg.timeJump, gg.searchAddress, gg.dumpMemory, gg.allocatePage, gg.saveList and gg.loadList.

The usual constants are there: gg.TYPE_BYTE, gg.TYPE_WORD, gg.TYPE_DWORD, gg.TYPE_QWORD, gg.TYPE_FLOAT, gg.TYPE_DOUBLE, gg.TYPE_AUTO, every gg.REGION_ and gg.SIGN_ value, gg.VERSION, gg.PACKAGE, gg.CACHE_DIR, gg.FILES_DIR and gg.EXT_STORAGE.

Like GameGuardian, functions that can fail return true on success or an error message as a string, so check with if ok ~= true then gg.alert(ok) end.

gh functions

gh adds what iOS games need. Addresses are plain Lua integers.

  • gh.base(module) returns where a module starts in memory, or nil. An empty string is the game itself.
  • gh.modules() lists loaded modules with name, start, end and main (true for the game itself).
  • gh.read(address, type) reads a value (Int 32 by default). gh.write(address, value, type) writes one and returns true or an error message.
  • gh.readBytes(address, count) returns hex like "1F 20 03 D5". gh.writeBytes(address, hex) writes them.
  • gh.patch(module, offset, bytes, name) patches code and returns an id, or nil and an error. gh.unpatch(id) puts the original code back.
  • gh.speed(speed) sets the game speed and returns it; gh.speed() just returns it.
  • gh.playMacro(name, times) plays a macro from the Macros tab and returns at once, so the script keeps running while it plays. times defaults to 1; 0 repeats until stopped. gh.stopMacro() stops it, gh.macroPlaying() says whether one is playing, and gh.macros() lists the saved macro names for this game.
  • gh.log(text) writes to the log. gh.toast and gh.sleep are the same as the gg versions. gh.version is the Game HUD version.

gh.unity works in Unity games:

  • gh.unity.available() is true in a Unity game.
  • gh.unity.search(text) returns matching methods and fields, each with class, name, type, field (true for fields), params and address. When nothing matches it returns an empty list and a reason.
  • gh.unity.find(class, method, params) returns a method's code address, or nil and a reason.
  • gh.unity.set(class, method, value, params) makes a method return value and returns an id, or nil and a reason. gh.unity.unset(id) undoes it.
  • gh.unity.field(class, field) reads a static field as text, or returns nil and a reason. gh.unity.setField(class, field, value) sets one and returns true or an error message.
if not gh.unity.available() then return gg.alert('Not a Unity game.') end
local id, err = gh.unity.set('Player', 'get_MaxHealth', '9999', 0)
if not id then return gg.alert(err) end
gg.toast('Max health is now 9999')

Troubleshooting

Paste Mod says the text isn't a mod pack or a Lua script

Packs must be valid JSON with a mods list. A trailing comma or a missing quote is the usual cause; paste the text into a JSON checker. For scripts, the message includes Lua's own error and line number.

A Unity mod says the class or method wasn't found

Search for it on the Unity tab to see the exact spelling and namespace. Names are case-sensitive, and an update to the game can rename or remove them. If a method has several versions, add params.

A code patch says the offset is outside the module, or the bytes didn't stick

The offset or module is wrong for this version of the game, or the game protects that part of its code. Patches are tied to one exact build, which is why gameVersion is worth filling in.

My script waits forever

A script stuck in a loop or waiting on a dialog can always be ended with Stop Script. Loops that call gg.sleep or any gg function stop right away; a tight loop of plain Lua stops within a moment.

Questions

Can I use my GameGuardian scripts?

Many work as they are, especially ones that search, refine and edit numbers and use the standard dialogs. Scripts that depend on Android memory regions, encrypted (XOR) values, or Android-only functions like gg.timeJump need changes.

Can a mod pack run code on my iPhone?

A pack can run Lua inside the game it's made for, patch that game's code and change its values. It can't reach other apps. Only add packs, scripts and .dylib files from people you trust, because they run with full access to that game.

Do mods stay on after the game updates?

Switches and moved sliders try again each launch. Unity mods usually survive updates. Code patches usually don't, and show an error until someone updates the pack for the new version.