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

Rounds of doc cleanups

Browse source
This commit is contained in:
Griatch 2022-11-10 23:15:54 +01:00
parent 86686c0d15
commit 4128bc4733
9 changed files with 87 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,7 +1,6 @@
# Core Components
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).
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

2
docs/source/Contribs/Contrib-Menu-Login.md
View file

@ -11,7 +11,7 @@ menu system `EvMenu` under the hood.
To install, add this to `mygame/server/conf/settings.py`:
CMDSET_UNLOGGEDIN = "evennia.contrib.base_systems.menu_login.UnloggedinCmdSet"
CONNECTION_SCREEN_MODULE = "contrib.base_systems.menu_login.connection_screens"
CONNECTION_SCREEN_MODULE = "evennia.contrib.base_systems.menu_login.connection_screens"
Reload the server and reconnect to see the changes.

6
docs/source/Howtos/Howtos-Overview.md
View file

@ -1,10 +1,6 @@
# Tutorials and Howto's
The documents in this section aims to teach how to use Evennia in a tutorial or
a step-by-step way. They often give hints on about solving a problem or implementing
a particular feature or concept. They will often refer to the
[components](../Components/Components-Overview.md) or [concepts](../Concepts/Concepts-Overview.md)
docs for those that want to dive deeper.
All Evennia tutorials. They will often refer to the [components](../Components/Components-Overview.md) or [concepts](../Concepts/Concepts-Overview.md) if you want to dive deeper.
## Beginner Tutorial

3
docs/source/Setup/Installation-Git.md
View file

@ -1,7 +1,6 @@
# Installing with GIT
This installs and runs Evennia from its sources. This is required if you want to contribute to Evennia
itself or have an easier time exploring the code. See the basic [Installation](./Installation.md) for
This installs and runs Evennia from its sources. This is required if you want to contribute to Evennia itself or have an easier time exploring the code. See the basic [Installation](./Installation.md) for
a quick installation of the library. See the [troubleshooting](./Installation-Troubleshooting.md) if you run
into trouble.

2
docs/source/Setup/Installation-Non-Interactive.md
View file

@ -1,6 +1,6 @@
# Non-interactive setup
The first ime you run `evennia start` (just after having created the database), you will be asked
The first time you run `evennia start` (just after having created the database), you will be asked
to interactively insert the superuser username, email and password. If you are deploying Evennia
as part of an automatic build script, you don't want to enter this information manually.

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

