On Chat Event

Patch 1.23 includes a new event, "On Chat", which is defined at the module level. This article provides technical information about it, and gives an example of how to use it.

Event Handler Script
This script must be implemented as a StartingConditional, as follows :

// oSender - the person, NPC, or object who spoke // oTarget - for CHAT_MODE_TELL and CHAT_MODE_SERVERMESSAGE, this is the person who is receiving the message. // nChannel - the CHAT_MODE_* const indicating which channel (tell, dm, shout, etc) was spoken on // sMessage - the message that is spoken // return - return FALSE to suppress the original message. return TRUE to allow it to display. int StartingConditional(object oSender, object oTarget, int nChannel, string sMessage)

New Chat Function
The sister function to this is the new function SendChatMessage, which allows you to send a message from a game object as if that object had spoken. // This function is used to send a chat message, as if spoken by a game object // oSender - the PC who will speak, OBJECT_INVALID if channel is CHAT_MODE_SERVER. This must be a valid PC object for CHAT_MODE_PARTY to work. Except for 'CHAT_MODE_SERVER', oSender must be a valid object or nothing will occur. // oReceiver - if nChannel is CHAT_MODE_TELL or CHAT_MODE_SERVER, then this must be the PC //             who will be receiving the message. // nMode - CHAT_MODE const indicating the type of message to be sent. Only the CHAT_MODE_* values //         provided are accepted. // sMessage - actual message text // bInvokeCallback - the module's OnChat script will be invoked to filter this message, //                  if this is TRUE. WARNING: use extreme caution if setting //                  bInvokeCallback to TRUE  from within the OnChat handler itself -- //                  this could lead to an infinite loop and hang your module! void SendChatMessage(object oSender, object oReceiver, int nChannel, string sMessage, int bInvokeCallback = FALSE);

Example Script
// This is a trivial example just meant to show how this works. In a real world situation, // there are many more possibilities. Fans of old text-based games might remember typing in // commands such as "take analgesic" or "wear bathrobe". Another good use would be to // provide  simple debugging tools for playtesting your module. // // If this script were saved as "on_chat.nss", you would set "on_chat" to be used in // the On Chat event of your module, which you can view by choosing // View -> Module Properties from within the toolset. // // In this example, if the speaker is a PC and says only one word, then we will execute // a script with the name of whatever they said. If the PC says the word "boo", we // will instead make them say "eek". This will only work on the regular talk channel. // int StartingConditional(object oSender, object oTarget, int nChannel, string sMessage) {       // allow the text to be spoken normally for objects other than // PCs, and for any channel other than the standard 'talk' channel. if (!GetIsPC(oSender) || nChannel != CHAT_MODE_TALK ) {          return TRUE; }       if (sMessage == "boo") {          // replace the text spoken by the PC. THe l ast parameter of FALSE // ensures that when the PC says "eek" we do NOT invoke this script again. SendChatMessage(oSender, oTarget, nChannel, "eek", FALSE); return FALSE; }

// if we don't find a space, then the PC has spoken only one word. // in this example, this means we'll assume they want to execute a       // script by the name of whatever they said. if (FindSubString(sMessage, " ") == -1) {            SendMessageToPC(oSender, "Executing script by name of: " + sMessage); ExecuteScript(sMessage, oSender); return FALSE; // do not let the say the text aloud. }       return TRUE; // treat all other cases normally, allowing the text to be spoken aloud. }