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