Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-05 07:27:17 +02: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 c75708a32c
commit b7e819b5a0
19 changed files with 116 additions and 269 deletions
Download patch file Download diff file Expand all files Collapse all files

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