Logging and chat

print(...) / aqua.log(msg)

Both write to:

1. In-game console, in cyan: [Lua: <name>] ...
2. Scripts workspace console, with timestamps

aqua.print_chat(text) -> bool[, reason]

Print a client-only line in the game’s native chat, including its fading notices and chat history. Other players do not receive the line. No FFI is required. Percent signs and HTML characters are literal; format values with Lua before calling. The function does not add a prefix or play a chat sound.

true means queued. Delivery runs on the game thread after script callbacks; it works from on_draw and the Scripts console too. An unavailable HUD can drop a queued line. Outside a match, invalid input or a limit returns false, reason. Stopping/reloading a script cancels its pending lines; disconnects/map changes clear the queue, and lines older than one second are discarded. Already dispatched lines remain in chat history.

Text accepts 1-512 UTF-8 bytes without NUL and must contain visible characters. Escaping and color spans must also fit the game’s 2048-byte display buffer; heavily styled text can hit that limit before 512 input bytes. Limits are 8 pending lines per script, 32 overall, and 4 accepted lines per second per script with a burst of 4. Print on an event or behind aqua.once/rate_limit.

local ok, reason = aqua.print_chat('[aqua] 100% ready: <hello> & "welcome"')
if not ok then print(reason) end

Styling: insert native color bytes with string.char(code). Colors apply until the next color byte; code 1 restores the default. HTML tags are escaped. Bytes 1-16 are color controls, so tabs/newlines are not line-break formatting. Other control bytes are rejected.

Code	Color	Code	Color
1	Default / white	9	Olive
2	Red	10	Pale blue
3	Native contextual color	11	Light blue
4	Green	12	Blue
5	Lime	13	Purple
6	Light green	14	Pink
7	Light red	15	Red-pink
8	Gray	16	Gold

local color = {
    default = string.char(1), green = string.char(4),
    red = string.char(7), gray = string.char(8),
    blue = string.char(11), purple = string.char(13), gold = string.char(16)
}

-- Colored prefix, followed by normal text.
aqua.print_chat(color.blue .. '[aqua] ' .. color.default .. 'Script loaded')

-- Several styles in the same line.
aqua.print_chat(color.green .. '[+] ' .. color.default .. 'Hit '
    .. color.gold .. 'Player' .. color.default .. ' for '
    .. color.red .. '43' .. color.default .. ' damage')

-- Values use Lua formatting; percent signs in the result remain literal.
local accuracy = 87
aqua.print_chat(color.purple .. '[stats] ' .. color.default
    .. ('Accuracy: %d%%'):format(accuracy) .. color.gray .. ' (this round)')