diff --git a/docs/source/.vale/write-good/README.md b/docs/source/.vale/write-good/README.md deleted file mode 100644 index 3edcc9b376..0000000000 --- a/docs/source/.vale/write-good/README.md +++ /dev/null @@ -1,27 +0,0 @@ -Based on [write-good](https://github.com/btford/write-good). - -> Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too. - -``` -The MIT License (MIT) - -Copyright (c) 2014 Brian Ford - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. -``` diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index 4f0286b25f..c0cca561fb 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -5,7 +5,7 @@ > Not released yet > 2019-2022 develop branch (WIP) -Up requirements to Django 4.0+, Twisted 22+, Python 3.9 or 3.10 +Increase requirements: Django 4.1+, Twisted 22.10+ Python 3.9, 3.10, 3.11. PostgreSQL 11+. - New `drop:holds()` lock default to limit dropping nonsensical things. Access check defaults to True for backwards-compatibility in 0.9, will be False in 1.0 diff --git a/docs/source/Components/Components-Overview.md b/docs/source/Components/Components-Overview.md index a0cc25688b..0f42a4a34a 100644 --- a/docs/source/Components/Components-Overview.md +++ b/docs/source/Components/Components-Overview.md @@ -2,7 +2,9 @@ These are the 'building blocks' out of which Evennia is built. This documentation is complementary to, and often goes deeper than, the doc-strings of each component in the [API](../Evennia-API.md). -## Database entites +## Basic entites + +These are base pieces used to make an Evennia game. Most are long-lived and are persisted in the database. ```{toctree} :maxdepth: 2 @@ -20,11 +22,13 @@ Tags.md Prototypes.md Help-System.md Permissions.md - +Portal-And-Server.md ``` ## Commands +Evennia's Command system handle everything sent to the server by the user. + ```{toctree} :maxdepth: 2 @@ -36,11 +40,15 @@ Connection-Screen.md Batch-Processors.md Batch-Code-Processor.md Batch-Command-Processor.md +Inputfuncs.md +Outputfuncs.md ``` ## Utils and tools +Evennia provides a library of code resources to help the creation of a game. + ```{toctree} :maxdepth: 2 @@ -59,30 +67,15 @@ Signals.md ## Web components +Evennia is also its own webserver, with a website and in-browser webclient you can expand on. + ```{toctree} :maxdepth: 2 Website.md -Web-API.md -Web-Admin.md -``` - -## Server and network - -```{toctree} -:maxdepth: 2 - -Portal-And-Server.md -Inputfuncs.md -Outputfuncs.md -Server.md -Setup/Server-Conf.md -Webserver.md Webclient.md +Web-Admin.md +Webserver.md +Web-API.md Bootstrap-Components-and-Utilities.md -Signals.md -``` - - - - +``` \ No newline at end of file diff --git a/docs/source/Components/Portal-And-Server.md b/docs/source/Components/Portal-And-Server.md index eaf134242c..afb9ef40ef 100644 --- a/docs/source/Components/Portal-And-Server.md +++ b/docs/source/Components/Portal-And-Server.md @@ -4,12 +4,8 @@ Evennia consists of two processes, known as *Portal* and *Server*. They can be controlled from inside the game or from the command line as described [here](../Setup/Start-Stop-Reload.md). -If you are new to the concept, the main purpose of separating the two is to have accounts connect to -the Portal but keep the MUD running on the Server. This way one can restart/reload the game (the -Server part) without Accounts getting disconnected. +If you are new to the concept, the main purpose of separating the two is to have accounts connect to the Portal but keep the MUD running on the Server. This way one can restart/reload the game (the Server part) without Accounts getting disconnected. -![portal and server layout](https://474a3b9f-a-62cb3a1a-s- -sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia_server_portal.png) +![portal and server layout](https://474a3b9f-a-62cb3a1a-s- sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia_server_portal.png) -The Server and Portal are glued together via an AMP (Asynchronous Messaging Protocol) connection. -This allows the two programs to communicate seamlessly. \ No newline at end of file +The Server and Portal are glued together via an AMP (Asynchronous Messaging Protocol) connection. This allows the two programs to communicate seamlessly. \ No newline at end of file diff --git a/docs/source/Components/Server.md b/docs/source/Components/Server.md deleted file mode 100644 index 05ca0ca3ab..0000000000 --- a/docs/source/Components/Server.md +++ /dev/null @@ -1,3 +0,0 @@ -# Server component - -TODO: This is currently in [Portal-and-Server](./Portal-And-Server.md). \ No newline at end of file diff --git a/docs/source/Components/Webclient.md b/docs/source/Components/Webclient.md index ea24a81972..2505566d7d 100644 --- a/docs/source/Components/Webclient.md +++ b/docs/source/Components/Webclient.md @@ -42,7 +42,7 @@ Example: To change the list of in-use plugins, you need to override base.html by `evennia/web/templates/webclient/base.html` to `mygame/web/templates/webclient/base.html` and editing it to add your new plugin. -# Evennia Web Client API (from evennia.js) +## Evennia Web Client API (from evennia.js) * `Evennia.init( opts )` * `Evennia.connect()` * `Evennia.isConnected()` @@ -50,14 +50,14 @@ Example: To change the list of in-use plugins, you need to override base.html by * `Evennia.emit( cmdname, args, kwargs )` * `log()` -# Plugin Manager API (from webclient_gui.js) +## Plugin Manager API (from webclient_gui.js) * `options` Object, Stores key/value 'state' that can be used by plugins to coordinate behavior. * `plugins` Object, key/value list of the all the loaded plugins. * `plugin_handler` Object * `plugin_handler.add("name", plugin)` * `plugin_handler.onSend(string)` -# Plugin callbacks API +## Plugin callbacks API * `init()` -- The only required callback * `boolean onKeydown(event)` This plugin listens for Keydown events * `onBeforeUnload()` This plugin does something special just before the webclient page/tab is @@ -79,21 +79,19 @@ their callback for this event called. This enables things like the up/down arro history.js plugin to always occur before the default_in.js plugin adds that key to the current input buffer. -# Example/Default Plugins (plugins/*.js) +### Example/Default Plugins (`plugins/*.js`) + * `clienthelp.js` Defines onOptionsUI from the options2 plugin. This is a mostly empty plugin to add some "How To" information for your game. -* `default_in.js` Defines onKeydown. key or mouse clicking the arrow will send the currently -typed text. +* `default_in.js` Defines onKeydown. `` key or mouse clicking the arrow will send the currently typed text. * `default_out.js` Defines onText, onPrompt, and onUnknownCmd. Generates HTML output for the user. * `default_unload.js` Defines onBeforeUnload. Prompts the user to confirm that they meant to leave/close the game. * `font.js` Defines onOptionsUI. The plugin adds the ability to select your font and font size. * `goldenlayout_default_config.js` Not actually a plugin, defines a global variable that goldenlayout uses to determine its window layout, known tag routing, etc. -* `goldenlayout.js` Defines onKeydown, onText and custom functions. A very powerful "tabbed" window -manager for drag-n-drop windows, text routing and more. -* `history.js` Defines onKeydown and onSend. Creates a history of past sent commands, and uses arrow -keys to peruse. +* `goldenlayout.js` Defines onKeydown, onText and custom functions. A very powerful "tabbed" window manager for drag-n-drop windows, text routing and more. +* `history.js` Defines onKeydown and onSend. Creates a history of past sent commands, and uses arrow keys to peruse. * `hotbuttons.js` Defines onGotOptions. A Disabled-by-default plugin that defines a button bar with user-assignable commands. * `html.js` A basic plugin to allow the client to handle "raw html" messages from the server, this @@ -104,32 +102,22 @@ window for a side-by-side web/text interface, mostly an example of how to build * `message_routing.js` Defines onOptionsUI, onText, onKeydown. This goldenlayout-only plugin implements regex matching to allow users to "tag" arbitrary text that matches, so that it gets routed to proper windows. Similar to "Spawn" functions for other clients. -* `multimedia.js` An basic plugin to allow the client to handle "image" "audio" and "video" messages -from the server and display them as inline HTML. +* `multimedia.js` An basic plugin to allow the client to handle "image" "audio" and "video" messages from the server and display them as inline HTML. * `notifications.js` Defines onText. Generates browser notification events for each new message while the tab is hidden. * `oob.js` Defines onSend. Allows the user to test/send Out Of Band json messages to the server. * `options.js` Defines most callbacks. Provides a popup-based UI to coordinate options settings with the server. -* `options2.js` Defines most callbacks. Provides a goldenlayout-based version of the options/settings tab. -Integrates with other plugins via the custom onOptionsUI callback. +* `options2.js` Defines most callbacks. Provides a goldenlayout-based version of the options/settings tab. Integrates with other plugins via the custom onOptionsUI callback. * `popups.js` Provides default popups/Dialog UI for other plugins to use. -* `text2html.js` Provides a new message handler type: `text2html`, similar to the multimedia and html -plugins. This plugin provides a way to offload rendering the regular pipe-styled ASCII messages -to the client. This allows the server to do less work, while also allowing the client a place to -customize this conversion process. To use this plugin you will need to override the current commands -in Evennia, changing any place where a raw text output message is generated and turn it into a -`text2html` message. For example: `target.msg("my text")` becomes: `target.msg(text2html=("my text"))` -(even better, use a webclient pane routing tag: `target.msg(text2html=("my text", {"type": "sometag"}))`) -`text2html` messages should format and behave identically to the server-side generated text2html() output. +* `text2html.js` Provides a new message handler type: `text2html`, similar to the multimedia and html plugins. This plugin provides a way to offload rendering the regular pipe-styled ASCII messages to the client. This allows the server to do less work, while also allowing the client a place to customize this conversion process. To use this plugin you will need to override the current commands in Evennia, changing any place where a raw text output message is generated and turn it into a `text2html` message. For example: `target.msg("my text")` becomes: `target.msg(text2html=("my text"))` (even better, use a webclient pane routing tag: `target.msg(text2html=("my text", {"type": "sometag"}))`) `text2html` messages should format and behave identically to the server-side generated text2html() output. -# A side note on html messages vrs text2html messages +### A side note on html messages vs text2html messages So...lets say you have a desire to make your webclient output more like standard webpages... -For telnet clients, you could collect a bunch of text lines together, with ASCII formatted borders, etc. -Then send the results to be rendered client-side via the text2html plugin. +For telnet clients, you could collect a bunch of text lines together, with ASCII formatted borders, etc. Then send the results to be rendered client-side via the text2html plugin. + +But for webclients, you could format a message directly with the html plugin to render the whole thing as an HTML table, like so: -But for webclients, you could format a message directly with the html plugin to render the whole thing as an -HTML table, like so: ``` # Server Side Python Code: @@ -155,13 +143,13 @@ HTML table, like so: target.msg( html2html=( "\n".join(table), {"type": "mytag"}) ) ``` -# Writing your own Plugins +## Writing your own Plugins So, you love the functionality of the webclient, but your game has specific types of text that need to be separated out into their own space, visually. The Goldenlayout plugin framework can help with this. -## GoldenLayout +### GoldenLayout GoldenLayout is a web framework that allows web developers and their users to create their own tabbed/windowed layouts. Windows/tabs can be click-and-dragged from location to location by @@ -263,8 +251,7 @@ Next, add the new plugin to your copy of base.html: ``` -Remember, plugins are load-order dependent, so make sure the new `