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

Taking pass cleaning up docs

Browse source
This commit is contained in:
Griatch 2022-11-19 20:24:11 +01:00
parent 2f2dada10b
commit 68b87d6157
19 changed files with 116 additions and 269 deletions
Download patch file Download diff file Expand all files Collapse all files

27
docs/source/.vale/write-good/README.md
View file

@ -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.
```

2
docs/source/Coding/Changelog.md
View file

@ -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

39
docs/source/Components/Components-Overview.md
View file

@ -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
```
```

10
docs/source/Components/Portal-And-Server.md
View file

@ -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.
The Server and Portal are glued together via an AMP (Asynchronous Messaging Protocol) connection. This allows the two programs to communicate seamlessly.

3
docs/source/Components/Server.md
View file

@ -1,3 +0,0 @@
# Server component
TODO: This is currently in [Portal-and-Server](./Portal-And-Server.md).

51
docs/source/Components/Webclient.md
View file

@ -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. <enter> key or mouse clicking the arrow will send the currently
typed text.
* `default_in.js` Defines onKeydown. `<enter>` 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:
<script src={% static "webclient/js/plugins/myplugin.js" %} language="javascript"
type="text/javascript"></script>
```
Remember, plugins are load-order dependent, so make sure the new `<script>` tag comes before the
goldenlayout.js
Remember, plugins are load-order dependent, so make sure the new `<script>` tag comes before the `goldenlayout.js`.
Next, create a new plugin file `mygame/web/static/webclient/js/plugins/myplugin.js` and
edit it.
@ -294,6 +281,6 @@ let myplugin = (function () {
})();
window.plugin_handler.add("myplugin", myplugin);
```
You can then add "mycomponent" to an item's componentName in your goldenlayout_default_config.js.
You can then add "mycomponent" to an item's `componentName` in your `goldenlayout_default_config.js`.
Make sure to stop your server, evennia collectstatic, and restart your server. Then make sure to clear your browser cache before loading the webclient page.

43
docs/source/Concepts/Soft-Code.md
View file

@ -1,12 +1,7 @@
# Soft Code
Softcode is a very simple programming language that was created for in-game development on TinyMUD
derivatives such as MUX, PennMUSH, TinyMUSH, and RhostMUSH. The idea is that by providing a stripped
down, minimalistic language for in-game use, you can allow quick and easy building and game
development to happen without having to learn C/C++. There is an added benefit of not having to have
to hand out shell access to all developers, and permissions can be used to alleviate many security
problems.
Softcode is a very simple programming language that was created for in-game development on TinyMUD derivatives such as MUX, PennMUSH, TinyMUSH, and RhostMUSH. The idea is that by providing a stripped down, minimalistic language for in-game use, you can allow quick and easy building and game development to happen without having to learn C/C++. There is an added benefit of not having to have to hand out shell access to all developers, and permissions can be used to alleviate many security problems.
Writing and installing softcode is done through a MUD client. Thus it is not a formatted language.
Each softcode function is a single line of varying size. Some functions can be a half of a page long
@ -47,27 +42,15 @@ If you are still curious about how Softcode works, take a look at some external
## Problems with Softcode
Softcode is excellent at what it was intended for: *simple things*. It is a great tool for making an
interactive object, a room with ambiance, simple global commands, simple economies and coded
systems. However, once you start to try to write something like a complex combat system or a higher
end economy, you're likely to find yourself buried under a mountain of functions that span multiple
objects across your entire code.
Softcode is excellent at what it was intended for: *simple things*. It is a great tool for making an interactive object, a room with ambiance, simple global commands, simple economies and coded systems. However, once you start to try to write something like a complex combat system or a higher end economy, you're likely to find yourself buried under a mountain of functions that span multiple objects across your entire code.
Not to mention, softcode is not an inherently fast language. It is not compiled, it is parsed with
each calling of a function. While MUX and MUSH parsers have jumped light years ahead of where they
once were they can still stutter under the weight of more complex systems if not designed properly.
Not to mention, softcode is not an inherently fast language. It is not compiled, it is parsed with each calling of a function. While MUX and MUSH parsers have jumped light years ahead of where they once were they can still stutter under the weight of more complex systems if not designed properly.
## Changing Times
Now that starting text-based games is easy and an option for even the most technically inarticulate,
new projects are a dime a dozen. People are starting new MUDs every day with varying levels of
commitment and ability. Because of this shift from fewer, larger, well-staffed games to a bunch of
small, one or two developer games, some of the benefit of softcode fades.
Now that starting text-based games is easy and an option for even the most technically inarticulate, new projects are a dime a dozen. People are starting new MUDs every day with varying levels of commitment and ability. Because of this shift from fewer, larger, well-staffed games to a bunch of small, one or two developer games, some of the benefit of softcode fades.
Softcode is great in that it allows a mid to large sized staff all work on the same game without
stepping on one another's toes. As mentioned before, shell access is not necessary to develop a MUX
or a MUSH. However, now that we are seeing a lot more small, one or two-man shops, the issue of
shell access and stepping on each other's toes is a lot less.
Softcode is great in that it allows a mid to large sized staff all work on the same game without stepping on one another's toes. As mentioned before, shell access is not necessary to develop a MUX or a MUSH. However, now that we are seeing a lot more small, one or two-man shops, the issue of shell access and stepping on each other's toes is a lot less.
## Our Solution
@ -75,20 +58,10 @@ Evennia shuns in-game softcode for on-disk Python modules. Python is a popular,
professional programming language. You code it using the conveniences of modern text editors.
Evennia developers have access to the entire library of Python modules out there in the wild - not
to mention the vast online help resources available. Python code is not bound to one-line functions
on objects but complex systems may be organized neatly into real source code modules, sub-modules,
or even broken out into entire Python packages as desired.
on objects but complex systems may be organized neatly into real source code modules, sub-modules, or even broken out into entire Python packages as desired.
So what is *not* included in Evennia is a MUX/MOO-like online player-coding system. Advanced coding
in Evennia is primarily intended to be done outside the game, in full-fledged Python modules.
Advanced building is best handled by extending Evennia's command system with your own sophisticated
building commands. We feel that with a small development team you are better off using a
professional source-control system (svn, git, bazaar, mercurial etc) anyway.
So what is *not* included in Evennia is a MUX/MOO-like online player-coding system. Advanced coding in Evennia is primarily intended to be done outside the game, in full-fledged Python modules. Advanced building is best handled by extending Evennia's command system with your own sophisticated building commands. We feel that with a small development team you are better off using a professional source-control system (svn, git, bazaar, mercurial etc) anyway.
## Your Solution
Adding advanced and flexible building commands to your game is easy and will probably be enough to
satisfy most creative builders. However, if you really, *really* want to offer online coding, there
is of course nothing stopping you from adding that to Evennia, no matter our recommendations. You
could even re-implement MUX' softcode in Python should you be very ambitious. The
[in-game-python](../Contribs/Contrib-Ingame-Python.md) is an optional
pseudo-softcode plugin aimed at developers wanting to script their game from inside it.
Adding advanced and flexible building commands to your game is easy and will probably be enough to satisfy most creative builders. However, if you really, *really* want to offer online coding, there is of course nothing stopping you from adding that to Evennia, no matter our recommendations. You could even re-implement MUX' softcode in Python should you be very ambitious. The [in-game-python](../Contribs/Contrib-Ingame-Python.md) is an optional pseudo-softcode plugin aimed at developers wanting to script their game from inside it.

10
docs/source/Concepts/Using-MUX-as-a-Standard.md
View file

@ -1,15 +1,9 @@
# Using MUX as a Standard
Evennia allows for any command syntax. If you like the way DikuMUDs, LPMuds or MOOs handle things,
you could emulate that with Evennia. If you are ambitious you could even design a whole new style,
perfectly fitting your own dreams of the ideal game.
Evennia allows for any command syntax. If you like the way DikuMUDs, LPMuds or MOOs handle things, you could emulate that with Evennia. If you are ambitious you could even design a whole new style, perfectly fitting your own dreams of the ideal game.
We do offer a default however. The default Evennia setup tends to *resemble*
[MUX2](https://www.tinymux.org/), and its cousins [PennMUSH](https://www.pennmush.org),
[TinyMUSH](https://github.com/TinyMUSH/TinyMUSH/wiki), and [RhostMUSH](http://www.rhostmush.com/).
While the reason for this similarity is partly historical, these codebases offer very mature feature
sets for administration and building.
We do offer a default however. The default Evennia setup tends to *resemble* [MUX2](https://www.tinymux.org/), and its cousins [PennMUSH](https://www.pennmush.org), [TinyMUSH](https://github.com/TinyMUSH/TinyMUSH/wiki), and [RhostMUSH](http://www.rhostmush.com/). While the reason for this similarity is partly historical, these codebases offer very mature feature sets for administration and building.
Evennia is *not* a MUX system though. It works very differently in many ways. For example, Evennia
deliberately lacks an online softcode language (a policy explained on our [softcode policy

21
docs/source/Contributing.md
View file

@ -6,14 +6,13 @@ If you cannot find what you are looking for in the documentation, here's what to
you are working on, make a post to the [discussions forum][forum].
- If you want more direct discussions with developers and other users, drop
into our very friendly [Discord channel][chat].
- If you think the documentation is not clear enough, create a [documentation issue][issues]
- If you think the documentation is not clear enough, create a [documentation issue][issues].
- If you have trouble with a missing feature or a problem you think is a bug,
[request or report it][issues].
[request, or report it][issues].
## Community and Spreading the word
Being active and helpful in the [forums][forum] or [chat][chat] is already a big
help.
Being active and helpful in the [discssion forums][forum] or [chat][chat] is already a big help.
Consider writing about Evennia on your blog or in your favorite (relevant)
forum. Write a review somewhere (good or bad, we like feedback either way). Rate
@ -27,8 +26,7 @@ great help!
- Easiest is to just [report documentation issues][issues] as you find them. If
we don't know about them, we can't fix them!
- If you want to help edit the docs directly, [check here](./Contributing-Docs.md)
on how to do it.
- If you want to help editing the docs directly, [check here](./Contributing-Docs.md) on how to do it.
- If you have knowledge to share, how about writing a new [Tutorial](Howtos/Howtos-Overview.md)?
## Helping with code
@ -36,7 +34,7 @@ great help!
If you find bugs, or have a feature-request, [make an issue][issues] for it. If
it's not in an issue, the issue will most likely be forgotten.
Even if you don't feel confident with tackling a [bug or feature][issues], just
Even if you don't feel confident with tackling a bug or feature, just
correcting typos, adjusting formatting or simply *using* the thing and reporting
when stuff doesn't make sense helps us a lot.
@ -51,18 +49,15 @@ when stuff doesn't make sense helps us a lot.
The most elegant way to contribute code to Evennia is to use GitHub to create a
*fork* of the Evennia repository and make your changes to that. Refer to the
[Forking Evennia](Coding/Version-Control.md#forking-evennia) version control instructions
for detailed instructions.
[Forking Evennia](Coding/Version-Control.md#forking-evennia) version control instructions for detailed instructions.
Once you have a fork set up, you can not only work on your own game in a
separate branch, you can also commit your fixes to Evennia itself.
- Make separate branches for all Evennia additions you do - don't edit your
local `master` or `develop` branches directly. It will make your life a lot
easier.
local `master` or `develop` branches directly. It will make your life a lot easier.
- If you have a change that you think is suitable for the main Evennia
repository, issue a [Pull Request][pullrequest]. This will let Evennia
devs know you have stuff to share.
repository, issue a [Pull Request][pullrequest]. This will let Evennia devs know you have stuff to share.
- Bug fixes should generally be done against the `master` branch of Evennia,
while new features/contribs should go into the `develop` branch. If you are
unsure, just pick one and we'll figure it out.

81
docs/source/Evennia-Introduction.md
View file

@ -14,8 +14,7 @@ your mind for years ... you know *just* how good it would be, if you could only
reality. We know how you feel. That is, after all, why Evennia came to be.
Evennia is a MU\*-building system: a bare-bones Python codebase and server intended to
be highly extendable for any style of game. "Bare-bones" in this context means that we try to impose
as few game-specific things on you as possible. For convenience offer basic building
be highly extendable for any style of game. "Bare-bones" in this context means that we try to impose as few game-specific things on you as possible. For convenience offer basic building
blocks like objects, characters, rooms, default commands for building and administration etc, we
don't prescribe any combat rules, mob AI, races, skills, character classes or other things that will
be different from game to game anyway.
@ -26,21 +25,11 @@ Evennia is *fully persistent*, that means things you drop on the ground somewher
there a dozen server reboots later. Through Django we support a large variety of different database
systems (a database is created for you automatically if you use the defaults).
We also include a growing list of *optional* [contribs](Contribs/Contribs-Overview.md) you can use for your game
would you want something to build from.
We also include a growing list of *optional* [contribs](Contribs/Contribs-Overview.md) you can use for your game would you want something to build from.
Using the full power of Python throughout the server offers some distinct advantages. All your
coding, from object definitions and custom commands to AI scripts and economic systems is done in
normal Python modules rather than some ad-hoc scripting language. The fact that you script the game
in the same high-level language that you code it in allows for very powerful and custom game
implementations indeed.
Using the full power of Python throughout the server offers some distinct advantages. All your coding, from object definitions and custom commands to AI scripts and economic systems is done in normal Python modules rather than some ad-hoc scripting language. The fact that you script the game in the same high-level language that you code it in allows for very powerful and custom game implementations indeed.
Out of the box, Evennia gives you a 'talker'-type of game; you can walk around, chat, build rooms and objects,
do basic roleplaying and administration. The server ships with a default set of player commands that are
similar to the MUX command set. We *do not* aim specifically to be a MUX server, but we had to pick some
default to go with (see [this](Concepts/Soft-Code.md) for more about our original motivations). It's easy to
remove or add commands, or to have the command syntax mimic other systems, like Diku, LP, MOO and so on.
Or why not create a new and better command system of your own design.
Out of the box, Evennia gives you a 'talker'-type of game; you can walk around, chat, build rooms and objects, do basic roleplaying and administration. The server ships with a default set of player commands that are similar to the MUX command set. We *do not* aim specifically to be a MUX server, but we had to pick some default to go with (see [this](Concepts/Soft-Code.md) for more about our original motivations). It's easy to remove or add commands, or to have the command syntax mimic other systems, like Diku, LP, MOO and so on. Or why not create a new and better command system of your own design.
## Can I test it somewhere?
@ -59,36 +48,20 @@ you need to know depending on your skills and needs.
### I don't know (or don't want to do) any programming - I just want to run a game!
Evennia comes with a default set of commands for the Python newbies and for those who need to get a
game running *now*. Stock Evennia is enough for running a simple 'Talker'-type game - you can build
and describe rooms and basic objects, have chat channels, do emotes and other things suitable for a
social or free-form MU\*. Combat, mobs and other game elements are not included, so you'll have a
very basic game indeed if you are not willing to do at least *some* coding.
Evennia comes with a default set of commands for the Python newbies and for those who need to get a game running *now*. Stock Evennia is enough for running a simple 'Talker'-type game - you can build and describe rooms and basic objects, have chat channels, do emotes and other things suitable for a social or free-form MU\*. Combat, mobs and other game elements are not included, so you'll have a very basic game indeed if you are not willing to do at least *some* coding.
### I know basic Python, or I am willing to learn
Evennia's source code is extensively documented and is [viewable
online](https://github.com/evennia/evennia). We also have a comprehensive [online
manual](https://evennia.com/docs) with lots of examples. But while Python is
considered a very easy programming language to get into, you do have a learning curve to climb if
you are new to programming. Evennia's [Starting-tutorial](Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) has a [basic introduction
to Python](Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Python-basic-introduction.md) but you should probably also sit down
with a full Python beginner's tutorial at some point (there are plenty of them on
the web if you look around). See also our [link
page](./Links.md) for some reading suggestions. To efficiently code your dream game in
Evennia you don't need to be a Python guru, but you do need to be able to read example code
containing at least these basic Python features:
Evennia's source code is [extensively documented](https://www.evennia.com/docs/latest). But while Python is considered a very easy programming language to get into, you do have a learning curve to climb if you are new to programming. Evennia's [Starting-tutorial](Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) has a [basic introduction to Python](Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Python-basic-introduction.md) but you should probably also sit down with a full Python beginner's tutorial at some point (there are plenty of them on the web if you look around). See also our [link page](./Links.md) for some reading suggestions.
To code your dream game in Evennia you don't need to be a Python guru, but you do need to be able to read example code containing at least these basic Python features:
- Importing and using python [modules](https://docs.python.org/3.7/tutorial/modules.html)
- Using [variables](https://www.tutorialspoint.com/python/python_variable_types.htm), [conditional
statements](https://docs.python.org/tutorial/controlflow.html#if-statements),
[loops](https://docs.python.org/tutorial/controlflow.html#for-statements) and
[functions](https://docs.python.org/tutorial/controlflow.html#defining-functions)
- Using [lists, dictionaries and list
comprehensions](https://docs.python.org/tutorial/datastructures.html)
- Using [variables](https://www.tutorialspoint.com/python/python_variable_types.htm), [conditional statements](https://docs.python.org/tutorial/controlflow.html#if-statements),
[loops](https://docs.python.org/tutorial/controlflow.html#for-statements) and [functions](https://docs.python.org/tutorial/controlflow.html#defining-functions)
- Using [lists, dictionaries and list comprehensions](https://docs.python.org/tutorial/datastructures.html)
- Doing [string handling and formatting](https://docs.python.org/tutorial/introduction.html#strings)
- Have a basic understanding of [object-oriented
programming](https://www.tutorialspoint.com/python/python_classes_objects.htm), using
- Have a basic understanding of [object-oriented programming](https://www.tutorialspoint.com/python/python_classes_objects.htm), using
[Classes](https://docs.python.org/tutorial/classes.html), their methods and properties
Obviously, the more things you feel comfortable with, the easier time you'll have to find your way.
@ -98,35 +71,13 @@ definitely build a whole advanced and customized game from extending Evennia's e
### I know my Python stuff and I am willing to use it!
Even if you started out as a Python beginner, you will likely get to this point after working on
your game for a while. With more general knowledge in Python the full power of Evennia opens up for
you. Apart from modifying commands, objects and scripts, you can develop everything from advanced
mob AI and economic systems, through sophisticated combat and social mini games, to redefining how
commands, players, rooms or channels themselves work. Since you code your game by importing normal
Python modules, there are few limits to what you can accomplish.
Even if you started out as a Python beginner, you will likely get to this point after working on your game for a while. With more general knowledge in Python the full power of Evennia opens up for you. Apart from modifying commands, objects and scripts, you can develop everything from advanced mob AI and economic systems, through sophisticated combat and social mini games, to redefining how commands, players, rooms or channels themselves work. Since you code your game by importing normal Python modules, there are few limits to what you can accomplish.
If you *also* happen to know some web programming (HTML, CSS, Javascript) there is also a web
presence (a website and a mud web client) to play around with ...
### Where to from here?
## Where to from here?
From here you can continue browsing the [online documentation](./index.md) to
find more info about Evennia. Or you can jump into the [Tutorials](Howtos/Howtos-Overview.md) and get your hands
dirty with code right away. You can also read the lead developer's [dev blog](https://evennia.blogspot.com/) for many tidbits and snippets about Evennia's development and
structure.
It's recommended you jump into the [Beginner Tutorial](Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md). You can either follow it or jump around to lessons that seem interesting. You can also read the lead developer's [dev blog](https://www.evennia.com/devblog/index.html) for many tidbits and snippets about Evennia's development and structure.
Some more hints:
1. Get engaged in the community. Make an introductory post to our [mailing
list/forum](https://groups.google.com/forum/#!forum/evennia) and get to know people. It's also
highly recommended you hop onto our [Developer
chat](https://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb)
on IRC. This allows you to chat directly with other developers new and old as well as with the devs
of Evennia itself. This chat is logged (you can find links on https://www.evennia.com) and can also
be searched from the same place for discussion topics you are interested in.
2. Read the [Game Planning](Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Game-Planning.md) wiki page. It gives some ideas for your work flow and the
state of mind you should aim for - including cutting down the scope of your game for its first
release.
3. Do the [Tutorial for basic MUSH-like game](Howtos/Tutorial-for-basic-MUSH-like-game.md) carefully from
beginning to end and try to understand what does what. Even if you are not interested in a MUSH for
your own game, you will end up with a small (very small) game that you can build or learn from.
Sometimes it's easier to ask for help. Get engaged in the Evennia community by joining our [Discord](https://discord.gg/AJJpcRUhtF) for direct support. Make an introductory post to our [Discussion forum](https://github.com/evennia/evennia/discussions) and say hi!.

2
docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.md
View file

@ -2,7 +2,7 @@
In this lesson we will test out what we can do in-game out-of-the-box. Evennia ships with
[around 90 default commands](../../../Components/Default-Commands.md), and while you can override those as you please,
they can be quite useful.
the defaults can be quite useful.
Connect and log into your new game and you will end up in the "Limbo" location. This
is the only room in the game at this point. Let's explore the commands a little.

4
docs/source/Setup/Installation-Troubleshooting.md
View file

@ -26,7 +26,7 @@ everything in the following sections.
## Confusion of location (GIT installation)
When doing the [Git installation](Installation-Git), some may be confused and install Evennia in the wrong location. After following the instructions (and using a virtualenv), the folder structure should look like this:
When doing the [Git installation](./Installation-Git.md), some may be confused and install Evennia in the wrong location. After following the instructions (and using a virtualenv), the folder structure should look like this:
```
muddev/
@ -83,7 +83,7 @@ If `localhost` doesn't work when trying to connect to your local game, try `127.
## Windows Troubleshooting
- If you install with `pip install evennia` and find that the `evennia` command is not available, run `py -m evennia` once. This should add the evennia binary to your environment. If this fails, make sure you are using a [virtualenv](Installation-Git#virtualenv). Worst case, you can keep using `py -m evennia` in the places where the `evennia` command is used.
- If you install with `pip install evennia` and find that the `evennia` command is not available, run `py -m evennia` once. This should add the evennia binary to your environment. If this fails, make sure you are using a [virtualenv](./Installation-Git.md#virtualenv). Worst case, you can keep using `py -m evennia` in the places where the `evennia` command is used.
- Install Python [from the Python homepage](https://www.python.org/downloads/windows/). You will need to be a Windows Administrator to install packages.
- When installing Python, make sure to check-mark *all* install options, especially the one about making Python available on the path (you may have to scroll to see it). This allows you to
just write `python` in any console without first finding where the `python` program actually sits on your hard drive.

4
docs/source/Setup/Installation-Upgrade.md
View file

@ -1,6 +1,6 @@
# Upgrading an existing installation
This is relevant to you already having code in an older Evennia version. If you are new, or don't have much code yet, it may be easier to just start fresh with the [Installation](Installation) instructions and copy
This is relevant to you already having code in an older Evennia version. If you are new, or don't have much code yet, it may be easier to just start fresh with the [Installation](./Installation.md) instructions and copy
over things manually.
## Evennia v0.9.5 to 1.0
@ -15,7 +15,7 @@ assume that you have a cloned `evennia` repo and use a virtualenv (best practice
- Make a _backup_ of your entire `mygame` folder, just to be sure!
- Install Python 3.11 (recommended). Follow the [Git-installation](./Installation-Git.md) for your OS if needed.
- Delete the old virtualenv `evenv` folder, or rename it (in case you want to keep using 0.9.5 for a while).
- Make _new_ `evenv` virtualenv (see the [virtualenv instructions](Installation-Git#virtualenv) for help)
- Make _new_ `evenv` virtualenv (see the [virtualenv instructions](./Installation-Git.md#virtualenv) for help)
- `cd` into your `evennia/` root folder (you want to see the `docs/` and `bin/` directories as well as a nested `evennia/` folder)
- `git pull`
- `pip install -e .`

33
docs/source/Setup/Installation.md
View file

@ -8,9 +8,9 @@ Installing Evennia doesn't make anything visible online. Apart from installation
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended)
- Windows: In the installer, make sure you select `add python to path`. If you have multiple versions of Python installed, use `py` command instead of `python` to have Windows automatically use the latest.
- Using a light-weight [Python virtual environment](Installation-Git#virtualenv) _ is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. This comes with Python.
- Using a light-weight [Python virtual environment](./Installation-Git.md#virtualenv) is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. Using virtualenvs is common Python praxis.
- Don't install Evennia as administrator or superuser.
- If you run into trouble, see [installation troubleshooting](Installation-Troubleshooting).
- If you run into trouble, see [installation troubleshooting](./Installation-Troubleshooting.md).
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python, you install Evennia with
@ -25,23 +25,23 @@ To update Evennia later, do
pip install --upgrade evennia
Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a virtualenv, make sure it's active whenever you need to use the `evennia` command.
> Windows users only: You now need to run `python -m evennia` once. This should permanently make the `evennia` command available in your environment.
Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a virtualenv, make sure it's active whenever you need to use the `evennia` command later.
> You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Initialize a new game
> Windows users: You need to first run `python -m evennia` once. This should permanently add the evennia launcher to your environment, making the `evennia` command available.
Use `cd` to enter a folder where you want to do your game development. Here (and in
the rest of the Evennia documentation) we call this folder `mygame`, but you should of course
name your game whatever you like.
We will create a new "game dir" for you do create your game in. Here (and in
the rest of the Evennia documentation) we refer to this game dir as `mygame`, but you should of course name your game whatever you like.
evennia --init mygame
This will create a new folder `mygame` (or whatever you chose) in your current location. This
contains empty templates and all the default settings needed to start the server.
> The game dir doesn't need to have the exact same name as your game. You can set the name of your game later by editing `mygame/server/conf/settings.py`.
## Start the new game
@ -52,7 +52,7 @@ This will create the default database (Sqlite3). The database file ends up as `m
evennia start
Set your user-name and password when prompted. This will be the "god user" or "superuser" in-game. The email is optional.
Set your user-name and password when prompted. This will be the "god user" or "super user" in-game. The email is optional.
> You can also [automate](./Installation-Non-Interactive.md) the creation of the super user.
@ -76,6 +76,8 @@ Full stop of the server (use `evennia start` to restart):
evennia stop
See [Server start-stop-reload](./Start-Stop-Reload.md) page for more details.
## See server logs
Log files are in `mygame/server/logs`. You can tail them live with
@ -92,21 +94,20 @@ You can start viewing the log immediately by adding `-l/--log` to `evennia` comm
evennia start -l
## Server configuration
The server configuration file is `mygame/server/settings.py`. It's empty by default. Copy and change only the settings you want from the [default settings file](./Settings-Default.md).
The server configuration file is `mygame/server/settings.py`. It's empty by default. Copy and change only the settings you want from the [default settings file](./Settings-Default.md). See the [Settings](./Settings.md) documentation for more info.
## Register with the Evennia Game Index (optional)
You can let the world know that you are working on a new Evennia-based game by
registering your server with the _Evennia game index_. You don't have to be
open for players to do this - you just mark your game as closed and "pre-alpha".
registering your server with the _Evennia game index_.
evennia connections
See [here](./Evennia-Game-Index.md) for more instructions and please [check out the index](http:games.evennia.com)
beforehand to make sure you don't pick a game name that is already taken - be nice!
Just follow the prompts. You don't have to be open for players to do this - you just mark your game as closed and "pre-alpha".
See [here](./Evennia-Game-Index.md) for more instructions and please [check out the index](http:games.evennia.com) beforehand to make sure you don't pick a game name that is already taken - be nice!
## The Next steps

2
docs/source/Setup/Settings.md
View file

@ -1,4 +1,4 @@
# Game Settings and Configuration direcotry
# Game Settings and Configuration directory
Evennia runs out of the box without any changes to its settings. But there are several important
ways to customize the server and expand it with your own plugins.

2
docs/source/Setup/Setup-Overview.md
View file

@ -17,7 +17,7 @@ Installation-Non-Interactive
Start-Stop-Reload
```
## Configuring
## Settings and configuration
```{toctree}
:maxdepth: 2

42
docs/source/Setup/Start-Stop-Reload.md
View file

@ -6,7 +6,7 @@ program. If the `evennia` program is not available on the command line you must
Evennia as described on the [Installation](./Installation.md) page.
```{sidebar} evennia not found?
If you ever try the `evennia` command and get an error complaining that the command is not available, make sure your [virtualenv](../Glossary.md#virtualenv) is active.
If you ever try the `evennia` command and get an error complaining that the command is not available, make sure your [virtualenv](../Glossary.md#virtualenv) is active. On Windows you may need to to run `py -m evennia` once first.
```
Below are described the various management options. Run
@ -21,11 +21,7 @@ to give you a menu with options.
## Starting Evennia
Evennia consists of two components, the Evennia [Portal and Server](../Components/Portal-And-Server.md). Briefly,
the *Server* is what is running the mud. It handles all game-specific things but doesn't care
exactly how players connect, only that they have. The *Portal* is a gateway to which players
connect. It knows everything about telnet, ssh, webclient protocols etc but very little about the
game. Both are required for a functioning mud.
Evennia consists of two components, the Evennia [Portal and Server](../Components/Portal-And-Server.md). Briefly, the *Server* is what is running the mud. It handles all game-specific things but doesn't care exactly how players connect, only that they have. The *Portal* is a gateway to which players connect. It knows everything about telnet, ssh, webclient protocols etc but very little about the game. Both are required for a functioning game.
evennia start
@ -37,40 +33,32 @@ Will start following the logs of an already running server. When starting Evenni
evennia start -l
> To stop viewing the log files, press `Ctrl-C`.
> To stop viewing the log files, press `Ctrl-C` (`Cmd-C` on Mac).
## Reloading
The act of *reloading* means the Portal will tell the Server to shut down and then boot it back up
again. Everyone will get a message and the game will be briefly paused for all accounts as the
server
reboots. Since they are connected to the *Portal*, their connections are not lost.
The act of *reloading* means the Portal will tell the Server to shut down and then boot it back up again. Everyone will get a message and the game will be briefly paused for all accounts as the server reboots. Since they are connected to the *Portal*, their connections are not lost.
Reloading is as close to a "warm reboot" you can get. It reinitializes all code of Evennia, but
doesn't kill "persistent" [Scripts](../Components/Scripts.md). It also calls `at_server_reload()` hooks on all
objects so you
can save eventual temporary properties you want.
Reloading is as close to a "warm reboot" you can get. It reinitializes all code of Evennia, but doesn't kill "persistent" [Scripts](../Components/Scripts.md). It also calls `at_server_reload()` hooks on all objects so you can save eventual temporary properties you want.
From in-game the `@reload` command is used. You can also reload the server from outside the game:
From in-game the `reload` command is used. You can also reload the server from outside the game:
evennia reload
Sometimes reloading from "the outside" is necessary in case you have added some sort of bug that
blocks in-game input.
Sometimes reloading from "the outside" is necessary in case you have added some sort of bug that blocks in-game input.
## Stopping
A full shutdown closes Evennia completely, both Server and Portal. All accounts will be booted and
systems saved and turned off cleanly.
From inside the game you initiate a shutdown with the `@shutdown` command. From command line you do
From inside the game you initiate a shutdown with the `shutdown` command. From command line you do
evennia stop
You will see messages of both Server and Portal closing down. All accounts will see the shutdown
message and then be disconnected. The same effect happens if you press `Ctrl+C` while the server
runs in interactive mode.
message and then be disconnected.
## Foreground mode
@ -89,15 +77,14 @@ will start/restart the *Server* in interactive mode. This is required if you wan
will start the *Portal* in interactive mode.
If you do `Ctrl-C`/`Cmd-C` in foreground mode, the component will stop. You'll need to run `evennia start` to get the game going again.
## Resetting
*Resetting* is the equivalent of a "cold reboot" - the Server will shut down and then restarted
again, but will behave as if it was fully shut down. As opposed to a "real" shutdown, no accounts
will be disconnected during a
reset. A reset will however purge all non-persistent scripts and will call `at_server_shutdown()`
hooks. It can be a good way to clean unsafe scripts during development, for example.
again, but will behave as if it was fully shut down. As opposed to a "real" shutdown, no accounts will be disconnected during a reset. A reset will however purge all non-persistent scripts and will call `at_server_shutdown()` hooks. It can be a good way to clean unsafe scripts during development, for example.
From in-game the `@reset` command is used. From the terminal:
From in-game the `reset` command is used. From the terminal:
evennia reset
@ -170,8 +157,7 @@ related to Evennia:
During development, you will usually modify code and then reload the server to see your changes.
This is done by Evennia re-importing your custom modules from disk. Usually bugs in a module will
just have you see a traceback in the game, in the log or on the command line. For some really
serious syntax errors though, your module might not even be recognized as valid Python. Evennia may
then fail to restart correctly.
serious syntax errors though, your module might not even be recognized as valid Python. Evennia may then fail to restart correctly.
From inside the game you see a text about the Server restarting followed by an ever growing list of
"...". Usually this only lasts a very short time (up to a few seconds). If it seems to go on, it

7
docs/source/index.md
View file

@ -11,16 +11,17 @@
# Evennia Documentation
This is the manual of [Evennia](https://www.evennia.com), the open source Python
`MU*` creation system.
`MU*` creation system. Use the Searchbar on the left to discover interesting articles.
- [Evennia Introduction](./Evennia-Introduction.md)
- [How to contribute and get help](./Contributing.md)
## Setup
- [Installation](Setup/Installation.md)
- [Installation](Setup/Installation.md#installation-running)
- [Starting, Stopping and Reloading](Setup/Start-Stop-Reload.md) - how to manage the Evennia server
- [Configurations](Setup/Setup-Overview.md) - how to run, maintain and release
- [Settings and configurations](Setup/Setup-Overview.md#configuring) - how to configure the server and integrations
- [Going public](Setup/Setup-Overview.md#going-public) - taking your game online
## Howtos and Tutorials

2
evennia/contrib/rpg/character_creator/README.md
View file

@ -1,4 +1,4 @@
# Character Creator contrib
# Character Creator
Commands for managing and initiating an in-game character-creation menu.