MUSHclient chat system

Why use chat?
Features
Chat plugin
Quick start guide
Other things you can do
Scripting support
Example of using scripting
Configuration options
Colours

Why use chat?

The chat system lets you do peer-to-peer chatting. That is, talk to other players directly without going through the MUD server. This could be useful for:

Privacy

Most MUDs have facilities for administrators or staff to log conversations or listen without your knowledge. By using a peer-to-peer chat, your conversations do not go through the MUD server at all, and thus are totally invisible to other people on the MUD.
Chat if the MUD is down

Because the chat system is independent of the MUD server, you can still chat if the MUD is down (providing you know your friends' TCP/IP addresses - you would normally establish those in advance).
Working around in-game limits

Some MUDs may have times you can't talk - you might be in a silent room, be gagged for some reason, or be stunned after a fight. By using chat you can still talk to people in your chat group, perhaps to summon help after a fight has gone against you.
Automating your gameplay

The scripting support makes it possible to make powerful scripts that help you to play together (for example, in a PK MUD). You can utilise unused "command numbers" in the chat system, to send commands to each other (providing you both use MUSHclient, heh heh) and have the scripts automatically respond. For example, you could have player A capture his/her HP and Mana with a trigger, and automatically forward them to player B via a chat message. Player B could intercept those figures and display them on the status line.
Compatibility with other clients

MUSHclient uses the MudMaster chat format, from their publicly released specifications. It has been tested with MudMaster 2000 (GUI) and MudMaster console version. All of the chat features that are documented there are implemented, except the following: "Do_not_disturb, Send_action, Send_alias, Send_macro, Send_variable, Send_event, Send_gag, Send_highlight, Send_list, Send_array, Send_baritem". Most of those relate to sending client-specific things (like macros and aliases) which would be different anyway from one client to another. Another chat client, zChat, has a MudMaster compatibility feature. You should turn that on if using zChat with MUSHclient for best results.

Features

Call another player (you will need to ask for his/her TCP/IP address, and what port they intend to use for chatting). The default port is 4050.
Receive calls from one or more other players. They need to know your TCP/IP address to do this.
You can validate incoming calls, and accept or reject them.

Once connected (either by an incoming or outgoing call) you can:

Talk directly to individual players.
Talk to every connected player.
Split players into groups and chat to members of a group.
Emote rather than talk (eg. "Nick sighs" rather than "Nick says, 'hello' )
" Ping" them to see whether they are still there, and how long messages take to reach them.
Send or receive files directly to/from other players. (*)
Snoop their output - in other words, you can see what they see. (*)
Send them commands - what you send gets executed as if they typed it. (*)
See who is connected to them (other chat connections). (*)

The functions marked "(*)" are protected by flags, so you have to enable them before people can do that to you. This is to stop other people affecting your session, or viewing it, without permission.

All these features are on a per-world basis, so if you have multiple worlds open you can have multiple chat sessions as well. If you want chatting to interact between worlds this can be achieved with some simple scripting.

Privacy

You have ultimate control over how chat will be used on your system. You can choose whether or not to receive calls, and if you receive them you can validate them on a case-by-case basis, or write a script to do that for you automatically.
Features like snooping, accepting commands, and accepting files, must be explicitly enabled, per connection, before they can be done.
You can mark connections as "private" so that other people cannot see who you have connected.
You can set someone to be ignored if they are annoying you (so you don't see what they are saying).
You can hang up a connection at any time.

Chat plugin

There is a new plugin supplied with MUSHclient "Chat.xml" - this provides an interface between the chat routines and the player. Install that plugin and then type:


chat:help

to see the various commands you can use.

Quick start guide ....

Install the chat plugin
To receive calls from other players, type: #accept
They will need to know your TCP/IP address. If you don't know it already, go to the MUSHclient File menu, and select "Windows Socket Info". The line "Our Address(es)" will tell you your address. If you are planning to run more than one chat session simultaneously (incoming) then they will need different port numbers. The default port number is 4050, however you might use port 4051, 4052 and so on. To do that you would type, for example:
```
#accept 4052
```
Warning - if you are behind a firewall or NAT (Network Address Translation, otherwise known as IP Masquerading) it may be impossible to receive incoming calls. In that case you need to find someone else and call them. Alternatively, configure your firewall to allow incoming sessions on that port, or in the case of NAT configure it to do "port redirection", so that incoming calls are directed to your PC.
To call another player, type: #call ip-address [ port ]
```
  eg. #call myfriend.hisdomain.com
```
You obviously need to know their TCP/IP address (domain name or dotted number, like: 123.45.6.7). They can find that out in the same was as described above for receiving calls. You also need to know their port number, especially if they are not using the default port of 4050. For example, if you know their address and port, you might type:
```
  eg. #call 123.45.6.7 4052
```
Here is an example, using MUSHclient to call a session in a different window on the same PC:
<CHAT> Calling chat server at 127.0.0.1 port 4052 <CHAT> Session established to localhost. <CHAT> Chat session accepted, user: "Bruce"
In both cases you would normally establish this information using "in-game" chatting (ie. normal "tells" or "says") to exchange the IP address and port, and then switch to using the chat system. If you are worried that admins might find your IP address you could always exchange the information by email, however this doesn't achieve a huge amount, as MUD admins can normally see what your IP address is anyway.
To see who is connected, type: #chats
You will also see if any "flags" are set on each session:
---- Chats ---- 1: Bruce (127.0.0.1, 4052) (can snoop)

If you want more details you can type: #chatdetails [ who ]

eg. #chatdetails bruce


----------------------------------------
Server         : localhost
User           : Bruce
Group          : 
Version        : MUSHclient v3.37
Call IP        : 127.0.0.1
Address        : 127.0.0.1
Port           : 4052
Call port      : 4052
Status         : 4
Type           : 0
ID             : 1
Incoming       : False
Can snoop      : True
Snooping       : False
They snoop     : False
Send commands  : False
Private        : False
Can send files : False
Ignore them    : False
Recent ping    : 0
Started at     : 15/04/03 17:29:19
Last in        : 15/04/03 17:29:19
Last out       : 15/04/03 17:29:19
Started file   : 
Xfer file      : False
Xfer is send   : False
File name      : 
Full file path : 
File size bytes: 0
File blocks    : 0
Blocks xferred : 0
Block size     : 500

To talk to everyone, type: #chatall hello
You chat to everybody, 'hello'
To talk to one person (eg. Nick), type: #chat Nick Hello
You can also #emote or #emoteall to do emotes rather than says. eg.
```
  #emoteall laughs
```
To drop a call (eg. the call to Jane), type: #hangup Jane
To drop all calls, type: #hangupall
To stop accepting calls, type: #nocalls

Other things you can do

Snooping

Snooping lets you see what someone else sees on their output window.

First the person being snooped must enable snooping:
```
#allowsnoop Nick
```
This example lets Nick snoop me.

To disable the snooping flag use "noallowsnoop", eg.
```
#noallowsnoop Nick
```
Then the person who wants to snoop starts the snooping:
```
#snoop Bruce
```
To stop snooping just type the snoop command again.

Send a file

You can send a file from one chat user to another.

First the person who wants to receive a file must enable files:
```
#allowfiles Nick
```
This example lets Nick send files to me.

To disable the files flag use "noallowfiles", eg.
```
#noallowfiles Nick
```
Then the person who wants to send the file does this:
```
#sendfile Bruce
```
You will be prompted for which file to send. The receiver of the file is then prompted for whether or not they want that particular file (and are told its size). If they say "yes" then they are prompted for where to save it.

To stop the file transfer in the middle type:
```
#stopfile Bruce
```

The file is sumchecked as it is read in on the sending end, and also on the receiving end. Both sumchecks should agree. If both players are using MUSHclient you will see the sumchecks printed above each other, so you can simply do a visual scan.


<CHAT> Receiving a file from nick -- Filename:
 C:\WINNT\Profiles\nick\Desktop\tips.txt, Length: 3928 bytes (3.8 Kb).
<CHAT> Receive of file "C:\WINNT\Profiles\nick\Desktop\tips.txt" complete.
<CHAT> Sumcheck as written was:  A59C38AD DFA6EB94 3F2494B4 D29D9E5B 756370EF
<CHAT> Sumcheck from sender was: A59C38AD DFA6EB94 3F2494B4 D29D9E5B 756370EF

The "as written" line was generated by the receiving client, the "from sender" line was generated by the sending client. If both sumchecks agree (160 bits of sumcheck) then it is very likely that the file has been transferred successfully. If not, you should delete the received file and try again. If one of you is using a different client then that client will not generate the sumcheck. In that case you cannot be sure the file was received successfully.

Tip: If you have multiple files to send, or the file is large, we recommend using a file compression/archive utility, such as WinZip or PKzip, to create a single, compressed, file. This will be faster and easier to use. Also, archives will probably incorporate their own sumchecks as a further check of file integrity.

Note: You can only send or receive one file at a time, to each chat user. However you can send files simultaneously to different chat users, and keep chatting during the file transfer.

Send commands

You can send commands from one chat user to another.

First the person who wants to be commanded must enable commands:
```
#allowcommands Nick
```
This example lets Nick send commands to me.

To disable the commands flag use "noallowcommands", eg.
```
#noallowcommands Nick
```
Then the person who wants to send the command does this:
```
#command Bruce west;; eat food;; north
```
<CHAT> You command Bruce to 'west; eat food; north'.
Tip: If you are planning to use command stacking, as in the above example, you need to make sure that you use the receiving client's command stack character. Also, if both clients use the same command-stack character, you would need to type it twice, otherwise the command stacking would occur on the sending client end. The example above does that by using ";;" in the command.

Sending multiple lines

You can use the #paste command to send multiple lines to another chat user. You could do this to simply show something you see on the screen (eg. your inventory), or to exchange triggers, aliases etc.

To exchange aliases, triggers, timers, or similar, do this:

Go to the appropriate configuration screen in MUSHclient (eg. aliaes).
Select one or more aliases in the list by clicking, control-clicking or shift-clicking them.
Click on the "copy" button to copy them to the clipboard.
Close the configuration screen.
Type:
```
#paste Nick
```

That pastes the clipboard contents to the other player.


<CHAT> You paste to nick: 

<aliases>
  <alias
   name="Eat_My_Food"
   match="eat"
   enabled="y"
   group="Group3"
   menu="y"
   sequence="100"
  >
  <send>open bag
get food bag
eat food
close bag</send>
  </alias>
</aliases>

They can then copy the resulting information from their screen by clicking and dragging.
They can them go into their alias configuration screen and click the "Paste" button to paste the resulting alias into their world.

Scripting support

The chat features has detailed support in the MUSHclient scripting language. The follow new script routines have been added:

ChatAcceptCalls(short Port);
ChatCall(BSTR Server, long Port);
ChatDisconnect(long ID);
ChatDisconnectAll();
ChatEverybody(BSTR Message, BOOL Emote);
ChatGetID(BSTR Who);
ChatGroup(BSTR Group, BSTR Message, BOOL Emote);
ChatID(long ID, BSTR Message, BOOL Emote);
ChatMessage(long ID, short Message, BSTR Text);
ChatNameChange(BSTR NewName);
ChatNote(short NoteType, BSTR Message);
ChatPasteEverybody();
ChatPasteText(long ID);
ChatPeekConnections(long ID);
ChatPersonal(BSTR Who, BSTR Message, BOOL Emote);
ChatPing(long ID);
ChatRequestConnections(long ID);
ChatSendFile(long ID, BSTR FileName);
ChatStopAcceptingCalls();
ChatStopFileTransfer(long ID);

The following routine retrieves a list of the current chat sessions:

GetChatList();

You can use the chat "ID"s (identifiers) returned from the above to find out more about a particular chat session, or set chat options:

GetChatInfo(long ChatID, short InfoType);
GetChatOption(long ID, BSTR OptionName);
SetChatOption(long ID, BSTR OptionName, BSTR Value);

The following routines have been added to improve handling of ANSI codes, because incoming and outgoing chat messages are supposed to be coloured using standard ANSI sequences:

ANSI(short Code); // make an ANSI sequence
AnsiNote(BSTR Text); // do a "note" using ANSI codes
StripANSI(BSTR Message); // remove ANSI codes from a string

New plugin callback routines have been added to let plugins interface with the chat system:

Function OnPluginChatAccept (sText)
Function OnPluginChatMessage (id, message, sText)
Function OnPluginChatDisplay (message, sText)
Sub OnPluginChatNewUser (id, name)
Sub OnPluginChatUserDisconnect (id, name)

These routines let you automate things like whether callers are accepted, process or disgregard certain chat message types, display incoming messages in the default way, or customise it. You are also notified of new players joining the chat system, and ones that leave it.

Example of using scripting

Using a trigger to tell the group what is happening

The example below shows how you can use a trigger (this one matches "You are hungry.") to automatically send an "emote to all" to tell everybody.


<triggers>
  <trigger
   enabled="y"
   match="You are hungry."
   send_to="12"
   sequence="100"
  >
  <send>ChatEverybody &quot;is hungry&quot;, 1</send>
  </trigger>
</triggers>

When this fires, everybody sees:


nick is hungry

The "ChatEverybody" script routine sends a chat to everybody. The second argument is the "emote" argument. By setting it to 1 you emote rather than say.

Using a custom message number

The MudMaster chat system uses a single byte for chat messages numbers. The numbers 1 to 31 are already used, and zChat also uses 100 to 106 for its extensions to the chat system. Thus, numbers out of those ranges are free for user-chosen features. You should probably choose a number well away from those ranges (for example, 200 up) to implement your own messages. Note that 255 is taken as the "end of message" identifier, and numbers 256 and above will not fit into a single byte.

Below I will illustrate how you could exchange your "prompt line" with another player, so you can monitor their status as you both play the MUD.

First, the "sending" player needs a trigger to capture the prompt, and send it with a custom message number to the other player ...
```
<triggers>
  <trigger
   enabled="y"
   match="&lt;*hp *m *mv&gt;*"
   send_to="12"
   sequence="100"
  >
  <send>ChatMessage ChatGetID (&quot;bruce&quot;), 200, &quot;%0&quot;</send>
  </trigger>
</triggers>
```
This example sends the message to Bruce, but you could choose anybody, or make a loop to send to all players (using GetChatList). The ChatMessage script routine sends a "raw" chat message - it is not formatted in any way, and can thus contain any data of your choosing.
Now Bruce needs to detect the incoming message 200 and react to it. This needs to be done in a plugin, because it uses a plugin callback to detect the chat message. By returning vbFalse it tells MUSHclient not to do any further processing for the message type 200, however other messages are to be processed in the nomral way.
```
Function OnPluginChatMessage (id, message, sText)

OnPluginChatMessage = vbTrue  ' default to process it

if message = 200 then
  SetStatus GetChatInfo (id, 2) & ": " & sText
  OnPluginChatMessage = vbFalse  ' don't process again
end if

End Function
```
The script uses GetChatInfo (id, 2) to find the actual chat name of the player with the supplied ID, so it will work for whatever name the incoming player has.

The beauty of this system is that it uses the chat system to exchange information with another player, however your screen is not cluttered up with messages. An bit more work and you could probably build some powerful automated systems that enhance playing on PK MUDs.

Configuration options

You can configure various aspects of the chat system by using world.SetOption and the following option names:

Option name	Purpose
accept_chat_connections	Are we accepting incoming chat calls?
auto_allow_snooping	Can they can snoop (if enabled) without a further dialog?
chat_name	Our chat name
chat_port	Port number to receive incoming chat calls
chat_foreground_colour	Foreground (text) colour for chat messages
chat_background_colour	Background colour for chat messages
ignore_chat_colours	Ignore imbedded colours in incoming chat messages?
validate_incoming_chat_calls	Ask before accepting incoming chat calls?

Examples:


world.SetAlphaOption "chat_name", "Henry"
world.SetOption "accept_chat_connections", 1
world.SetOption "chat_port", 4090
world.SetOption "chat_foreground_colour", ColourNameToRGB ("green")

Hint: Most of these options can be indirectly set by using the appropriate script routine. For example, to accept incoming calls use:


 world.ChatAcceptCalls (port)

Using ChatAcceptCalls does three things:

Sets the "accept_chat_connections" flag to true
Changes the "chat_port" to the supplied port number
Actually starts listening for calls (unless it is already accepting calls)

If you just set the option using world.SetOption the option is only noticed next time MUSHclient tries to accept a call.

Similarly, you can use:


 world.ChatNameChange (newname)

to change your chat name. Not only does this change the MUSHclient internal chat name, but notifies existing chat users of your name change.

Colours

The MudMaster chat system seems to rely on clients using the default chat colour of red text on black background. Even if you change the MUSHclient chat colour (as in the example above) you may find parts of incoming messages still in an undesired colour because of the imbedded colours codes.

If this bothers you, set the option "ignore_chat_colours" as described above. Then, chat messages will only appear in the colour you have specified (for the entire line) and any imbedded colour codes will be disregarded.