Wax

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.

Open in the Explorer

MemberTypeDescription
idstringThe mod's folder name.
namestring
versionstring
dirstringPath of the mod's folder.
Reloadfun()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).
Sidefun(side?: "host"|"client"|"both"): booleanWhether 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.
ContentWaxContent?The game content the mod brings in content/<Id>.pak: models, textures, blueprints. Nil for a mod without that file.
OnUnloadfun(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.

Open in the Explorer

MemberTypeDescription
channelstringThe mod's id.

log:trace(fmt, ...)

Logs at trace level, which the default log level drops.

log:trace(fmt: any, ...: any): WaxLogEntry?
ParameterType
fmtany
...any

Returns WaxLogEntry?

Open in the Explorer

log:debug(fmt, ...)

Logs at debug level.

log:debug(fmt: any, ...: any): WaxLogEntry?
ParameterType
fmtany
...any

Returns WaxLogEntry?

Open in the Explorer

log:info(fmt, ...)

Logs at info level.

log:info(fmt: any, ...: any): WaxLogEntry?
ParameterType
fmtany
...any

Returns WaxLogEntry?

Open in the Explorer

log:warn(fmt, ...)

Logs a warning.

log:warn(fmt: any, ...: any): WaxLogEntry?
ParameterType
fmtany
...any

Returns WaxLogEntry?

Open in the Explorer

log:error(fmt, ...)

Logs an error, which also shows as a notification in the game.

log:error(fmt: any, ...: any): WaxLogEntry?
ParameterType
fmtany
...any

Returns WaxLogEntry?

Open in the Explorer

storage

Settings that survive restarting the game, kept in one small file per name.

Type name: WaxStorage.

Open in the Explorer

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
ParameterTypeDescription
namestringLetters, digits, _ and - only.
defaults (optional)T

Returns T

Open in the Explorer

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)
ParameterTypeDescription
namestringLetters, digits, _ and - only.
valuetable

Returns nothing.

Open in the Explorer

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)
ParameterType
...any

Returns nothing.

Open in the Explorer

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
ParameterType
keystring
default (optional)T

Returns T

Open in the Explorer

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
ParameterType
namestring | WaxFile

Returns any

Open in the Explorer

Global values

raw

The real global table: unguarded access to everything UE4SS offers, including what Wax blocks.

Type table<string, any>

Open in the Explorer

WaxManifest

What a mod's mod.lua returns. The file is optional, and so is every field.

Open in the Explorer

FieldTypeDescription
name (optional)stringDisplay name. The folder name when omitted.
version (optional)string"0.0.0" when omitted.
main (optional)stringEntry 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)stringThe 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.

Open in the Explorer

WaxLogEntry

One line of the Wax log.

Returned by log:trace, log:debug, log:info, log:warn, log:error.

Open in the Explorer

FieldTypeDescription
idinteger
timeinteger
level"trace" | "debug" | "info" | "warn" | "error"
channelstring
messagestring
countintegerHow 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.

FunctionNote
LoopAsyncBlocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use task.spawn or task.delay.
ExecuteAsyncBlocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use task.spawn or task.delay.
ExecuteWithDelayBlocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use task.spawn or task.delay.
RegisterHookBlocked 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.
UnregisterHookBlocked in Wax mods: hooks.listen returns the function that takes the listener off, and a reload takes it off by itself.
RegisterKeyBindBlocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use ui.Hotkey.
RegisterKeyBindAsyncBlocked in Wax mods: it runs Lua on another thread, which corrupts the game's Lua state. Use ui.Hotkey.
RestartModBlocked in Wax mods: restarting a UE4SS mod destroys the Lua state Wax runs in. Reload the mod through Wax instead.
RestartCurrentModBlocked in Wax mods: restarting a UE4SS mod destroys the Lua state Wax runs in. Reload the mod through Wax instead.
UninstallModBlocked in Wax mods: it destroys the Lua state Wax runs in.
UninstallCurrentModBlocked in Wax mods: it destroys the Lua state Wax runs in.
ClearAllDelayedActionsBlocked in Wax mods: it cancels every mod's timers, and Wax's own frame loop with them.

Open in the Explorer

On this page