Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-02 14:07:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Fixed all links

Browse source
This commit is contained in:
Griatch 2020-10-11 19:31:05 +02:00
parent d4f1733bc7
commit 26f8ba3f71
175 changed files with 11972 additions and 4443 deletions
Download patch file Download diff file Expand all files Collapse all files

93
docs/source/Custom-Protocols.md
View file

@ -5,27 +5,32 @@
their own custom client protocol.*
A [PortalSession](./Sessions#Portal-and-Server-Sessions) is the basic data object representing an external
A [PortalSession](./Sessions#Portal-and-Server-Sessions) is the basic data object representing an
external
connection to the Evennia [Portal](./Portal-And-Server) -- 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
*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 <->
You <->
Protocol + PortalSession <->
PortalSessionHandler <->
(AMP) <->
(AMP) <->
ServerSessionHandler <->
ServerSession <->
InputFunc
InputFunc
```
(See the [Message Path](./Messagepath) 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).
(See the [Message Path](./Messagepath) 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
@ -47,7 +52,8 @@ modules, you could do the following:
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`.
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
@ -93,27 +99,30 @@ Writing a stable communication protocol from scratch is not something we'll cove
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.
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:
Here's a example to show the concept:
```python
# In module that we'll later add to the system through PORTAL_SERVICE_PLUGIN_MODULES
# pseudo code
# pseudo code
from twisted.something import TwistedClient
# this class is used both for Portal- and Server Sessions
from evennia.server.session import Session
from evennia.server.session import Session
from evennia.server.portal.portalsessionhandler import PORTAL_SESSIONS
class MyCustomClient(TwistedClient, Session):
class MyCustomClient(TwistedClient, Session):
def __init__(self, *args, **kwargs):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.sessionhandler = PORTAL_SESSIONS
# these are methods we must know that TwistedClient uses for
# these are methods we must know that TwistedClient uses for
# communication. Name and arguments could vary for different Twisted protocols
def onOpen(self, *args, **kwargs):
# let's say this is called when the client first connects
@ -131,39 +140,39 @@ class MyCustomClient(TwistedClient, Session):
# link to the Evennia equivalent
self.disconnect(reason)
def onMessage(self, indata, *args, **kwargs):
def onMessage(self, indata, *args, **kwargs):
# called with incoming data
# convert as needed here
self.data_in(data=indata)
# convert as needed here
self.data_in(data=indata)
def sendMessage(self, outdata, *args, **kwargs):
# called to send data out
# modify if needed
# modify if needed
super().sendMessage(self, outdata, *args, **kwargs)
# these are Evennia methods. They must all exist and look exactly like this
# The above twisted-methods call them and vice-versa. This connects the protocol
# the Evennia internals.
# the Evennia internals.
def disconnect(self, reason=None):
def disconnect(self, reason=None):
"""
Called when connection closes.
Called when connection closes.
This can also be called directly by Evennia when manually closing the connection.
Do any cleanups here.
"""
self.sessionhandler.disconnect(self)
def at_login(self):
def at_login(self):
"""
Called when this session authenticates by the server (if applicable)
"""
"""
def data_in(self, **kwargs):
"""
Data going into the server should go through this method. It
Data going into the server should go through this method. It
should pass data into `sessionhandler.data_in`. THis will be called
by the sessionhandler with the data it gets from the approrpriate
send_* method found later in this protocol.
by the sessionhandler with the data it gets from the approrpriate
send_* method found later in this protocol.
"""
self.sessionhandler.data_in(self, text=kwargs['data'])
@ -175,38 +184,46 @@ class MyCustomClient(TwistedClient, Session):
# we assume we have a 'text' outputfunc
self.onMessage(kwargs['text'])
# 'outputfuncs' are defined as `send_<outputfunc_name>`. From in-code, they are called
# with `msg(outfunc_name=<data>)`.
# 'outputfuncs' are defined as `send_<outputfunc_name>`. From in-code, they are called
# with `msg(outfunc_name=<data>)`.
def send_text(self, txt, *args, **kwargs):
def send_text(self, txt, *args, **kwargs):
"""
Send text, used with e.g. `session.msg(text="foo")`
"""
# we make use of the
# we make use of the
self.data_out(text=txt)
def send_default(self, cmdname, *args, **kwargs):
def send_default(self, cmdname, *args, **kwargs):
"""
Handles all outputfuncs without an explicit `send_*` method to handle them.
"""
self.data_out(**{cmdname: str(args)})
```
The principle here is that the Twisted-specific methods are overridden to redirect inputs/outputs to the Evennia-specific methods.
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.
To send data out through this protocol, you'd need to get its Session and then you could e.g.
```python
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 in our case means sending "foo" across the network.
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
### Receiving data
Just because the protocol is there, does not mean Evennia knows what to do with it. An [Inputfunc](./Inputfuncs) 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](./Inputfuncs) page for how to do this.
Just because the protocol is there, does not mean Evennia knows what to do with it. An
[Inputfunc](./Inputfuncs) 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](./Inputfuncs) 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
@ -219,4 +236,4 @@ websockets. You'll find that whereas telnet is a textbook example of a Twisted p
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.
ways.