Updated ReST documentation.

docs/sphinx/source/wiki/SessionProtocols.rst

@@ -236,6 +236,72 @@ Loop over all relevant sessions. The Server will treat this like a
 Portal call and data will be sent back to be handled by the portal as
 normal.
 
+Adding custom Protocols
+=======================
+
+Evennia has a plugin-system that allows you to add new custom Protocols
+without editing any files in ``src/``. To do this you need to add the
+protocol as a new "service" to the application.
+
+Take a look at for example ``src/server/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
+``src/server.server.py``.
+
+To add a new service of your own (for example your own custom client
+protocol) to e.g. the Portal, create a new module in
+``game/gamesrc/conf/``. Let's call it ``myproc_plugin.py``. We need to
+tell the Server or Portal that they need to import this module. In
+``game/settings.py``, add one of the following:
+
+::
+
+    # add to the Server
+    SERVER_SERVICES_PLUGIN_MODULES.append('game.gamesrc.conf.myproc_plugin')
+    # or, if you want to add to the Portal
+    PORTAL_SERVICES_PLUGIN_MODULES.append('game.gamesrc.conf.myproc_plugin')
+
+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 application itself so
+the custom service can be added to it. The function should not return
+anything.
+
+This is how it can look:
+
+::
+
+    # game/gamesrc/conf/myproc_plugin.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
+    MY_PORT = 6666
+
+    def start_plugin_services(portal):
+        "This is called by the Portal during startup"
+         if not MYPROC_ENABLED:
+             return 
+         # output to list this with the other services at startup
+         print "  myproc: %s" % MY_PORT
+
+         # some setup (simple example)
+         factory = MyOwnFactory()
+         my_service = internet.TCPServer(MY_PORT, factory)
+         # all Evennia services must be uniquely named
+         my_service.setName("MyService")
+         # add to the main portal application
+         portal.services.addService(my_service)
+
+One the module is defined and targeted in settings, just reload the
+server and your new protocol/services should start with the others.
+
 Assorted notes
 ==============