-
-

Custom Protocols

-

Note: This is considered an advanced topic and is mostly of interest to users planning to implement -their own custom client protocol.

-

A PortalSession is the basic data object representing an -external -connection to the Evennia Portal – 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 Protocol. The most common such protocol for MUD:s is the -Telnet protocol. All Portal Sessions are stored and managed by the Portal’s sessionhandler.

-

It’s technically sometimes hard to separate the concept of PortalSession from the concept of -Protocol 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

-
# In the Portal
-You <-> 
-  Protocol + PortalSession <-> 
-    PortalSessionHandler <->
-      (AMP) <-> 
-        ServerSessionHandler <->
-          ServerSession <->
-            InputFunc  
+  

+
Protocols

+
            Internet│ Protocol
+            ┌─────┐ │ | 
+┌──────┐    │Text │ │  ┌──────────┐    ┌────────────┐   ┌─────┐
+│Client◄────┤JSON ├─┼──┤outputfunc◄────┤commandtuple◄───┤msg()│
+└──────┘    │etc  │ │  └──────────┘    └────────────┘   └─────┘
+            └─────┘ │
+                    │Evennia
 

 

-
(See the Message Path 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 Protocol + PortalSession
-(which translates between data coming in/out over the wire to/from Evennia internal representation)
-as well as the InputFunc (which handles incoming data).

-

-
Adding custom Protocols

+
The Protocol describes how Evennia sends and receives data over the wire to the client. Each connection-type (telnet, ssh, webclient etc) has its own protocol. Some protocols may also have variations (such plain-text Telnet vs Telnet SSL).

+
See the Message Path for the bigger picture of how data flows through Evennia.

+
In Evennia, the PortalSession represents the client connection. The session is told to use a particular protocol. When sending data out, the session must provide an “Outputfunc” to convert the generic commandtuple to a form the protocol understands. For ingoing data, the server must also provide suitable Inputfuncs to handle the instructions sent to the server.

+

+
Adding a new Protocol

 
Evennia has a plugin-system that add the protocol as a new “service” to the application.

-
Take a look at evennia/server/portal/portal.py, 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 evennia/server/server.py).

-
To add a new service of your own (for example your own custom client protocol) to the Portal or
-Server, look at  mygame/server/conf/server_services_plugins and portal_services_plugins. 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:

+
To add a new service of your own (for example your own custom client protocol) to the Portal or Server, expand  mygame/server/conf/server_services_plugins and portal_services_plugins.

+
To expand where Evennia looks for plugins, use the following settings:

 
    # add to the Server
     SERVER_SERVICES_PLUGIN_MODULES.append('server.conf.my_server_plugins')
     # or, if you want to add to the Portal
     PORTAL_SERVICES_PLUGIN_MODULES.append('server.conf.my_portal_plugins')
 

 

-
When adding a new connection you’ll most likely only need to add new things to the
-PORTAL_SERVICES_PLUGIN_MODULES.

-
This module can contain whatever you need to define your protocol, but it must contain a function
-start_plugin_services(app). This is called by the Portal as part of its upstart. The function
-start_plugin_services must contain all startup code the server need.  The app argument is a
-reference to the Portal/Server application itself so the custom service can be added to it. The
-function should not return anything.

-
This is how it looks:

+

+
When adding a new client connection you’ll most likely only need to add new things to the Portal-plugin files.

+

+
The plugin module must contain a function start_plugin_services(app), where the app arguments refers to the Portal/Server application itself. This is called by the Server or Portal when it starts up. It must contatin all startup code needed.

+
Example:

 
    # mygame/server/conf/portal_services_plugins.py
 
     # here the new Portal Twisted protocol is defined
     class MyOwnFactory( ... ):
-       [...]
+       # [...]
 
     # some configs
     MYPROC_ENABLED = True # convenient off-flag to avoid having to edit settings all the time
@@ -189,14 +167,14 @@ function should not return anything.

 

 
Once the module is defined and targeted in settings, just reload the server and your new
 protocol/services should start with the others.

-

 

-
Writing your own Protocol

-
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.

-
Writing a protocol implementation in Twisted usually involves creating a class inheriting from an
-already existing Twisted protocol class and from evennia.server.session.Session (multiple
+
Writing your own Protocol

+

+
Important

+
This is considered an advanced topic.

+

+
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.

+
Writing a protocol implementation in Twisted usually involves creating a class inheriting from an already existing Twisted protocol class and from evennia.server.session.Session (multiple
 inheritance), then overloading the methods that particular protocol uses to link them to the
 Evennia-specific inputs.

 
Here’s a example to show the concept:

@@ -297,38 +275,22 @@ Evennia-specific inputs.

The principle here is that the Twisted-specific methods are overridden to redirect inputs/outputs to the Evennia-specific methods.

+

Sending data out

To send data out through this protocol, you’d need to get its Session and then you could e.g.

    session.msg(text="foo")
-

The message will pass through the system such that the sessionhandler will dig out the session and -check if it has a send_text method (it has). It will then pass the “foo” into that method, which +

The message will pass through the system such that the sessionhandler will dig out the session and check if it has a send_text method (it has). It will then pass the “foo” into that method, which in our case means sending “foo” across the network.

Receiving data

-

Just because the protocol is there, does not mean Evennia knows what to do with it. An -Inputfunc must exist to receive it. In the case of the text 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 -Inputfunc page for how to do this.

-

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 Portal Session, which is the actual common -interface between the different low-level protocols and Evennia.

+

Just because the protocol is there, does not mean Evennia knows what to do with it. An Inputfunc must exist to receive it. In the case of the text 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 Inputfunc page for how to do this.

+

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 Portal Session, which is the actual common interface between the different low-level protocols and Evennia.

-
-

Assorted notes

-

To take two examples, Evennia supports the telnet protocol as well as webclient, 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 -ways.

-
@@ -354,7 +316,7 @@ ways.

>previous |