Chathooks#
This document provides usage of the Chathook API added in Northstar v1.6.0
.
For an example of chathooks in use, check out EmmaM’s OwOfier mod.
Client chat API#
Callbacks#
The client chat callbacks allow you to intercept chat messages and modify or block them.
-
struct ClClient_MessageStruct#
Contains details on a chat message to be displayed. You can receive one of these by adding a chat callback with AddCallback_OnReceivedSayTextMessage.
-
string message#
the text sent by the player.
-
entity player#
the player who sent the chat.
-
string playerName#
the display name of the player who sent the chat.
-
bool isTeam#
whether this chat has a
[TEAM]
tag.
-
bool isDead#
whether this chat has a
[DEAD]
tag.
-
bool isWhisper#
whether this chat has a
[WHISPER]
tag.
-
bool shouldBlock#
if true, this chat will not be displayed.
-
string message#
-
void AddCallback_OnReceivedSayTextMessage(callbackFunc)#
Adds a callback that will be run when a chat message is received from the server. This will only be triggered for messages from players, not server messages.
The provided function should accept a ClClient_MessageStruct and return an optionally modified copy of it. When a chat message is received, each registered callback is run in sequence to modify or block the message.
Example:
ClClient_MessageStruct function MyChatFilter(ClClient_MessageStruct message) { if (message.message.find("nft") != null) { message.shouldBlock = true } message.message = StringReplace(message.message, "yes", "no", true, true) return message } void function MyModInit() { AddCallback_OnReceivedSayTextMessage(MyChatFilter) }
Writing to Chat#
A handful of functions are provided to write messages in local chat windows. These do not send messages to other players, they only display them locally.
-
void Chat_GameWriteLine(string text)#
Writes a line of text in local game chat panels. Supports ANSI escape codes.
Example:
void function OnGameStarted() { Chat_GameWriteLine("You got this, " + GetLocalClientPlayer().GetPlayerName() + "!") }
-
void Chat_GameWrite(string text)#
Appends text to local game chat panels. Supports ANSI escape codes.
Example:
void function InitialiseHEVSuit() { Chat_GameWriteLine("SENSOR ARRAYS-") ActivateSensorArrays() Chat_GameWrite("ACTIVATED") wait 1 Chat_GameWriteLine("BIOMETRIC MONITORING SYSTEMS-") ActivateBiometricMonitoringSystems() Chat_GameWrite("ACTIVATED") wait 1 Chat_GameWriteLine("HAVE A VERY SAFE DAY.") }
-
void Chat_NetworkWriteLine(string text)#
Writes a line of text in local network chat panels. Supports ANSI escape codes.
Example:
void function MyModInit() { Chat_NetworkWriteLine("MyMod v1.0.0 is good to go!") }
-
void Chat_NetworkWrite(string text)#
Appends text to local network chat panels. Supports ANSI escape codes.
Example:
void function OnButtonPressed() { Chat_NetworkWrite("Connecting in 3...") wait 1 Chat_NetworkWrite("2...") wait 1 Chat_NetworkWrite("1...") wait 1 Chat_NetworkWrite("0") Connect() }
Server Chat API#
Callbacks#
The server chat callbacks allow you to intercept incoming chat messages and modify or block them.
-
struct ClServer_MessageStruct#
Contains details on an incoming chat message. You can receive one of these by adding a chat callback with AddCallback_OnReceivedSayTextMessage.
-
string message#
the text sent by the player.
-
entity player#
the player who sent the chat.
-
bool isTeam#
whether this chat is only sent to the player’s team.
-
bool shouldBlock#
if true, this chat will not be sent.
-
string message#
-
void AddCallback_OnReceivedSayTextMessage(callbackFunc)
Adds a callback that will be run when a chat message is received from a player. This will not be fired for custom messages sent by server mods.
The provided function should accept a ClServer_MessageStruct and return an optionally modified copy of it. When a chat message is received, each registered callback is run in sequence to modify or block the message.
Example:
ClServer_MessageStruct function MyChatFilter(ClServer_MessageStruct message) { if (message.message.find("nft") != null) { message.shouldBlock = true } message.message = StringReplace(message.message, "yes", "no", true, true) return message } void function MyModInit() { AddCallback_OnReceivedSayTextMessage(MyChatFilter) }
Custom Messages#
With custom messages you can send chat messages at any time, to all players or to specific players.
-
void Chat_Impersonate(entity player, string text, bool isTeamChat)#
Displays a chat message as if the player sent it. Only use this when the player has performed a clear action to send a chat message.
Parameters:
entity player
- the player that the chat message will appear to be from.string text
- the contents of the chat message. Supports ANSI escape codes for colors.bool isTeamChat
- whether this chat is only sent to the player’s team.
Example:
void function OnSayRedCommand(entity player, string text) { Chat_Impersonate(player, "red text -> \x1b[31m" + text) }
-
void Chat_PrivateMessage(entity fromPlayer, entity toPlayer, string text, bool whisper)#
Sends a private chat message from a player that is only displayed to one other player. Only use this when the player has performed a clear action to send a chat message.
Parameters:
entity fromPlayer
- the player the message will be from.entity toPlayer
- the player that the message will be shown to.string text
- the contents of the chat message. Supports ANSI escape codes for colors.bool whisper
- if true,[WHISPER]
will be displayed before the message to indicate the message is private.
Example:
void function OnSendToFriendsCommand(entity fromPlayer, string text) { array<entity> friends = GetPlayerFriends(fromPlayer) foreach (friend in friends) { Chat_PrivateMessage(fromPlayer, friend, text, true) } }
-
void Chat_ServerBroadcast(string text, bool withServerTag = true)#
Displays a server message to all players in the chat.
Parameters:
string text
- the contents of the chat message. Supports ANSI escape codes for colors.bool withServerTag
- if true,[SERVER]
will appear before the message in chat. Defaults to true.
Example:
void function RestartServerThread() { // wait one hour wait 3600 Chat_ServerBroadcast("Server will be shut down in \x1b[93m5 seconds") wait 1 Chat_ServerBroadcast("Server will be shut down in \x1b[93m4 seconds") wait 1 Chat_ServerBroadcast("Server will be shut down in \x1b[93m3 seconds") wait 1 Chat_ServerBroadcast("Server will be shut down in \x1b[93m2 seconds") wait 1 Chat_ServerBroadcast("Server will be shut down in \x1b[93m1 second") wait 1 StopServer() }
-
void Chat_ServerPrivateMessage(entity toPlayer, string text, bool whisper, bool withServerTag = true)#
Sends a server message to a specific player in the chat.
Parameters:
entity toPlayer
- the player that the message will be shown to.string text
- the contents of the chat message. Supports ANSI escape codes for colors.bool whisper
- if true,[WHISPER]
will be displayed before the message to indicate the message is private.bool withServerTag
- if true,[SERVER]
will appear before the message in chat. Defaults to true.
Example:
void function OnBanCommand(entity player, array<string> args) { if (!PlayerIsModerator(player)) { Chat_ServerPrivateMessage(player, "You do not have the permissions to perform this command.", true, false) return } BanPlayerByName(args[0]) }
ANSI Escape Codes#
All messages support ANSI escape codes for customising text color. These are commands in strings that have special meaning. For example, the string:
Hello world, \x1b[31mthis text is red\x1b[0m. And \x1b[34mthis text is blue\x1b[0m.
\x1b
is a special character that Squirrel (and other languages) replace with a reserved ASCII character. For future
reference this will be referred to with ESC
(e.g. setting red text is ESC[31m
).
The following commands are available:
Codes |
Description |
|
Reset text formatting. |
|
Set to one of the available color presets. |
|
Set to one of the available 8-bit colors. |
|
Set to an RGB color, with |
|
Set to chat text color. |
|
Set to friendly player name color. |
|
Set to enemy player name color. |
|
Set to network name color. |