Communications

Apart from moving around in the game world and talking, players might need other forms of communication. This is offered by Evennia’s Comm system. Stock evennia implements a ‘MUX-like’ system of channels, but there is nothing stopping you from changing things to better suit your taste.

Comms rely on two main database objects - Msg and Channel. There is also the TempMsg which mimics the API of a Msg but has no connection to the database.

Msg

The Msg object is the basic unit of communication in Evennia. A message works a little like an e-mail; it always has a sender (a Account) and one or more recipients. The recipients may be either other Accounts, or a Channel (see below). You can mix recipients to send the message to both Channels and Accounts if you like.

Once created, a Msg is normally not changed. It is peristently saved in the database. This allows for comprehensive logging of communications. This could be useful for allowing senders/receivers to have ‘mailboxes’ with the messages they want to keep.

Properties defined on Msg

• senders - this is a reference to one or many Account or Objects (normally Characters) sending the message. This could also be an External Connection such as a message coming in over IRC/IMC2 (see below). There is usually only one sender, but the types can also be mixed in any combination.

• receivers - a list of target Accounts, Objects (usually Characters) or Channels to send the message to. The types of receivers can be mixed in any combination.

• header - this is a text field for storing a title or header for the message.

• message - the actual text being sent.

• date_sent - when message was sent (auto-created).

• locks - a lock definition.

• hide_from - this can optionally hold a list of objects, accounts or channels to hide this Msg from. This relationship is stored in the database primarily for optimization reasons, allowing for quickly post-filter out messages not intended for a given target. There is no in-game methods for setting this, it’s intended to be done in code.

You create new messages in code using evennia.create_message (or evennia.utils.create.create_message.)

TempMsg

evennia.comms.models also has TempMsg which mimics the API of Msg but is not connected to the database. TempMsgs are used by Evennia for channel messages by default. They can be used for any system expecting a Msg but when you don’t actually want to save anything.

Channels

Channels are Typeclassed entities, which mean they can be easily extended and their functionality modified. To change which channel typeclass Evennia uses, change settings.BASE_CHANNEL_TYPECLASS.

Channels act as generic distributors of messages. Think of them as “switch boards” redistributing Msg or TempMsg objects. Internally they hold a list of “listening” objects and any Msg (or TempMsg) sent to the channel will be distributed out to all channel listeners. Channels have Locks to limit who may listen and/or send messages through them.

The sending of text to a channel is handled by a dynamically created Command that always have the same name as the channel. This is created for each channel by the global ChannelHandler. The Channel command is added to the Account’s cmdset and normal command locks are used to determine which channels are possible to write to. When subscribing to a channel, you can then just write the channel name and the text to send.

The default ChannelCommand (which can be customized by pointing settings.CHANNEL_COMMAND_CLASS to your own command), implements a few convenient features:

• It only sends TempMsg objects. Instead of storing individual entries in the database it instead dumps channel output a file log in server/logs/channel_<channelname>.log. This is mainly for practical reasons - we find one rarely need to query individual Msg objects at a later date. Just stupidly dumping the log to a file also means a lot less database overhead.

• It adds a /history switch to view the 20 last messages in the channel. These are read from the end of the log file. One can also supply a line number to start further back in the file (but always 20 entries at a time). It’s used like this:

   > public/history
   > public/history 35
  

There are two default channels created in stock Evennia - MudInfo and Public. MudInfo receives server-related messages meant for Admins whereas Public is open to everyone to chat on (all new accounts are automatically joined to it when logging in, it is useful for asking questions). The default channels are defined by the DEFAULT_CHANNELS list (see evennia/settings_default.py for more details).

You create new channels with evennia.create_channel (or evennia.utils.create.create_channel).

In code, messages are sent to a channel using the msg or tempmsg methods of channels:

 channel.msg(msgobj, header=None, senders=None, persistent=True)

The argument msgobj can be either a string, a previously constructed Msg or a TempMsg - in the latter cases all the following keywords are ignored since the message objects already contains all this information. If msgobj is a string, the other keywords are used for creating a new Msg or TempMsg on the fly, depending on if persistent is set or not. By default, a TempMsg is emitted for channel communication (since the default ChannelCommand instead logs to a file).

    # assume we have a 'sender' object and a channel named 'mychan'

    # manually sending a message to a channel
    mychan.msg("Hello!", senders=[sender])

Properties defined on Channel

• key - main name for channel

• aliases - alternative native names for channels

• desc - optional description of channel (seen in listings)

• keep_log (bool) - if the channel should store messages (default)

• locks - A lock definition. Channels normally use the access_types send, control and listen.