‘OOB message’ as far as Evennia is concerned). The message follows the <aclass="reference internal"href="Messagepath.html"><spanclass="doc std std-doc">Message Path</span></a>.
<aclass="reference internal"href="../Components/Inputfuncs.html"><spanclass="doc std std-doc">Inputfunc</span></a>. This function is called as <codeclass="docutils literal notranslate"><spanclass="pre">cmdname(session,</span><spanclass="pre">*args,</span><spanclass="pre">**kwargs)</span></code> where
<codeclass="docutils literal notranslate"><spanclass="pre">session</span></code> is the Session-source of the command. Inputfuncs can easily be added by the developer to
support/map client commands to actions inside Evennia (see the <aclass="reference internal"href="../Components/Inputfuncs.html"><spanclass="doc std std-doc">inputfunc</span></a> page for more
<p>Sending is simple. You just use the normal <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> method of the object whose session you want to send
<p>A special case is the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> input/outputfunc. It’s so common that it’s the default of the <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code>
<p>You don’t have to specify the full output/input definition. So for example, if your particular
command only needs kwargs, you can skip the <codeclass="docutils literal notranslate"><spanclass="pre">(args)</span></code> part. Like in the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> case you can skip
writing the tuple if there is only one arg … and so on - the input is pretty flexible. If there
are no args at all you need to give the empty tuple <codeclass="docutils literal notranslate"><spanclass="pre">msg(cmdname=(,)</span></code> (giving <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> would mean a
single argument <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code>).</p>
<p>Which commands you can send depends on the client. If the client does not support an explicit OOB
protocol (like many old/legacy MUD clients) Evennia can only send <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> to them and will quietly
<div><p>Remember that a given message may go to multiple clients with different capabilities. So unless
you turn off telnet completely and only rely on the webclient, you should never rely on non-<codeclass="docutils literal notranslate"><spanclass="pre">text</span></code>
<p><aclass="reference internal"href="../Components/Inputfuncs.html"><spanclass="doc std std-doc">Inputfuncs</span></a> lists the default inputfuncs available to handle incoming OOB messages. To
<div><p>Note that for Telnet, <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> has a special status as the “in-band” operation. So the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code>
outputcommand sends the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> argument directly over the wire, without going through the OOB
form <codeclass="docutils literal notranslate"><spanclass="pre">cmdname</span><spanclass="pre">+</span><spanclass="pre">JSONdata</span></code>. Here the cmdname is expected to be on the form “Package.Subpackage”.
There could also be additional Sub-sub packages etc. The names of these ‘packages’ and ‘subpackages’
are not that well standardized beyond what individual MUDs or companies have chosen to go with over
the years. You can decide on your own package names, but here are what others are using:</p>
<p>Evennia will translate underscores to <codeclass="docutils literal notranslate"><spanclass="pre">.</span></code> and capitalize to fit the specification. So the
outputcommand <codeclass="docutils literal notranslate"><spanclass="pre">foo_bar</span></code> will become a GMCP command-name <codeclass="docutils literal notranslate"><spanclass="pre">Foo.Bar</span></code>. A GMCP command “Foo.Bar” will be
come <codeclass="docutils literal notranslate"><spanclass="pre">foo_bar</span></code>. To send a GMCP command that turns into an Evennia inputcommand without an
underscore, use the <codeclass="docutils literal notranslate"><spanclass="pre">Core</span></code> package. So <codeclass="docutils literal notranslate"><spanclass="pre">Core.Cmdname</span></code> becomes just <codeclass="docutils literal notranslate"><spanclass="pre">cmdname</span></code> in Evennia and vice
<p>On the wire, a GMCP instruction for <codeclass="docutils literal notranslate"><spanclass="pre">("cmdname",</span><spanclass="pre">("arg",),</span><spanclass="pre">{})</span></code> will look like this:</p>
<p>where all the capitalized words are telnet character constants specified in
<codeclass="docutils literal notranslate"><spanclass="pre">evennia/server/portal/telnet_oob.py</span></code>. These are parsed/added by the protocol and we don’t include
<p><aclass="reference external"href="http://tintin.sourceforge.net/msdp/">MSDP</a>, the <em>Mud Server Data Protocol</em>, is a competing standard
to GMCP. The MSDP protocol page specifies a range of “recommended” available MSDP command names.
Evennia does <em>not</em> support those - since MSDP doesn’t specify a special format for its command names
(like GMCP does) the client can and should just call the internal Evennia inputfunc by its actual
name.</p>
<p>MSDP uses Telnet character constants to package various structured data over the wire. MSDP supports
strings, arrays (lists) and tables (dicts). These are used to define the cmdname, args and kwargs
needed. When sending MSDP for <codeclass="docutils literal notranslate"><spanclass="pre">("cmdname",</span><spanclass="pre">("arg",),</span><spanclass="pre">{})</span></code> the resulting MSDP instruction will look
<p>The various available MSDP constants like <codeclass="docutils literal notranslate"><spanclass="pre">VAR</span></code> (variable), <codeclass="docutils literal notranslate"><spanclass="pre">VAL</span></code> (value), <codeclass="docutils literal notranslate"><spanclass="pre">ARRAYOPEN</span></code>/<codeclass="docutils literal notranslate"><spanclass="pre">ARRAYCLOSE</span></code>
and <codeclass="docutils literal notranslate"><spanclass="pre">TABLEOPEN</span></code>/<codeclass="docutils literal notranslate"><spanclass="pre">TABLECLOSE</span></code> are specified in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/server/portal/telnet_oob</span></code>.</p>
<codeclass="docutils literal notranslate"><spanclass="pre">[cmdname,</span><spanclass="pre">[],</span><spanclass="pre">{}]</span></code> | VAR cmdname VAL
<codeclass="docutils literal notranslate"><spanclass="pre">[cmdname,</span><spanclass="pre">[arg],</span><spanclass="pre">{}]</span></code> | VAR cmdname VAL arg
<codeclass="docutils literal notranslate"><spanclass="pre">[cmdname,</span><spanclass="pre">[args],{}]</span></code> | VAR cmdname VAL ARRAYOPEN VAL arg VAL arg … ARRAYCLOSE
<codeclass="docutils literal notranslate"><spanclass="pre">[cmdname,</span><spanclass="pre">[],</span><spanclass="pre">{kwargs}]</span></code> | VAR cmdname VAL TABLEOPEN VAR key VAL val … TABLECLOSE
<codeclass="docutils literal notranslate"><spanclass="pre">[cmdname,</span><spanclass="pre">[args],</span><spanclass="pre">{kwargs}]</span></code> | VAR cmdname VAL ARRAYOPEN VAL arg VAL arg … ARRAYCLOSE VAR cmdname
VAL TABLEOPEN VAR key VAL val … TABLECLOSE</p>
<p>Observe that <codeclass="docutils literal notranslate"><spanclass="pre">VAR</span><spanclass="pre">...</span><spanclass="pre">VAL</span></code> always identifies cmdnames, so if there are multiple arrays/dicts tagged
with the same cmdname they will be appended to the args, kwargs of that inputfunc. Vice-versa, a
different <codeclass="docutils literal notranslate"><spanclass="pre">VAR</span><spanclass="pre">...</span><spanclass="pre">VAL</span></code> (outside a table) will come out as a second, different command input.</p>
<p>Our web client uses pure JSON structures for all its communication, including <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code>. This maps
directly to the Evennia internal output/inputcommand, including eventual empty args/kwargs. So the
same example <codeclass="docutils literal notranslate"><spanclass="pre">("cmdname",</span><spanclass="pre">("arg",),</span><spanclass="pre">{})</span></code> will be sent/received as a valid JSON structure</p>
