Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 21:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Clean up protocol docs

Browse source
This commit is contained in:
Griatch 2022-11-27 11:38:50 +01:00
parent f2c64e2903
commit 20520d99d5
5 changed files with 36 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/source/Concepts/Messagepath.md
View file

@ -116,7 +116,7 @@ This will be converted to a `commandtuple` looking like this:
### outputfuncs
```{sidebar}
`outputfuncs` are tightly coupled to the protocol and you usually don't need to touch them, unless you are adding a new protocol entirely.
`outputfuncs` are tightly coupled to the protocol and you usually don't need to touch them, unless you are [adding a new protocol](./Protocols.md) entirely.
```
Since `msg()` is aware of which [Session](../Components/Sessions.md) to send to, the outgoing `commandtuple` is always end up pointed at the right client.

103
docs/source/Concepts/Protocols.md
View file

@ -1,50 +1,28 @@
# 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](../Components/Sessions.md#portal-and-server-sessions) is the basic data object representing an
external
connection to the Evennia [Portal](../Components/Portal-And-Server.md) -- 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
# Protocols
```
# In the Portal
You <->
Protocol + PortalSession <->
PortalSessionHandler <->
(AMP) <->
ServerSessionHandler <->
ServerSession <->
InputFunc
Internet│ Protocol
┌─────┐ │ |
┌──────┐ │Text │ │ ┌──────────┐ ┌────────────┐ ┌─────┐
│Client◄────┤JSON ├─┼──┤outputfunc◄────┤commandtuple◄───┤msg()│
└──────┘ │etc │ │ └──────────┘ └────────────┘ └─────┘
└─────┘ │
│Evennia
```
(See the [Message Path](./Messagepath.md) 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).
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).
## Adding custom Protocols
See the [Message Path](./Messagepath.md) 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](../Components/Inputfuncs.md) 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:
```python
# add to the Server
SERVER_SERVICES_PLUGIN_MODULES.append('server.conf.my_server_plugins')
@ -52,23 +30,18 @@ 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 client connection you'll most likely only need to add new things to the Portal-plugin files.
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.
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.
This is how it looks:
Example:
```python
# 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
@ -93,14 +66,15 @@ This is how it looks:
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 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.
```{important}
This is considered an advanced topic.
```
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 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.
@ -212,28 +186,11 @@ To send data out through this protocol, you'd need to get its Session and then y
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](../Components/Inputfuncs.md) 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](../Components/Inputfuncs.md) page for how to do this.
Just because the protocol is there, does not mean Evennia knows what to do with it. An [Inputfunc](../Components/Inputfuncs.md) 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](../Components/Inputfuncs.md) 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.
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.

4
docs/source/Contribs/Contrib-Character-Creator.md
View file

@ -1,9 +1,9 @@
# Character Creator
Commands for managing and initiating an in-game character-creation menu.
Contribution by InspectorCaracal, 2022
Commands for managing and initiating an in-game character-creation menu.
## Installation
In your game folder `commands/default_cmdsets.py`, import and add

2
docs/source/Contribs/Contribs-Guidelines.md
View file

@ -44,7 +44,7 @@ Evennia has a [contrib](./Contribs-Overview.md) directory which contains optiona
It's often a good idea to import useful resources in `__init__.py` to make it easier to import them.
- Your code should abide by the [Evennia Style Guide](../Coding/Evennia-Code-Style.md). Write it to be easy to read.
- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically.
- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically. Use a folder `tests/` to group your tests if there are many of them across multiple modules.
- The `README.md` file will be parsed and converted into a document linked from [the contrib overview page](./Contribs-Overview.md). It needs to be on the following form:
```markdown

4
docs/source/Contribs/Contribs-Overview.md
View file

@ -542,9 +542,9 @@ It is a common design pattern in RPGs, particularly action games.
### `character_creator`
_Commands for managing and initiating an in-game character-creation menu._
_Contribution by InspectorCaracal, 2022_
Contribution by InspectorCaracal, 2022
Commands for managing and initiating an in-game character-creation menu.
[Read the documentation](./Contrib-Character-Creator.md) - [Browse the Code](evennia.contrib.rpg.character_creator)