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 Player) and one or more recipients. The recipients may be either other Players, or a Channel (see below). You can mix recipients to send the message to both Channels and Players 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 Player 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 Players, Objects (usually Characters) or Channels to send the message to. The types of receivers can be mixed in any combination.
  • header - this has a max-length of 128 characters. This could be used to store mime-type information for this type of message (such as if it’s a mail or a page), but depending on your game it could also instead be used for the subject line or other types of header info you want to track. Being an indexed field it can be used for quick look-ups in the database.
  • 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, players 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 Player’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 players 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, admin and listen.