<li><aclass="reference internal"href="#properties-defined-on-msg">Properties defined on <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code></a></li>
<li><aclass="reference internal"href="#properties-defined-on-channel">Properties defined on <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code></a></li>
<h1>Communications<aclass="headerlink"href="#communications"title="Permalink to this headline">¶</a></h1>
<p>Apart from moving around in the game world and talking, players might need other forms of communication. This is offered by Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">Comm</span></code> system. Stock evennia implements a ‘MUX-like’ system of channels, but there is nothing stopping you from changing things to better suit your taste.</p>
<p>Comms rely on two main database objects - <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code>. There is also the <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> which mimics the API of a <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> but has no connection to the database.</p>
<divclass="section"id="msg">
<h2>Msg<aclass="headerlink"href="#msg"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> object is the basic unit of communication in Evennia. A message works a little like an e-mail; it always has a sender (a <aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a>) and one or more recipients. The recipients may be either other Accounts, or a <em>Channel</em> (see below). You can mix recipients to send the message to both Channels and Accounts if you like.</p>
<p>Once created, a <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> 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.</p>
<h3>Properties defined on <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code><aclass="headerlink"href="#properties-defined-on-msg"title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">senders</span></code> - this is a reference to one or many <aclass="reference internal"href="Accounts.html"><spanclass="doc">Account</span></a> or <aclass="reference internal"href="Objects.html"><spanclass="doc">Objects</span></a> (normally <em>Characters</em>) sending the message. This could also be an <em>External Connection</em> 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.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">receivers</span></code> - a list of target <aclass="reference internal"href="Accounts.html"><spanclass="doc">Accounts</span></a>, <aclass="reference internal"href="Objects.html"><spanclass="doc">Objects</span></a> (usually <em>Characters</em>) or <em>Channels</em> to send the message to. The types of receivers can be mixed in any combination.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">header</span></code> - this is a text field for storing a title or header for the message.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">message</span></code> - the actual text being sent.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">date_sent</span></code> - when message was sent (auto-created).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locks</span></code> - a <aclass="reference internal"href="Locks.html"><spanclass="doc">lock definition</span></a>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">hide_from</span></code> - this can optionally hold a list of objects, accounts or channels to hide this <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> 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.</p></li>
</ul>
<p>You create new messages in code using <codeclass="docutils literal notranslate"><spanclass="pre">evennia.create_message</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils.create.create_message.</span></code>)</p>
</div>
</div>
<divclass="section"id="tempmsg">
<h2>TempMsg<aclass="headerlink"href="#tempmsg"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">evennia.comms.models</span></code> also has <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> which mimics the API of <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> 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 <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> but when you don’t actually want to save anything.</p>
</div>
<divclass="section"id="channels">
<h2>Channels<aclass="headerlink"href="#channels"title="Permalink to this headline">¶</a></h2>
<p>Channels are <aclass="reference internal"href="Typeclasses.html"><spanclass="doc">Typeclassed</span></a> entities, which mean they can be easily extended and their functionality modified. To change which channel typeclass Evennia uses, change settings.BASE_CHANNEL_TYPECLASS.</p>
<p>Channels act as generic distributors of messages. Think of them as “switch boards” redistributing <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> objects. Internally they hold a list of “listening” objects and any <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code>) sent to the channel will be distributed out to all channel listeners. Channels have <aclass="reference internal"href="Locks.html"><spanclass="doc">Locks</span></a> to limit who may listen and/or send messages through them.</p>
<p>The <em>sending</em> of text to a channel is handled by a dynamically created <aclass="reference internal"href="Commands.html"><spanclass="doc">Command</span></a> that always have the same name as the channel. This is created for each channel by the global <codeclass="docutils literal notranslate"><spanclass="pre">ChannelHandler</span></code>. 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.</p>
<p>The default ChannelCommand (which can be customized by pointing <codeclass="docutils literal notranslate"><spanclass="pre">settings.CHANNEL_COMMAND_CLASS</span></code> to your own command), implements a few convenient features:</p>
<ul>
<li><p>It only sends <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> objects. Instead of storing individual entries in the database it instead dumps channel output a file log in <codeclass="docutils literal notranslate"><spanclass="pre">server/logs/channel_<channelname>.log</span></code>. 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.</p></li>
<li><p>It adds a <codeclass="docutils literal notranslate"><spanclass="pre">/history</span></code> 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:</p>
<p>There are two default channels created in stock Evennia - <codeclass="docutils literal notranslate"><spanclass="pre">MudInfo</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Public</span></code>. <codeclass="docutils literal notranslate"><spanclass="pre">MudInfo</span></code> receives server-related messages meant for Admins whereas <codeclass="docutils literal notranslate"><spanclass="pre">Public</span></code> 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 <codeclass="docutils literal notranslate"><spanclass="pre">DEFAULT_CHANNELS</span></code> list (see <codeclass="docutils literal notranslate"><spanclass="pre">evennia/settings_default.py</span></code> for more details).</p>
<p>You create new channels with <codeclass="docutils literal notranslate"><spanclass="pre">evennia.create_channel</span></code> (or <codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils.create.create_channel</span></code>).</p>
<p>In code, messages are sent to a channel using the <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">tempmsg</span></code> methods of channels:</p>
<p>The argument <codeclass="docutils literal notranslate"><spanclass="pre">msgobj</span></code> can be either a string, a previously constructed <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> or a <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> - in the latter cases all the following keywords are ignored since the message objects already contains all this information. If <codeclass="docutils literal notranslate"><spanclass="pre">msgobj</span></code> is a string, the other keywords are used for creating a new <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> on the fly, depending on if <codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> is set or not. By default, a <codeclass="docutils literal notranslate"><spanclass="pre">TempMsg</span></code> is emitted for channel communication (since the default ChannelCommand instead logs to a file).</p>
4</pre></div></td><tdclass="code"><divclass="highlight"><pre><span></span><spanclass="c1"># assume we have a 'sender' object and a channel named 'mychan'</span>
<spanclass="c1"># manually sending a message to a channel</span>
<h3>Properties defined on <codeclass="docutils literal notranslate"><spanclass="pre">Channel</span></code><aclass="headerlink"href="#properties-defined-on-channel"title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> - main name for channel</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> - alternative native names for channels</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">desc</span></code> - optional description of channel (seen in listings)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">keep_log</span></code> (bool) - if the channel should store messages (default)</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locks</span></code> - A <aclass="reference internal"href="Locks.html"><spanclass="doc">lock definition</span></a>. Channels normally use the access_types <codeclass="docutils literal notranslate"><spanclass="pre">send,</span><spanclass="pre">control</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">listen</span></code>.</p></li>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> and ❤️ using a custom <ahref="https://github.com/LinxiFan/Sphinx-theme">theme</a> based on <ahref="https://readthedocs.org">Read the Docs</a>.
