xiao.notify New

Show a notification of the client menu from a script, with a rate limit against spam.

xiao.notify shows a notification of the client: the same toast as the menu uses.

The toast appears in the top left corner of the screen, visible with the menu open or closed. It stays about 4 seconds, and at most 5 are on screen; a sixth pushes the oldest out. The toast is queued and appears at the end of the next Lua frame, so a call from the main chunk, a timer or on_frame shows up within one frame. A notification sent while the client unloads (from on_unload or the unload signal) is not shown.

At a glance

Function	Description
`xiao.notify(title, text?, kind?)`	show a toast, `true` if shown

Rule	Value
Kinds	`"info"` (default), `"success"`, `"warning"`
Rate limit	3 notifications per rolling second, shared by every execution in the VM
Title	at most 48 characters, cut with `...`
Text	at most 128 characters, cut with `...`; one line, the toast clips what does not fit
Characters	printable ASCII only: tabs and line breaks become spaces, each non ASCII character becomes `?`, other control characters are removed

Packet hooks and cmd hooks

xiao.notify raises xiao.notify is not available inside a packet hook or a cmd hook: the toasts belong to the render thread. Defer it with xiao.timer.after(0, ...). See Execution contexts.

Functions

xiao.notify(title, text, kind): boolean

xiao.notify(title: string, text?: string, kind?: "info" | "success" | "warning"): boolean

Name	Type	Description
`title`	string	first line, drawn in capitals by the menu
`text`	string	optional second line, `nil` for none
`kind`	string	optional, `"info"` by default: neutral dot; `"success"`: check mark; `"warning"`: alert triangle in red

A number is accepted for title and text and converted to a string, like in string functions.

Returns: true when the toast is queued, false when the rate limit dropped it. The first drop of a VM prints one line in the console: xiao.notify: more than 3 notifications in 1000 ms, the extra ones are dropped. Errors:

bad argument #1 to 'notify' (string expected, got nil), same for #2 when text is neither a string nor nil
bad argument #3 to 'notify' ('info', 'success' or 'warning' expected)
xiao.notify is not available inside a packet hook or a cmd hook

A dropped notification is not an error: the arguments are still checked first.

xiao.notify("Script", "loaded", "success")

Clear VM resets the rate limit and the one time console line.

Complete example

Warn once when health gets low, and again only after it went back up. The packet hook defers its toast with a timer, since xiao.notify is refused inside a hook.

local warned = false

xiao.signal.add("think", "low_health", function()
    local me = xiao.game.player()
    if me == nil or me.health == nil then return end
    if me.health <= 6 and not warned then
        warned = true
        xiao.notify("Low health", ("%.0f hp left"):format(me.health), "warning")
    elseif me.health > 10 then
        warned = false
    end
end)

xiao.packet.hook("Text", "mention", function(msg)
    local f = msg:fields()
    local text = f ~= nil and f.message or nil
    if type(text) == "string" and text:find("@me", 1, true) then
        xiao.timer.after(0, function()
            xiao.notify("Mention", text, "info")
        end)
    end
end)