Wax

Events of the game

Hear when a character is hit or dies, when items come into an inventory or leave it, and when the item in hand changes.

For a few things the game itself tells Wax the moment they happen: a hit, a death, and an item that comes or goes. Wax hands them to you as signals.

init.lua
game.Me.Damaged:Connect(function(_, amount, info)
    local text = ("You lost %d health. %s left."):format(amount, tostring(info.Health))
    ui.Notify(text, { kind = "warn" })
end)

game.Creatures.Died:Connect(function(creature, info)
    if info.Killer then
        print(info.Kind, "was killed by", info.Killer.Name)
    end
end)

Where they are

SignalFires for
game.Me.Damaged, game.Me.DiedYour own character. They stay connected through a respawn and a map change.
character.Damaged, character.DiedOne character you have as an Instance: a player's or a creature's.
game.Creatures.DamagedEvery creature.
game.Creatures.DiedEvery creature. Before Wax 0.3.0 it came without Killer, Instigator and Damage.
game.Me.ItemAdded, ItemRemoved, ItemChangedEverything your character carries, over all its inventories.
inventory.ItemAdded, ItemRemoved, ItemChangedOne inventory, such as game.Me.Backpack.

Damaged

Your function gets the character, the damage of the hit, and a table with what the game knows of it.

In infoWhat it is
HealthThe character's health after the hit.
AppliedWhat the game took off its health.
CauserThe actor the game names as what did it. For hunger and for a fall that is the character itself.
InstigatorThe controller the game names as who did it. For hunger and for a fall there is none.
Radialtrue for damage over an area.
Stealthtrue for a stealth hit.
  • Health that goes down with no hit is not damage. Assigning character.Health as the host does not fire it.
  • The handlers of one signal share one info table. Copy what you want to keep.

Died

Died fires once when the character is dead.

In infoWhat it is
KillerThe Causer of the hit that left it no health.
InstigatorThe Instigator of that hit.
DamageThe damage of that hit.

All three are nil when the character died with no hit that Wax heard. A creature killed with Kill() is such a death. For game.Creatures.Died, info also has Kind, Variant, ClassName and Name, as before.

A character that lives again and dies again is told again. When a character leaves the world, the handlers you connected to that Instance are disconnected.

Items

init.lua
game.Me.ItemAdded:Connect(function(item, amount, stack)
    local where = stack and stack.Inventory or "an inventory"
    print(("+%d %s into %s"):format(amount, item, where))
end)

game.Me.ItemRemoved:Connect(function(item, amount)
    print(("-%d %s"):format(amount, item))
end)
SignalFires whenYour function gets
ItemAddedThere is more of an item than a frame before.The item's name, how many more, and a stack it went onto.
ItemRemovedThere is less of an item than a frame before.The item's name, how many fewer, and a stack it came out of.
ItemChangedA slot holds something else than a frame before.What it holds now and what it held, with nil for nothing.
  • A stack that only moves from one slot or inventory of your character to another is not added and not removed. It is a change of both slots.
  • A tool that wore is a change. A spoil timer that only counts down is not.
  • The item's name is spelled as the game spells it, which is not always the same letter case. Compare names without it, or ask Count or Has.

A stack is the same table that inventories give.

The hand

game.Me.Equipped fires when the hotbar slot in hand, or the item in it, is not what it was. Wax looks four times a second, and only while a handler is connected. Your function gets the stack in hand now, or nil when that slot is empty, and the name of the item that was in hand. What was already in hand when you connect is where the signal starts. Bare hands are the item Player_Fist.

game.Me.Activated fires inside stack:Activate, with the stack and the use name. With no use name, that second value is nil.

init.lua
game.Me.Equipped:Connect(function(stack, previous)
    print("In hand:", stack and stack.Item or "empty", "was", previous)
end)

How to put a stack in the hand, and what Activate("Consume") runs, is on Items and inventories.

When your function runs

A handler on one of the signals above never runs inside the game's own call. Wax notes what it heard and tells you from its frame loop, in the same frame or the next. So your function can wait, show a window or call the game, like any other task. A listener made with hooks.listen, below, is the other kind: it runs inside the call.

Listening to any function of the game

The signals cover what most mods need. For anything else, hooks.listen runs your function each time the game calls one of its own: a function of the game's C++ code, named by its path. The Explorer lists them with their parameters.

init.lua
-- The bench asks whether an input of a recipe can be met. Say yes when a chest nearby has it.
hooks.listen("/Script/Icarus.ProcessingComponent:CanSatisfyRecipeInput", function(bench, ret, input, multiplier, extra, have)
    if ret:get() == false and chests.have(bench, input.Element.RowName, input.Count * multiplier) then
        ret:set(true)
    end
end, { when = "post" })
  • when = "pre", the default, runs your function before the game's: fn(object, params...).
  • when = "post" runs it after: fn(object, ret, params...). ret:get() is what the game answered, and ret:set(value) replaces what the caller will see. Returning a value from your function does the same.
  • The object the function was called on comes as an Instance. Numbers, strings and booleans come as they are, an object parameter as an Instance, an array or a struct as a view: #list, list[i], shape.Field, and list:get() for a Lua table you can keep. A view is good inside your function only, so copy what you want to keep.
  • Your function runs inside the game's call. Keep it short, never wait in it, and do not show windows from it. An error is logged, and after five in a row the listener is switched off.
  • It returns a function that takes the listener off. A reload of your mod takes it off by itself.
  • reach = "called" is for a function that blueprint code calls: the values UE4SS sees then are the caller's own variables, so only the object is handed over.

