From 1340cc75c7b431adc43d951ef3cb41f7eecf722b Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Wed, 28 Oct 2026 12:08:58 -0500
Subject: [PATCH] feat(chat): SendSystemMessage
Shows a local CHAT_MSG_SYSTEM line through the engine's chat line
function, called as the game-message display calls it for a chat-kind
message: chat type 10 and ten zero arguments.
---
README.md | 2 +-
docs/API.md | 23 +++++++++++++
src/chat/SystemMessage.cpp | 68 ++++++++++++++++++++++++++++++++++++++
3 files changed, 92 insertions(+), 1 deletion(-)
create mode 100644 src/chat/SystemMessage.cpp
diff --git a/README.md b/README.md
index 1bc23fae..1535ce42 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th
| [Animation](docs/API.md#animation) | `region:CreateAnimationGroup`, `region:GetAnimationGroups`, `region:StopAnimating`, `SetMaxAnimFramerate`, `GetMaxAnimFramerate`, `AnimationGroup` and `Animation` / `Alpha` / `Translation` / `Scale` / `Rotation` / `Path` / `ControlPoint` methods |
| [AuctionHouse](docs/API.md#auctionhouse) | `C_AuctionHouse.PostItem` |
| [Bindings](docs/API.md#bindings) | `SetBindingSpell`, `SetBindingItem`, `SetBindingMacro`, `SetBindingClick`, `SetOverrideBinding`, `SetOverrideBindingSpell`, `SetOverrideBindingItem`, `SetOverrideBindingMacro`, `SetOverrideBindingClick`, `ClearOverrideBindings`, `GetBindingAction` (`checkOverride`), `GetBindingByKey`, `IsModifiedClick`, `GetModifiedClick`, `SetModifiedClick`, `GetNumModifiedClickActions`, `GetModifiedClickAction` |
-| [Chat](docs/API.md#chat) | `GetCurrentChatEvent`, `GetCurrentChatGUID` |
+| [Chat](docs/API.md#chat) | `GetCurrentChatEvent`, `GetCurrentChatGUID`, `SendSystemMessage` |
| [ChatBubbles](docs/API.md#chatbubbles) | `C_ChatBubbles.GetAllChatBubbles` |
| [Class](docs/API.md#class) | `FillLocalizedClassList` |
| [ClassColor](docs/API.md#classcolor) | `C_ClassColor.GetClassColor` |
diff --git a/docs/API.md b/docs/API.md
index cef8f369..a2f5eb67 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -68,6 +68,7 @@ build instructions.
- [Chat](#chat)
- [`GetCurrentChatEvent()`](#getcurrentchatevent)
- [`GetCurrentChatGUID()`](#getcurrentchatguid)
+ - [`SendSystemMessage(message)`](#sendsystemmessagemessage)
- [Class](#class)
- [`FillLocalizedClassList(table [, isFemale])`](#filllocalizedclasslisttable--isfemale)
@@ -2056,6 +2057,28 @@ If a chat event handler causes another chat event, the function gives the
inner event's sender while that handler runs. When the inner handler
returns, it gives the outer event's sender again.
+### `SendSystemMessage(message)`
+
+Shows `message` in chat as a system message. Only your client shows the
+line. Nothing goes to the server.
+
+The line has the system message color and fires `CHAT_MSG_SYSTEM`, with
+`message` as `arg1`. Chat frames and addons that watch system messages see
+it as they see a message from the game.
+
+```lua
+SendSystemMessage("Raid check complete.")
+```
+
+| Argument | Type | Description |
+|---|---|---|
+| `message` | string | The text of the line. A number is also accepted. |
+
+If `message` is not a string or a number, the function raises the error
+`Usage: SendSystemMessage("message")`.
+
+The line cannot show icons. A `|T` or `|A` escape shows as text.
+
## Class
### `FillLocalizedClassList(table [, isFemale])`
diff --git a/src/chat/SystemMessage.cpp b/src/chat/SystemMessage.cpp
new file mode 100644
index 00000000..d3b35276
--- /dev/null
+++ b/src/chat/SystemMessage.cpp
@@ -0,0 +1,68 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see .
+
+// `SendSystemMessage(msg)` — a local CHAT_MSG_SYSTEM line.
+//
+// 4.3.4 calls CGChat::AddChatMessage(msg, CHAT_MSG_SYSTEM, NULL). 1.12's
+// equivalent is the chat line function FUN_CHAT_DISPATCH, called exactly as the
+// game-message display FUN_00496720 calls it for a chat-kind message (0x00496822):
+// chat type 10 in EDX and ten zero stack args. The engine copies the text into
+// its own 0x800 buffer with a bounded SStrCopy (0x0049A9F1), so any length is
+// safe. The call goes through Chat::Dispatch's hook like every engine system
+// line does.
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include
+
+namespace Chat::SystemMessage {
+
+namespace {
+
+constexpr int CHAT_MSG_SYSTEM = 0x0A;
+
+using ChatDispatch_t = void(__fastcall *)(
+ const char *message, int chatType,
+ const char *senderName, int languageID, const char *channel, const char *targetName,
+ const char *flags, int speakerGuidLo, int speakerGuidHi, int rank,
+ int guidLo, int guidHi);
+
+int __fastcall Script_SendSystemMessage(void *L) {
+ if (!Game::Lua::IsString(L, 1))
+ Game::Lua::Error(L, "Usage: SendSystemMessage(\"message\")");
+ auto dispatch = reinterpret_cast(
+ static_cast(Offsets::FUN_CHAT_DISPATCH));
+ dispatch(Game::Lua::ToString(L, 1), CHAT_MSG_SYSTEM, nullptr, 0, nullptr, nullptr,
+ nullptr, 0, 0, 0, 0, 0);
+ return 0;
+}
+
+const Game::Doc::Field kArgs[] = {
+ Game::Doc::Req("message", "string", "The text of the line."),
+};
+const Game::Doc::Function kSendSystemMessage{
+ "Shows a line in chat as a system message, only on your own client. It fires "
+ "CHAT_MSG_SYSTEM with the text as arg1.",
+ kArgs, {}, "ChatGlobals"};
+
+} // namespace
+
+static void RegisterLuaFunctions() {
+ Game::Lua::RegisterGlobalFunction("SendSystemMessage", &Script_SendSystemMessage,
+ &kSendSystemMessage);
+}
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace Chat::SystemMessage