diff --git a/docs/source/Concepts/Messagepath.md b/docs/source/Concepts/Messagepath.md index cacd8754b0..d2938ed7e8 100644 --- a/docs/source/Concepts/Messagepath.md +++ b/docs/source/Concepts/Messagepath.md @@ -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. diff --git a/docs/source/Concepts/Protocols.md b/docs/source/Concepts/Protocols.md index 72e5c4f073..2664e390ef 100644 --- a/docs/source/Concepts/Protocols.md +++ b/docs/source/Concepts/Protocols.md @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/source/Contribs/Contrib-Character-Creator.md b/docs/source/Contribs/Contrib-Character-Creator.md index 08c9d68f70..b7594da2e8 100644 --- a/docs/source/Contribs/Contrib-Character-Creator.md +++ b/docs/source/Contribs/Contrib-Character-Creator.md @@ -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 diff --git a/docs/source/Contribs/Contribs-Guidelines.md b/docs/source/Contribs/Contribs-Guidelines.md index 8a5d2501d4..2f6d42e48c 100644 --- a/docs/source/Contribs/Contribs-Guidelines.md +++ b/docs/source/Contribs/Contribs-Guidelines.md @@ -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 diff --git a/docs/source/Contribs/Contribs-Overview.md b/docs/source/Contribs/Contribs-Overview.md index 1ac15ddbaa..164e16ca17 100644 --- a/docs/source/Contribs/Contribs-Overview.md +++ b/docs/source/Contribs/Contribs-Overview.md @@ -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)