mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
Rounds of doc cleanups
This commit is contained in:
Griatch
parent
86686c0d15
commit
4128bc4733
9 changed files with 87 additions and 102 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue