<p>The <aclass="reference internal"href="../api/evennia.comms.models.html#evennia.comms.models.Msg"title="evennia.comms.models.Msg"><spanclass="xref myst py py-class">Msg</span></a> object represents a database-saved piece of communication. Think of it as a discrete piece of email - it contains a message, some metadata and will always have a sender and one or more recipients.</p>
<p>Once created, a Msg is normally not changed. It is persitently saved in the database. This allows for comprehensive logging of communications. Here are some good uses for <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> objects:</p>
<li><p>page/tells (the <codeclass="docutils literal notranslate"><spanclass="pre">page</span></code> command is how Evennia uses them out of the box)</p></li>
<li><p>messages in a bulletin board</p></li>
<li><p>game-wide email stored in ‘mailboxes’.</p></li>
</ul>
<divclass="admonition important">
<pclass="admonition-title">Important</p>
<p>A <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> does not have any in-game representation. So if you want to use them
to represent in-game mail/letters, the physical letters would never be
visible in a room (possible to steal, spy on etc) unless you make your
spy-system access the Msgs directly (or go to the trouble of spawning an
actual in-game letter-object based on the Msg)</p>
</div>
<divclass="versionchanged">
<p><spanclass="versionmodified changed">Changed in version 1.0: </span>Channels dropped Msg-support. Now only used in <codeclass="docutils literal notranslate"><spanclass="pre">page</span></code> command by default.</p>
<h2>Working with Msg<aclass="headerlink"href="#working-with-msg"title="Permalink to this headline">¶</a></h2>
<p>The Msg is intended to be used exclusively in code, to build other game systems. It is <em>not</em> a <aclass="reference internal"href="Typeclasses.html"><spanclass="doc std std-doc">Typeclassed</span></a> entity, which means it cannot (easily) be overridden. It doesn’t support Attributes (but it <em>does</em> support <aclass="reference internal"href="Tags.html"><spanclass="doc std std-doc">Tags</span></a>). It tries to be lean and small since a new one is created for every message.
You create a new message with <codeclass="docutils literal notranslate"><spanclass="pre">evennia.create_message</span></code>:</p>
<h3>Properties on Msg<aclass="headerlink"href="#properties-on-msg"title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">senders</span></code> - there must always be at least one sender. This is a set of</p></li>
or <codeclass="docutils literal notranslate"><spanclass="pre">str</span></code> in any combination (but usually a message only targets one type).
Using a <codeclass="docutils literal notranslate"><spanclass="pre">str</span></code> for a sender indicates it’s an ‘external’ sender and
and can be used to point to a sender that is not a typeclassed entity. This is not used by default
and what this would be depends on the system (it could be a unique id or a
python-path, for example). While most systems expect a single sender, it’s
possible to have any number of them.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">receivers</span></code> - these are the ones to see the Msg. These are again any combination of
<aclass="reference internal"href="Accounts.html"><spanclass="doc std std-doc">Account</span></a>, <aclass="reference internal"href="Objects.html"><spanclass="doc std std-doc">Object</span></a> or <aclass="reference internal"href="Scripts.html"><spanclass="doc std std-doc">Script</span></a> or <codeclass="docutils literal notranslate"><spanclass="pre">str</span></code> (an ‘external’ receiver).
It’s in principle possible to have zero receivers but most usages of Msg expects one or more.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">header</span></code> - this is an optional text field that can contain meta-information about the message. For
an email-like system it would be the subject line. This can be independently searched, making
this a powerful place for quickly finding messages.</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> - this is auto-set to the time the Msg was created (and thus presumably sent).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locks</span></code> - the Evennia <aclass="reference internal"href="Locks.html"><spanclass="doc std std-doc">lock handler</span></a>. Use with <codeclass="docutils literal notranslate"><spanclass="pre">locks.add()</span></code> etc and check locks with <codeclass="docutils literal notranslate"><spanclass="pre">msg.access()</span></code>
like for all other lockable entities. This can be used to limit access to the contents
of the Msg. The default lock-type to check is <codeclass="docutils literal notranslate"><spanclass="pre">'read'</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">hide_from</span></code> - this is an optional list of <aclass="reference internal"href="Accounts.html"><spanclass="doc std std-doc">Accounts</span></a> or <aclass="reference internal"href="Objects.html"><spanclass="doc std std-doc">Objects</span></a> that
will not see this Msg. This relationship is available mainly for optimization
reasons since it allows quick filtering of messages not intended for a given
target.</p></li>
</ul>
</section>
</section>
<sectionid="tempmsg">
<h2>TempMsg<aclass="headerlink"href="#tempmsg"title="Permalink to this headline">¶</a></h2>
<p><aclass="reference internal"href="../api/evennia.comms.models.html#evennia.comms.models.TempMsg"title="evennia.comms.models.TempMsg"><spanclass="xref myst py py-class">evennia.comms.models.TempMsg</span></a> is an object that implements the same API as the regular <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code>, but which has no database component (and thus cannot be searched). It’s meant to plugged into systems expecting a <codeclass="docutils literal notranslate"><spanclass="pre">Msg</span></code> but where you just want to process the message without saving it.</p>
