Mods
What every mod has: mod, log, print, persist, storage, require and raw.
The Explorer searches everything on this page, and the classes of the game too.
mod
What a mod knows about itself. Every Lua file and folder of the mod is a field too: mod.Utils is Utils.lua and mod.extras.Utils is extras/Utils.lua. A file called id, name, version, dir, Reload, OnUnload or Content has to be required by its name instead.
Type name: WaxModInfo.
| Member | Type | Description |
|---|---|---|
id | string | The mod's folder name. |
name | string | |
version | string | |
dir | string | Path of the mod's folder. |
Reload | fun() | Loads the mod again at the start of the next frame, as a saved file does. |
side | "host" | "client" | "both" | Where the mod runs, as its mod.lua says ("both" when it says nothing). |
Side | fun(side?: "host"|"client"|"both"): boolean | Whether a feature of that side can work on this game: "host" is true on the host of the world and on a dedicated server, "client" on any game with a screen, "both" always. With no argument it answers for the mod's own side. Use it to grey a control with ui.NeedsHost, never to refuse an action: the game answers for itself. |
Content | WaxContent? | The game content the mod brings in content/<Id>.pak: models, textures, blueprints. Nil for a mod without that file. |
OnUnload | fun(fn: fun(why: "reload"|"off"|"removed"|"failed"|"shutdown")): fun() | Runs fn once when the mod is about to unload, before anything of the mod is taken away: its windows, tasks, connections and table changes are all still there. why is "reload" when the mod loads again straight after, "off" when the player switched it off, "removed" when its folder went, "failed" when the mod raised an error while it loaded, and "shutdown" when Wax itself stops. Several run newest first, and one that raises an error is logged and stops none of the others. fn must return at once: it cannot wait. Use it for what Wax cannot undo for you, such as a change made to the world. It does not run when the game closes or the map changes. Returns a function that takes fn off again. |
log
The mod's own log channel. Values after fmt are put into it with string.format.
Type name: WaxLogger.
| Member | Type | Description |
|---|---|---|
channel | string | The mod's id. |
log:trace(fmt, ...)
Logs at trace level, which the default log level drops.
log:trace(fmt: any, ...: any): WaxLogEntry?| Parameter | Type |
|---|---|
fmt | any |
... | any |
Returns WaxLogEntry?
log:debug(fmt, ...)
Logs at debug level.
log:debug(fmt: any, ...: any): WaxLogEntry?| Parameter | Type |
|---|---|
fmt | any |
... | any |
Returns WaxLogEntry?
log:info(fmt, ...)
Logs at info level.
log:info(fmt: any, ...: any): WaxLogEntry?| Parameter | Type |
|---|---|
fmt | any |
... | any |
Returns WaxLogEntry?
log:warn(fmt, ...)
Logs a warning.
log:warn(fmt: any, ...: any): WaxLogEntry?| Parameter | Type |
|---|---|
fmt | any |
... | any |
Returns WaxLogEntry?
log:error(fmt, ...)
Logs an error, which also shows as a notification in the game.
log:error(fmt: any, ...: any): WaxLogEntry?| Parameter | Type |
|---|---|
fmt | any |
... | any |
Returns WaxLogEntry?
storage
Settings that survive restarting the game, kept in one small file per name.
Type name: WaxStorage.
storage.Load(name, defaults?)
Returns a copy of defaults with whatever was saved under name laid over it.
storage.Load<T: table>(name: string, defaults?: T): T
storage.Load(name: string): table| Parameter | Type | Description |
|---|---|---|
name | string | Letters, digits, _ and - only. |
defaults (optional) | T |
Returns T
storage.Save(name, value)
Queues the table to be written under name. Only numbers, strings, booleans and tables of them are kept.
storage.Save(name: string, value: table)| Parameter | Type | Description |
|---|---|---|
name | string | Letters, digits, _ and - only. |
value | table |
Returns nothing.
Global functions
Call these by name, with nothing in front.
print(...)
Logs the values, joined by tabs, at info level on the mod's channel.
print(...: any)| Parameter | Type |
|---|---|
... | any |
Returns nothing.
persist(key, default?)
Returns the value kept under key, storing default (or a new table) on first use. The value survives reloads of the mod.
persist<T>(key: string, default?: T): T
persist(key: string): table| Parameter | Type |
|---|---|
key | string |
default (optional) | T |
Returns T
require(name)
Loads a file of this mod and returns what it returned. require(mod.Utils) and require("Utils") are the same file, as are require(mod.extras.Utils) and require("extras.Utils"). A folder with an init.lua is loaded by the folder's name. require("@Id") gives another mod's exports.
require(name: string|WaxFile): any| Parameter | Type |
|---|---|
name | string | WaxFile |
Returns any
Global values
raw
The real global table: unguarded access to everything UE4SS offers, including what Wax blocks.
Type table<string, any>
WaxManifest
What a mod's mod.lua returns. The file is optional, and so is every field.
| Field | Type | Description |
|---|---|---|
name (optional) | string | Display name. The folder name when omitted. |
version (optional) | string | "0.0.0" when omitted. |
main (optional) | string | Entry file inside the mod's folder. "init.lua" when omitted. |
dependencies (optional) | string[] | Ids of mods that load first. Each can then be reached with require("@Id"). |
key (optional) | string | The key that shows and hides the mod's windows, such as "F6". ui.Window takes it when given no key of its own. |
keys (optional) | string[] | The mod's other keys, one line each: "F10: Show or hide the pins". The name after the colon is the one given to ui.Bind. |
side (optional) | "host" | "client" | "both" | Where the mod's features run: on the host (the game that owns the world, or a dedicated server), on each player's own game, or both. "both" when omitted. The catalogue reads it from the code when it is missing. A mod of the host side shows greyed on a client's Mods page, with a tip, and is never refused. |
features (optional) | string[] | The mod's features with their sides, one line each: "host: Craft from containers", "client: Push all". Each is listed on the mod's card, greyed on a game it cannot run on. |
WaxFile
A file or folder of the mod, as mod.Utils or mod.extras.Utils gives it. Pass it to require.
Used by require.
WaxLogEntry
One line of the Wax log.
Returned by log:trace, log:debug, log:info, log:warn, log:error.
| Field | Type | Description |
|---|---|---|
id | integer | |
time | integer | |
level | "trace" | "debug" | "info" | "warn" | "error" | |
channel | string | |
message | string | |
count | integer | How many times in a row this message was logged. |
Blocked functions
These UE4SS functions raise an error when a mod calls them. The reason is given for each one.
| Function | Note |
|---|---|
LoopAsync | Blocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use task.spawn or task.delay. |
ExecuteAsync | Blocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use task.spawn or task.delay. |
ExecuteWithDelay | Blocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use task.spawn or task.delay. |
RegisterHook | Blocked in Wax mods: it hands your code the game's own arrays, and a write into one of them crashes the game. Use hooks.listen(path, fn, { when = "post" }), which hands you parameters you can read and a return value you can set. |
UnregisterHook | Blocked in Wax mods: hooks.listen returns the function that takes the listener off, and a reload takes it off by itself. |
RegisterKeyBind | Blocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use ui.Hotkey. |
RegisterKeyBindAsync | Blocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use ui.Hotkey. |
RestartMod | Blocked in Wax mods: restarting a UE4SS mod destroys the Lua state Wax runs in. Reload the mod through Wax instead. |
RestartCurrentMod | Blocked in Wax mods: restarting a UE4SS mod destroys the Lua state Wax runs in. Reload the mod through Wax instead. |
UninstallMod | Blocked in Wax mods: it destroys the Lua state Wax runs in. |
UninstallCurrentMod | Blocked in Wax mods: it destroys the Lua state Wax runs in. |
ClearAllDelayedActions | Blocked in Wax mods: it cancels every mod's timers, and Wax's own frame loop with them. |