SendChatMessage

A chat message to one player - a text, or pieces that differ in colour, weight and slant.

message is a text - SendClientMessage with the default colour - or a table:

key	what it is
text	the words, in one colour
spans	the words in pieces: a list whose entries are a text or a table { text = "...", color = 0xRRGGBBAA, bold = true, italic = true } (a span’s color left out is the line’s colour). When there are spans, text is ignored
channel	the channel the line belongs to; "" or left out is the default channel
color	0xRRGGBBAA: the line’s colour and that of every span that has none of its own. Left out, it is the channel’s colour, else white
template	the name of a chat template of the interface ([theme.chat.templates] in its ui.toml, ooc): the web chat lays the line out with it; the game’s own chat draws the plain line
params	the template’s {0} to {15}: a list of texts (a number is written as text) - at most 16, 256 characters each, 1024 in all

A line carries at most 16 spans and 512 characters in all - counted over the words of every span - and a message over either is refused, never cut; so is an empty one.

With a template and no text or spans, the plain line - the game’s own chat, a bot, the server’s log - is the template with the params put in and its tags left out (<b>{0}</b>: {1} with {"Henry", "hi"} is Henry: hi); when the interface has no template of that name, the params one after the other. A template’s own words are the interface’s: the template language ({0}, {{ and }}, <b>, <i>, <span class="...">) never runs anything, and every param is shown as text.

A line sent to one player reaches them whatever the channel’s visibility - the mode chose the recipient. The game’s own chat draws a line in one colour (the first span’s, when it has one, otherwise the line’s) with the channel’s label in front; a chat that can style messages draws each piece as it was given.

The answer is true, or false and the reason: "no such player", "no such channel", "too many spans (16 at most)", "the message is over 512 characters", "empty message", "bad template name (a-z, 0-9 and _, starting with a letter, 32 at most)", "too many params (16 at most)", "a param is over 256 characters", "the params are over 1024 characters in all", "params need a template" - or, for a table that is not a message, what is wrong with it in words ("a span needs its text", "spans must be a list", "color must be a number", "template must be a text", "params must be a list" …).

Syntax

SendChatMessage(pid, message)

Parameter	Type
pid	number	the player
message	string | table	a text, or a table { text | spans, channel, color, template, params }

Returns

true, or false, reason - the reason as a person reads it ("too many spans (16 at most)", "no such channel" …)

Example

-- a guard's challenge: the name in gold and bold, the words in italics
SendChatMessage(pid, {
  spans = {
    { text = "[Guard] ", color = COLOR_GOLD, bold = true },
    { text = "Halt! Who goes there?", italic = true },
  },
})

-- a line on a channel; the reason is there when it cannot be sent
local ok, why = SendChatMessage(pid, { text = "Sold to the man in blue.", channel = "trade" })
if not ok then Log("trade line: " .. why) end

See also

SendChatMessageToAll · SendClientMessage · RegisterChatChannel · OnPlayerText · ClearPlayerChat · the Chat and commands group of the index