<h1>Custom Protocols<aclass="headerlink"href="#custom-protocols"title="Permalink to this headline">¶</a></h1>
<p><em>Note: This is considered an advanced topic and is mostly of interest to users planning to implement
their own custom client protocol.</em></p>
<p>A <aclass="reference internal"href="../Components/Sessions.html#portal-and-server-sessions"><spanclass="std std-doc">PortalSession</span></a> is the basic data object representing an
external
connection to the Evennia <aclass="reference internal"href="../Components/Portal-And-Server.html"><spanclass="doc std std-doc">Portal</span></a>– usually a human player running a mud client
of some kind. The way they connect (the language the player’s client and Evennia use to talk to
each other) is called the connection <em>Protocol</em>. The most common such protocol for MUD:s is the
<em>Telnet</em> protocol. All Portal Sessions are stored and managed by the Portal’s <em>sessionhandler</em>.</p>
<p>It’s technically sometimes hard to separate the concept of <em>PortalSession</em> from the concept of
<em>Protocol</em> since both depend heavily on the other (they are often created as the same class). When
data flows through this part of the system, this is how it goes</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># In the Portal</span>
<p>(See the <aclass="reference internal"href="Messagepath.html"><spanclass="doc std std-doc">Message Path</span></a> for the bigger picture of how data flows through Evennia). The
parts that needs to be customized to make your own custom protocol is the <codeclass="docutils literal notranslate"><spanclass="pre">Protocol</span><spanclass="pre">+</span><spanclass="pre">PortalSession</span></code>
(which translates between data coming in/out over the wire to/from Evennia internal representation)
as well as the <codeclass="docutils literal notranslate"><spanclass="pre">InputFunc</span></code> (which handles incoming data).</p>
<sectionid="adding-custom-protocols">
<h2>Adding custom Protocols<aclass="headerlink"href="#adding-custom-protocols"title="Permalink to this headline">¶</a></h2>
<p>Evennia has a plugin-system that add the protocol as a new “service” to the application.</p>
<p>Take a look at <codeclass="docutils literal notranslate"><spanclass="pre">evennia/server/portal/portal.py</span></code>, notably the sections towards the end of that file.
These are where the various in-built services like telnet, ssh, webclient etc are added to the
Portal (there is an equivalent but shorter list in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/server/server.py</span></code>).</p>
<p>To add a new service of your own (for example your own custom client protocol) to the Portal or
Server, look at <codeclass="docutils literal notranslate"><spanclass="pre">mygame/server/conf/server_services_plugins</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">portal_services_plugins</span></code>. By
default Evennia will look into these modules to find plugins. If you wanted to have it look for more
modules, you could do the following:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># add to the Server</span>
<p>This module can contain whatever you need to define your protocol, but it <em>must</em> contain a function
<codeclass="docutils literal notranslate"><spanclass="pre">start_plugin_services(app)</span></code>. This is called by the Portal as part of its upstart. The function
<codeclass="docutils literal notranslate"><spanclass="pre">start_plugin_services</span></code> must contain all startup code the server need. The <codeclass="docutils literal notranslate"><spanclass="pre">app</span></code> argument is a
reference to the Portal/Server application itself so the custom service can be added to it. The
<spanclass="n">MYPROC_ENABLED</span><spanclass="o">=</span><spanclass="kc">True</span><spanclass="c1"># convenient off-flag to avoid having to edit settings all the time</span>
<p>Once the module is defined and targeted in settings, just reload the server and your new
protocol/services should start with the others.</p>
</section>
<sectionid="writing-your-own-protocol">
<h2>Writing your own Protocol<aclass="headerlink"href="#writing-your-own-protocol"title="Permalink to this headline">¶</a></h2>
<p>Writing a stable communication protocol from scratch is not something we’ll cover here, it’s no
trivial task. The good news is that Twisted offers implementations of many common protocols, ready
for adapting.</p>
<p>Writing a protocol implementation in Twisted usually involves creating a class inheriting from an
already existing Twisted protocol class and from <codeclass="docutils literal notranslate"><spanclass="pre">evennia.server.session.Session</span></code> (multiple
inheritance), then overloading the methods that particular protocol uses to link them to the
Evennia-specific inputs.</p>
<p>Here’s a example to show the concept:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># In module that we'll later add to the system through PORTAL_SERVICE_PLUGIN_MODULES</span>
<spanclass="c1"># let's say this is called when the client first connects</span>
<spanclass="c1"># we need to init the session and connect to the sessionhandler. The .factory</span>
<spanclass="c1"># is available through the Twisted parents</span>
<spanclass="n">client_address</span><spanclass="o">=</span><spanclass="bp">self</span><spanclass="o">.</span><spanclass="n">getClientAddress</span><spanclass="p">()</span><spanclass="c1"># get client address somehow</span>
<p>The message will pass through the system such that the sessionhandler will dig out the session and
check if it has a <codeclass="docutils literal notranslate"><spanclass="pre">send_text</span></code> method (it has). It will then pass the “foo” into that method, which
in our case means sending “foo” across the network.</p>
</section>
<sectionid="receiving-data">
<h3>Receiving data<aclass="headerlink"href="#receiving-data"title="Permalink to this headline">¶</a></h3>
<p>Just because the protocol is there, does not mean Evennia knows what to do with it. An
<aclass="reference internal"href="../Components/Inputfuncs.html"><spanclass="doc std std-doc">Inputfunc</span></a> must exist to receive it. In the case of the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> input exemplified above,
Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So
handle that you need to simply add a cmdset with commands on your receiving Session (and/or the
Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the
<aclass="reference internal"href="../Components/Inputfuncs.html"><spanclass="doc std std-doc">Inputfunc</span></a> page for how to do this.</p>
<p>These might not be as clear-cut in all protocols, but the principle is there. These four basic
components - however they are accessed - links to the <em>Portal Session</em>, which is the actual common
interface between the different low-level protocols and Evennia.</p>
</section>
</section>
<sectionid="assorted-notes">
<h2>Assorted notes<aclass="headerlink"href="#assorted-notes"title="Permalink to this headline">¶</a></h2>
<p>To take two examples, Evennia supports the <em>telnet</em> protocol as well as <em>webclient</em>, via ajax or
websockets. You’ll find that whereas telnet is a textbook example of a Twisted protocol as seen
above, the ajax protocol looks quite different due to how it interacts with the
webserver through long-polling (comet) style requests. All the necessary parts
mentioned above are still there, but by necessity implemented in very different
