How a mod is built
The files in a mod, mod.lua, splitting code into files and using another mod.
A mod is a folder. The folder name is the mod's id.
Wax\mods\
MyMod\
init.lua the code that runs
mod.lua optional: name, version, dependencies
helpers.lua optional: more code, loaded with requireinit.lua
Wax runs init.lua from top to bottom when the mod loads. It runs it again, from the top, each time the mod
reloads.
print("My mod is loading.")
local window = ui.Window({ title = "My mod" })
window:Label("Hello.")mod.lua
mod.lua describes your mod. It is called the manifest. The file is optional, and so is every field in it.
return {
name = "My mod",
version = "1.2.0",
main = "init.lua",
dependencies = { "Greeter" },
}| Field | What it means | When left out |
|---|---|---|
name | The name shown on the Mods page. | The folder name. |
version | The version shown on the Mods page. | "0.0.0" |
main | The file Wax runs first. | "init.lua" |
dependencies | Ids of mods that must load before this one. | None. |
key | The key that shows and hides the mod's windows, such as "F6". | A free key Wax picks. |
keys | The mod's other keys, one line each: "F10: Show or hide the pins". | None. |
mod.lua may only hold plain values like the ones above. It cannot call functions.
Keys
A mod that makes a window names the key that shows it, and a mod that makes a panel or has other keys names those:
return {
id = "MapMarkers",
name = "Map Markers",
version = "1.2.0",
key = "F6", -- shows and hides the mod's windows
keys = { "F10: Show or hide the pins" }, -- one line for each key made with ui.Bind: the key, a colon, its name
}- Wax reads these before the mod runs, so the keys are on the mod's card of the Mods page while the mod is still switched off, and a clash with another mod's key is said before the player switches it on.
keyis whatui.Windowuses when you give it nokeyof its own.- A name in
keysis the name you giveui.Bind:ui.Bind("Show or hide the pins", nil, fn)takes the key frommod.lua. - The player can change every one of them on the card. Their choice is kept.
A mod you publish must name a key when it has a window or a panel.
What every mod can use
These names are ready in every file of your mod. You don't load them.
| Name | What it is |
|---|---|
game | The root of the game: the world, the player and everything else. See The game tree. |
ui | Windows, overlays, notifications, hotkeys and themes. See Windows. |
task | Run code alongside the game. See Tasks. |
Signal | Make your own events. See Signals. |
print, log | Write to the log. See Printing and the log. |
persist, storage | Keep values across reloads and across game sessions. See Saving settings. |
require | Load another file of your mod, or another mod. |
mod | Facts about your own mod. |
raw | Everything UE4SS offers, with no safety checks. For experts. |
Lua's own tools (string, table, math, pairs, ipairs, tostring and the rest) work as usual.
The mod table
print(mod.id) -- the folder name, for example "MyMod"
print(mod.name) -- the name from mod.lua
print(mod.version) -- the version from mod.lua
print(mod.dir) -- the path of the mod's foldermod.OnUnload(fn) runs a function just before your mod unloads. See When your mod unloads.
mod.Reload() loads your mod again at the start of the next frame, as saving one of its files does. Use it
when something your mod worked out at load has changed, such as the size of the screen:
ui.ScreenChanged:Connect(function()
mod.Reload()
end)Each mod has its own globals
A global variable you set in one mod is not seen by other mods. Two mods can both use the name settings
without clashing.
More than one file
A mod is a folder, and you can lay it out as you like. init.lua stays at the top. Other files go beside it or
in folders of their own.
MyMod\
mod.lua
init.lua
Utils.lua
extras\
Maths.lua
assets\
logo.pngPut shared code in its own file and return it:
local Utils = {}
function Utils.shout(text)
return text:upper() .. "!"
end
return UtilsLoad it with require. mod knows the files of your mod, so you name a file the way you see it in the folder:
local Utils = require(mod.Utils)
local Maths = require(mod.extras.Maths)
print(Utils.shout("hello")) -- HELLO!mod.UtilsisUtils.lua.mod.extras.Mathsisextras\Maths.lua.- A folder with an
init.luain it is loaded by the folder's name:require(mod.extras)loadsextras\init.lua. - A file runs once. A second
requireof the same file gives back the same value. - What the file returns is what
requiregives you. - In VS Code,
mod.lists your files and folders, and what a file returns completes too.
The name in quotes works as well, with dots for folders: require("Utils"), require("extras.Maths"). You need
that form for a file whose name has a dash in it, or is called id, name, version, dir, Reload or
OnUnload.
Saving any .lua file of the mod reloads the whole mod.
Pictures and other files
Keep them in the mod's folder, for example in assets. mod.dir is the path of your mod's folder, so a file in
it is mod.dir .. "/assets/logo.png".
ui.Icons.Register("mymod-logo", mod.dir .. "/assets/logo.png")
local window = ui.Window({ title = "My mod", icon = "mymod-logo" })
window:Icon("mymod-logo", { size = 64 })A registered picture is used by its name anywhere an icon name is taken. Use a PNG. Give the name a prefix of your own so it does not clash with another mod's.
Using another mod
One mod can offer functions to others. What its init.lua returns is what other mods get.
local greeter = {}
function greeter.hello(name)
return "Hello, " .. name .. "!"
end
return greeterA mod that uses it does two things. It lists the id under dependencies:
return {
name = "My mod",
dependencies = { "Greeter" },
}And it loads the other mod with @ in front of the id:
local greeter = require("@Greeter")
ui.Notify(greeter.hello("explorer"))Good to know:
- Dependencies load first.
- When
Greeterreloads, every mod that depends on it reloads too. - If
Greeteris missing or switched off, your mod does not load. The Mods page says which mod it needs. require("@Greeter")without listingGreeterunderdependenciesis an error. The message tells you what to add.
Wax cleans up after you
Everything a mod sets up belongs to that mod: its windows, overlays, hotkeys, tasks and signal connections. When the mod reloads or is switched off, Wax removes all of it. You don't write clean-up code.
Changes to the game's tables go back the same way. What you change in the world itself does not: for that, see the next section.
When your mod unloads
Some things Wax cannot undo for you: a value you wrote on the character, slots you added to an inventory,
anything else you changed in the world. mod.OnUnload runs a function of yours just before the mod goes, so
you can put them back.
local character = game.Character
if character then character:Set("JumpMaxCount", 3) end
mod.OnUnload(function(why)
local now = game.Character
if now then now:Set("JumpMaxCount", 1) end
end)Your function gets one value that says why the mod unloads:
why | When |
|---|---|
"reload" | The mod loads again straight after, because a file was saved or mod.Reload() was called. |
"off" | The player switched the mod off. |
"removed" | The mod's folder was removed. |
"failed" | The mod raised an error while it was loading. What it set up before the error is still undone. |
"shutdown" | Wax itself stops. |
Good to know:
- It runs before anything of the mod is taken away. Your windows, tasks, connections and table changes are
all still there, so
game.Data:Changes()still tells what a field was. - Several functions run newest first. One that raises an error is logged, and the others still run.
- The function must return at once. It cannot wait.
- It does not run when the game closes, and not on a map change. A mod stays loaded across maps.
mod.OnUnloadgives back a function. Call it to take your function off again.- When the mod only reloads, you can often skip the work: check for
why == "reload"and let the new load put things right.
Functions that are blocked
A few UE4SS functions are switched off inside Wax mods, because they break the game's Lua state. Calling one raises an error that says why.
| Blocked | Use this instead |
|---|---|
LoopAsync, ExecuteAsync, ExecuteWithDelay | task.spawn, task.delay and task.wait |
RegisterKeyBind, RegisterKeyBindAsync | ui.Hotkey |
RestartMod, RestartCurrentMod, UninstallMod, UninstallCurrentMod, ClearAllDelayedActions | Nothing. Wax reloads mods by itself. |
RegisterHook, UnregisterHook | hooks.listen |
The originals are still reachable through raw, for example raw.LoopAsync. They can crash the game.
RegisterHook is blocked for another reason: it hands your code the game's own arrays, and a write into one
of them crashed a dedicated server. hooks.listen hands you views you can read and a return value you can
set. A mod that reaches raw.RegisterHook all the same is told so in the log, once per file, when it loads.
The full list with reasons is in the reference.
Sharing your mod
To give a mod to a friend, zip its folder. They extract it into their own Wax\mods\ folder.
To put it on the Mods page for every player, see Publish a mod. A published
mod needs a few more fields in mod.lua, and that page lists them.