@ -1,14 +1,5 @@
# Installation
The Evennia server is installed, run and maintained from the terminal (console/CMD on Windows). Starting the server
doesn't make anything visible online. Once you download everything you can in fact develop your game in complete
isolation if you want, without needing any access to the internet.
Evennia requires [Python](https://www.python.org/downloads/) 3.9 or 3.10.
Using a [Python virtualenv](../Glossary.md#virtualenv) is highly recommended in order to keep your
Evennia installation independent from the system libraries. Don't install Evennia as
administrator or superuser.
```{warning}
pip install evennia is not yet available in develop branch. Use the [git installation](./Installation-Git.md).
```
@ -16,13 +7,24 @@ pip install evennia is not yet available in develop branch. Use the [git install
If you are converting an existing game from a previous version, [see here](./Installation-Upgrade.md).
```
- Evennia requires [Python](https://www.python.org/downloads/) 3.9 or 3.10.
- Using a [Python virtualenv](../Glossary.md#virtualenv) is highly recommended in order to keep your
Evennia installation independent from the system libraries.
- Don't install Evennia as
administrator or superuser.
Evennia is managed from the terminal (console/CMD on Windows). If you have a suitable Python installed, you can install with
pip install 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.
Alternatively, you can [install Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md).
Check out [installation troubleshooting](./Installation-Troubleshooting.md) if you run into problems. Some
Installing doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection.
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.
> Check out [installation troubleshooting](./Installation-Troubleshooting.md) if you run into problems. Some
users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Initialize a new game
@ -42,18 +44,15 @@ contains empty templates and all the default settings needed to start the server
cd mygame
evennia migrate
This will create the default database (Sqlite3). The database file ends up as `mygame/server/evennia.db3`. If you
ever want to start from a fresh database, just delete this file and re-run `evennia migrate` again.
This will create the default database (Sqlite3). The database file ends up as `mygame/server/evennia.db3`. If you ever want to start from a fresh database, just delete this file and re-run `evennia migrate` again.
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 "superuser" in-game. The email is optional.
> You can also [automate](./Installation-Non-Interactive.md) the creation of the super user.
If all went well, the server is now up and running. Point a legacy MUD/telnet client to `localhost:4000` or
a web browser at [http://localhost:4001](http://localhost:4001) to play your new (if empty) game!
If all went well, the server is now up and running. Point a legacy MUD/telnet client to `localhost:4000` or a web browser at [http://localhost:4001](http://localhost:4001) to play your new (if empty) game!
Log in as a new account or use the superuser you just created.
@ -93,8 +92,7 @@ To exit the log tailing, enter `Ctrl-C` (`Cmd-C` for Mac). This will not affect
## 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).
## Register with the Evennia Game Index (optional)
@ -111,10 +109,4 @@ beforehand to make sure you don't pick a game name that is already taken - be ni
You are good to go!
Evennia comes with a small [Tutorial World](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Tutorial-World.md) to experiment and learn from. After logging
in, you can create it by running
batchcommand tutorial_world.build
Next, why not head into the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md)
to learn how to start making your new game!
Next, why not head into the [Starting Tutorial](../Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md) to learn how to start making your new game!

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

@ -1,7 +1,6 @@
# Server Setup and Life
This documentation covers how to setup and maintain the server,
from first install to opening your game to the public.
This sums up all steps of maintaining your Evennia game from first installation to production release.
## Installation & running

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

@ -3,10 +3,11 @@
You control Evennia from your game folder (we refer to it as `mygame/` here), using the `evennia`
program. If the `evennia` program is not available on the command line you must first install
Evennia as described in the [Setup Quickstart](./Installation.md) page.
Evennia as described on the [Installation](./Installation.md) page.
> Hint: 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.
```{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.
```
Below are described the various management options. Run
@ -20,7 +21,7 @@ to give you a menu with options.
## Starting Evennia
Evennia consists of two components, the Evennia [Server and Portal](../Components/Portal-And-Server.md). Briefly,
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
@ -28,10 +29,7 @@ game. Both are required for a functioning mud.
evennia start
The above command will start the Portal, which in turn will boot up the Server. The command will
print a summary of the process and unless there is an error you will see no further output. Both
components will instead log to log files in `mygame/server/logs/`. For convenience you can follow
those logs directly in your terminal by attaching `-l` to commands:
The above command will start the Portal, which in turn will boot up the Server. The command will print a summary of the process and unless there is an error you will see no further output. Both components will instead log to log files in `mygame/server/logs/`. For convenience you can follow those logs directly in your terminal by attaching `-l` to commands:
evennia -l
@ -41,23 +39,6 @@ Will start following the logs of an already running server. When starting Evenni
> To stop viewing the log files, press `Ctrl-C`.
## Foreground mode
Normally, Evennia runs as a 'daemon', in the background. If you want you can start either of the
processes (but not both) as foreground processes in *interactive* mode. This means they will log
directly to the terminal (rather than to log files that we then echo to the terminal) and you can
kill the process (not just the log-file view) with `Ctrl-C`.
evennia istart
will start/restart the *Server* in interactive mode. This is required if you want to run a
*debugger*. Next time you reload the server, it will return to normal mode.
evennia ipstart
will start the *Portal* in interactive mode. This is usually only necessary if you want to run
Evennia under the control of some other type of process.
## Reloading
The act of *reloading* means the Portal will tell the Server to shut down and then boot it back up
@ -78,6 +59,36 @@ From in-game the `@reload` command is used. You can also reload the server from
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
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.
## Foreground mode
Normally, Evennia runs as a 'daemon', in the background. If you want you can start either of the
processes (but not both) as foreground processes in *interactive* mode. This means they will log
directly to the terminal (rather than to log files that we then echo to the terminal) and you can
kill the process (not just the log-file view) with `Ctrl-C`.
evennia istart
will start/restart the *Server* in interactive mode. This is required if you want to run a
[debugger](Debugging). Next time you `evennia reload` the server, it will return to normal mode.
evennia ipstart
will start the *Portal* in interactive mode.
## Resetting
*Resetting* is the equivalent of a "cold reboot" - the Server will shut down and then restarted
@ -103,20 +114,6 @@ This is identical to doing these two commands:
evennia stop
evennia start
## Shutting down
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
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.
## Status and info
To check basic Evennia settings, such as which ports and services are active, this will repeat the
@ -134,7 +131,7 @@ This can be useful for automating checks to make sure the game is running and is
## Killing (Linux/Mac only)
In the extreme case that neither of the server processes locks up and does not respond to commands,
you can send them kill-signals to force them to shut down. To kill only the Server:
[]()you can send them kill-signals to force them to shut down. To kill only the Server:
evennia skill
@ -147,19 +144,17 @@ Note that this functionality is not supported on Windows.
## Django options
The `evennia` program will also pass-through options used by the `django-admin`. These operate on
the database in various ways.
The `evennia` program will also pass-through options used by the `django-admin`. These operate on the database in various ways.
```bash
evennia migrate # migrate the database
evennia shell # launch an interactive, django-aware python shell
evennia dbshell # launch database shell
evennia dbshell # launch the database shell
```
For (many) more options, see [the django-admin
docs](https://docs.djangoproject.com/en/1.7/ref/django-admin/#usage).
For (many) more options, see [the django-admin docs](https://docs.djangoproject.com/en/1.7/ref/django-admin/#usage).
## Advanced handling of Evennia processes
@ -168,10 +163,7 @@ such as Linux' `top` or the more advanced `htop`), you will find the following p
related to Evennia:
* 1 x `twistd ... evennia/server/portal/portal.py` - this is the Portal process.
* 3 x `twistd ... server.py` - One of these processes manages Evennia's Server component, the main
game. The other processes (with the same name but different process id) handle's Evennia's
internal web server threads. You can look at `mygame/server/server.pid` to determine which is the
main process.
* 3 x `twistd ... server.py` - One of these processes manages Evennia's Server component, the main game. The other processes (with the same name but different process id) handle's Evennia's internal web server threads. You can look at `mygame/server/server.pid` to determine which is the main process.
### Syntax errors during live development
@ -193,4 +185,4 @@ Fix your bug then run
evennia start
Assuming the bug was fixed, this will start the Server manually (while not restarting the Portal).
In-game you should now get the message that the Server has successfully restarted.
In-game you should now get the message that the Server has successfully restarted.

30
docs/source/index.md
View file

@ -14,27 +14,35 @@ This is the manual of [Evennia](https://www.evennia.com), the open source Python
`MU*` creation system.
- [Evennia Introduction](./Evennia-Introduction.md)
- [Installation](Setup/Installation.md)
- [Beginner Tutorial](Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md)
- [How to contribute and get help](./Contributing.md)
## Main sections
## Setup
- [Server Setup, Maintenance and Life](Setup/Setup-Overview.md) - how to run, maintain and release
- [Tutorials and Howto's](Howtos/Howtos-Overview.md) - projects and hints for reaching particular effects and goals
----
- [Installation](Setup/Installation.md)
- [Starting, Stopping and Reloading](Setup/Start-Stop-Reload.md) - how to manage the Evennia server
- [Setup and configuration](Setup/Setup-Overview.md) - how to run, maintain and release
## Howtos and Tutorials
- [The Beginner Tutorial](Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md) - learn the basics and build a small game (in progress)
- [Tutorials and Howto's](Howtos/Howtos-Overview.md) - mixed tutorials to learn Evennia
## Developing with Evennia
- [Core components](Components/Components-Overview.md) - the core building blocks of Evennia
- [Concepts](Concepts/Concepts-Overview.md) - larger-scale concepts and features
----
- [API](./Evennia-API.md) - the full API-reference, generated from source
- [Default Commands](Components/Default-Commands.md) - list of game commands included out of the box
- [Coding](Coding/Coding-Overview.md) - coding and development hints and resources
- [Contribs](Contribs/Contribs-Overview.md) - game-specific tools and code added by the community
----
- [Links](./Links.md) - useful links
## Contributions and Info
- [Contribs](Contribs/Contribs-Overview.md) - game-specific code and snippets to use for your game
- [How to contribute to these docs](./Contributing-Docs.md) - if you want to help out
- [Links](./Links.md) - useful links
- [Licensing](./Licensing.md) - Evennia licensing info (BSD)
----
## All Sections