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.authoranddescription: 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 hasmodule(blank or left out for the game's own code; Unity games usually useUnityFramework),offset(a hex string like"0x1A2B3C"or a number) andbytes(hex pairs like"1F 20 03 D5"). Optionalname. The original bytes come back when it's switched off.unity: a list of Unity method changes. Each hasclass,methodandreturn, plus optionalparams, the number of parameters, to pick one version of an overloaded method.returnis a number,trueorfalse,nullfor objects, ornothingfor methods that return nothing (which skips the method entirely).fields: a list of Unity static fields to set. Each hasclass,fieldandvalue. When switched off, the field goes back to what it was, or tooffif you give one.speed: a game speed, like2. Switching off restores the speed from before.lua: Lua code to run when switched on.luaOffruns 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. Optionalparams. Back atdefault, 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
luastring: the code runs with a variable namedvalueset 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
- 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.
- Turn each mod on and check it in the game. A mod that failed shows the reason in pink under its name.
- Close and reopen the game to check that what you left on comes back.
- 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:
100finds exactly 100. Decimals match loosely, so1.5finds 1.45 to 1.55.10~20finds anything from 10 to 20.100;250;7finds those numbers stored within 512 bytes of each other. End with::64to require that order within 64 bytes.- A type letter after a number mixes types:
Bbyte,Wword,DInt 32,QInt 64,Ffloat,Edouble. For example1.5F;20D. 0x1For1Fhis 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.typedefaults togg.TYPE_AUTO.signsupportsgg.SIGN_EQUAL,gg.SIGN_GREATER_OR_EQUALandgg.SIGN_LESS_OR_EQUAL.fromandtolimit 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_GREATERmeans it went up,gg.SIGN_FUZZY_LESSdown,gg.SIGN_FUZZY_NOT_EQUALchanged, andgg.SIGN_FUZZY_EQUALthe same. Adifferenceother than"0"means it changed by exactly that much.gg.getResultsCount()(orgg.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'svalue.gg.addListItems(items)adds items to the Saved tab. An item withfreeze = trueis frozen, andnamelabels it.gg.getListItems(),gg.removeListItems(items)andgg.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 ornil.gg.multiChoice(items, selected, title)returns a table of chosen keys set totrue, ornil.gg.prompt(labels, defaults, types)returns the answers ornil. Types arenumber,text,checkboxandspeed.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()returnstrueonce 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()returnspackageName,label,versionName,versionCode,x64,processNameandpid.gg.getRangesList(filter)lists the game's loaded modules withstart,end,nameandinternalName. Android filters likelibil2cpp.somatchUnityFramework.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 whenbodyis given) and returnscode,message,contentandheaders, 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, ornil. An empty string is the game itself.gh.modules()lists loaded modules withname,start,endandmain(true for the game itself).gh.read(address, type)reads a value (Int 32 by default).gh.write(address, value, type)writes one and returnstrueor 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, orniland 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.timesdefaults to 1; 0 repeats until stopped.gh.stopMacro()stops it,gh.macroPlaying()says whether one is playing, andgh.macros()lists the saved macro names for this game.gh.log(text)writes to the log.gh.toastandgh.sleepare the same as theggversions.gh.versionis the Game HUD version.
gh.unity works in Unity games:
gh.unity.available()istruein a Unity game.gh.unity.search(text)returns matching methods and fields, each withclass,name,type,field(true for fields),paramsandaddress. When nothing matches it returns an empty list and a reason.gh.unity.find(class, method, params)returns a method's code address, orniland a reason.gh.unity.set(class, method, value, params)makes a method returnvalueand returns an id, orniland a reason.gh.unity.unset(id)undoes it.gh.unity.field(class, field)reads a static field as text, or returnsniland a reason.gh.unity.setField(class, field, value)sets one and returnstrueor 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.