Arrays the game hands you are read-only

What a hook is handed lives in the game's own memory for the length of the call. An array there belongs to the function that made it: if Lua made it longer or emptied it, UE4SS would give it new memory of its own, and the game would then write into or free memory it does not own. That is a crash, and on a dedicated server it took the whole session down. So every write into a parameter raises an error:

Wax refuses to write into an array the game handed a hook: it belongs to the game. Use the return value, or move items with the game's own calls.

The right ways:

  • The return value. Change what the function answers with ret:set or by returning a value, as above.
  • The game's own calls. To have the game count an item, give it the item: inventory:Move, Push and Pull on Items and inventories hand it over the way the game does, before the game looks.

raw.RegisterHook is still there for whoever accepts the risk: it hands you UE4SS's values with no view in between, the log says so once per file when the mod loads, and the catalogue warns on it. RegisterHook by itself is not available in a mod, and the catalogue refuses a mod that calls it.

Answering a crafting check from the containers around

The game decides whether a recipe can be made with ProcessingComponent:CanSatisfyRecipeInput(Input, Multiplier, AdditionalInventories, CurrentAmount) for each input and CanQueueItem(RecipeToQueue, AdditionalInventories) for the CRAFT button, and it hands each an array of extra inventories that nothing may be added to. The way to count the chests around a station is to answer those checks after the game has: read the game's own answer first and leave a yes alone, read only the fields you need, and take the counts from game.Containers rather than from the game on every call. The checks run for every recipe tile when a crafting screen opens, hundreds in one frame, so the memo below answers a repeated ask from the frame's first one.

init.lua
local memo = raw.Wax.import("core.memo")
local answered = memo.frame()                     -- forgets everything when the frame moves on

local function station_of(component)             -- the actor the check was made on, and its place
    local owner = component:GetOwner()
    local at = owner:K2_GetActorLocation()
    return { addr = owner:GetAddress(), at = { X = at.X, Y = at.Y, Z = at.Z } }
end

hooks.listen("/Script/Icarus.ProcessingComponent:CanSatisfyRecipeInput", function(component, ret, input, multiplier, _, current)
    if ret:get() == true then return end          -- the game says yes: nothing to add
    local item, count = input.Element.RowName, input.Count
    local station = station_of(component.Raw)
    local key = station.addr .. "|" .. item .. "|" .. count .. "|" .. multiplier .. "|" .. current
    return answered:take(key, function()
        local nearby = game.Containers:Held(item, 30, { around = station.at })
        if current + nearby >= count * multiplier then return true end
        return nil                                -- nil is not kept, and leaves the game's no
    end)
end, { when = "post", reach = "net" })

For the craft itself, move what the backpack lacks into it before the game counts: a when = "pre" listener on OnServer_AddProcessingRecipe that uses OnServer_ShiftItem through the player's controller, where the craft is decided (a server, a host, a single player). Quick Stash in the catalogue is the whole of it, with the station's sources kept half a second and a per-frame memo for the CRAFT button's check too.

Memos for hot hooks

core.memo has two small caches for paths the game runs many times a frame: memo.frame() keeps its entries for the rest of the current frame, memo.timed(seconds) for that long. Both have get, has, set, take(key, fn, ...) (the value kept, or fn run and kept) and clear; keys are any Lua value, false is kept as a value, nil is not. The memo reference lists them.

What they cost

  • Nothing until the first handler connects. Wax starts listening to the game's function then.
  • While connected, each time the game calls that function costs a little: about 0.1 ms for a hit, and 0.02 to 0.06 ms for an item. The game reports a spoiling stack about once a second.
  • The first handler on game.Me.ItemAdded, ItemRemoved or ItemChanged reads all six inventories once.

What has been seen

All of this was seen on the host of a session, on a player's character: damage from a fall, and items given and taken. A poisoned deer fired Damaged for each tick of the poison. These have not been seen:

  • Any of it as a guest in someone else's game.
  • A player's death. game.Me.Died has only run in tests outside the game.
  • A creature killed by a player's hit, so what Killer names then has not been looked at. Poison named the animal itself.
  • The item signals of a chest or a bench. There, an inventory you keep asking about is still kept up to date by looking, as Items and inventories says.
  • The few bosses of the class IcarusPawn are not told by game.Creatures.Damaged. Their death is told, with no killer.

Wax has no function for listening to other functions of the game. To follow a value, see Watching a value.

The signals are listed in the Characters reference and the Items and inventories reference.

On this page