Wax

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 require

init.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.

MyMod\init.lua
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.

MyMod\mod.lua
return {
    name = "My mod",
    version = "1.2.0",
    main = "init.lua",
    dependencies = { "Greeter" },
}
FieldWhat it meansWhen left out
nameThe name shown on the Mods page.The folder name.
versionThe version shown on the Mods page."0.0.0"
mainThe file Wax runs first."init.lua"
dependenciesIds of mods that must load before this one.None.
keyThe key that shows and hides the mod's windows, such as "F6".A free key Wax picks.
keysThe 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:

mod.lua
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.
  • key is what ui.Window uses when you give it no key of its own.
  • A name in keys is the name you give ui.Bind: ui.Bind("Show or hide the pins", nil, fn) takes the key from mod.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.

NameWhat it is
gameThe root of the game: the world, the player and everything else. See The game tree.
uiWindows, overlays, notifications, hotkeys and themes. See Windows.
taskRun code alongside the game. See Tasks.
SignalMake your own events. See Signals.
print, logWrite to the log. See Printing and the log.
persist, storageKeep values across reloads and across game sessions. See Saving settings.
requireLoad another file of your mod, or another mod.
modFacts about your own mod.
rawEverything 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 folder

mod.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.png

Put shared code in its own file and return it:

MyMod\Utils.lua
local Utils = {}

function Utils.shout(text)
    return text:upper() .. "!"
end

return Utils

Load it with require. mod knows the files of your mod, so you name a file the way you see it in the folder:

MyMod\init.lua
local Utils = require(mod.Utils)
local Maths = require(mod.extras.Maths)

print(Utils.shout("hello"))   -- HELLO!
  • mod.Utils is Utils.lua. mod.extras.Maths is extras\Maths.lua.
  • A folder with an init.lua in it is loaded by the folder's name: require(mod.extras) loads extras\init.lua.
  • A file runs once. A second require of the same file gives back the same value.
  • What the file returns is what require gives 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.

Greeter\init.lua
local greeter = {}

function greeter.hello(name)
    return "Hello, " .. name .. "!"
end

return greeter

A mod that uses it does two things. It lists the id under dependencies:

MyMod\mod.lua
return {
    name = "My mod",
    dependencies = { "Greeter" },
}

And it loads the other mod with @ in front of the id:

MyMod\init.lua
local greeter = require("@Greeter")

ui.Notify(greeter.hello("explorer"))

Good to know:

  • Dependencies load first.
  • When Greeter reloads, every mod that depends on it reloads too.
  • If Greeter is missing or switched off, your mod does not load. The Mods page says which mod it needs.
  • require("@Greeter") without listing Greeter under dependencies is 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.

MyMod\init.lua
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:

whyWhen
"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.OnUnload gives 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.

BlockedUse this instead
LoopAsync, ExecuteAsync, ExecuteWithDelaytask.spawn, task.delay and task.wait
RegisterKeyBind, RegisterKeyBindAsyncui.Hotkey
RestartMod, RestartCurrentMod, UninstallMod, UninstallCurrentMod, ClearAllDelayedActionsNothing. Wax reloads mods by itself.
RegisterHook, UnregisterHookhooks.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.

On this page