<p>If you haven’t, you should be familiar with the <aclass="reference internal"href="Messagepath.html"><spanclass="doc std std-doc">Messagepath</span></a>, which describes how a message enters and leaves Evennia and how along the way, all messages are converted to a generic format called a <codeclass="docutils literal notranslate"><spanclass="pre">commandtuple</span></code>:</p>
<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 to.</p>
<p>The keyword becomes the command-name part of the <codeclass="docutils literal notranslate"><spanclass="pre">commandtuple</span></code> and the value its <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code> parts. You can also send multiple messages of different <codeclass="docutils literal notranslate"><spanclass="pre">commandname</span></code>s at the same time.</p>
<p>A special case is the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> call. It’s so common that it’s the default of the <codeclass="docutils literal notranslate"><spanclass="pre">msg</span></code> method. So these are equivalent:</p>
<p>You don’t have to specify the full <codeclass="docutils literal notranslate"><spanclass="pre">commandtuple</span></code> 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>
<h3>Which command-names can I send?<aclass="headerlink"href="#which-command-names-can-i-send"title="Permalink to this headline">¶</a></h3>
<p>This depends on the client and protocol. If you use the Evennia <aclass="reference internal"href="../Components/Webclient.html"><spanclass="doc std std-doc">webclient</span></a>, you can modify it to have it support whatever command-names you like.</p>
<p>Many third-party MUD clients support a range of OOB protocols listed below. If a client does not support a particular OOB instruction/command, Evennia will just send the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> command to them and quietly drop all other OOB instructions.</p>
<div><p>Note 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> OOB messages always reaching all targets.</p>
<h3>Which command-names can I receive<aclass="headerlink"href="#which-command-names-can-i-receive"title="Permalink to this headline">¶</a></h3>
<p>This is decided by which <aclass="reference internal"href="../Components/Inputfuncs.html"><spanclass="doc std std-doc">Inputfuncs</span></a> you define. You can extend Evennia’s default as you like, but adding your own functions in a module pointed to by <codeclass="docutils literal notranslate"><spanclass="pre">settings.INPUT_FUNC_MODULES</span></code>.</p>
<p>By default telnet (and telnet+SSL) supports only the plain <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> outputcommand. Evennia detects if the Client supports one of two MUD-specific OOB <em>extensions</em> to the standard telnet protocol - GMCP or MSDP. Evennia supports both simultaneously and will switch to the protocol the client uses. If the client supports both, GMCP will be used.</p>
<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 translations described below.</p>
<p><aclass="reference external"href="https://www.gammon.com.au/gmcp">GMCP</a>, the <em>Generic Mud Communication Protocol</em> sends data on the 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 versa.</p>
<p>On the wire, the <codeclass="docutils literal notranslate"><spanclass="pre">commandtuple</span></code></p>
<p>where all the capitalized words are telnet character constants specified in ]<spanclass="xref myst">evennia/server/portal/telnet_oob</span>. These are parsed/added by the protocol and we don’t include these in the listings below.</p>
<p>Since Evennia already supplies default Inputfuncs that don’t match the names expected by the most common GMCP implementations we have a few hard-coded mappings for those:</p>
<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 like this:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>IAC SB MSDP VAR cmdname VAL arg IAC SE
</pre></div>
</div>
<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>
<p>Observe that <codeclass="docutils literal notranslate"><spanclass="pre">VAR</span><spanclass="pre">...</span><spanclass="pre">VAL</span></code> always identifies <codeclass="docutils literal notranslate"><spanclass="pre">cmdnames</span></code>, 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>
</section>
</section>
<sectionid="ssh">
<h3>SSH<aclass="headerlink"href="#ssh"title="Permalink to this headline">¶</a></h3>
<p>SSH only supports the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> input/outputcommand.</p>
</section>
<sectionid="web-client">
<h3>Web client<aclass="headerlink"href="#web-client"title="Permalink to this headline">¶</a></h3>
<p>Our web client uses pure <aclass="reference external"href="https://en.wikipedia.org/wiki/JSON">JSON</a> 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.</p>
