mirror/evennia
3
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-08-18 03:05:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'rewrite-install-docs'

Browse Source
This commit is contained in:
Griatch
2026-07-04 09:52:01 +02:00
parent ec9a4ccf92 0999afa546
commit 41460fcd36
5 changed files with 162 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -48,7 +48,7 @@
- [Fix][pull3938]: Fix ReferenceError in notifications plugin when window unfocused (Problematic)
- [Fix][pull3942]: Add AMP_CONNECT_TIMEOUT for portal probe (jaborsh)
- Fix: Resolve UnhandledCommand race on server start (Griatch)
- Docs: Griatch, BigJMoney, dicnunz, pikammmmm
- Docs: Griatch, BigJMoney, dicnunz, pikammmmm, InspectorCaracal
[pull3866]: https://github.com/evennia/evennia/pull/3866
[pull3867]: https://github.com/evennia/evennia/pull/3867

85
docs/source/Setup/Create-Game-Dir.md Normal file
View File

@ -0,0 +1,85 @@
# Creating a New Game
## Initialize a New Game
We will create a new "game dir" in which to create your game. 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. To create the new `mygame` folder—or whatever you choose—in your current location:
```{sidebar} Game Dir vs Game Name
The game dir you create doesn't have to match the name of your game. You can change the name of your game later by editing `mygame/server/conf/settings.py`.
```
evennia --init mygame
The resultant folder contains all the empty templates and default settings needed to start the Evennia server.
## Start the New Game
First, create the default database (Sqlite3):
cd mygame
evennia migrate
The resulting database file is created in `mygame/server/evennia.db3`. If you ever want to start from a fresh database, just delete this file and re-run the `evennia migrate` command.
Next, start the Evennia server with:
evennia start
When prompted, enter a username and password for the in-game "god" or "superuser." Providing an email address is optional.
> You can also [automate](./Installation-Non-Interactive.md) creation of the superuser.
If all went well, your new Evennia server is now up and running! To play your new—albeit empty—game, point a legacy MUD/telnet client to `localhost:4000` or a web browser to [http://localhost:4001](http://localhost:4001). You may log in as a new account or use the superuser account you created above.
## Restarting and Stopping
You can restart the server (without disconnecting players) by issuing:
evennia restart
And, to do a full stop and restart (with disconnecting players) use:
evennia reboot
A full stop of the server (use `evennia start` to restart) is achieved with:
evennia stop
See the [Server start-stop-reload](./Running-Evennia.md) documentation page for details.
## View Server Logs
Log files are located in `mygame/server/logs`. You can tail the logging in real-time with:
evennia --log
or just:
evennia -l
Press `Ctrl-C` (`Cmd-C` for Mac) to stop viewing the live log.
You may also begin viewing the real-time log immediately by adding `-l/--log` to `evennia` commands, such as when starting the server:
evennia start -l
## Server Configuration
Your server's configuration file is `mygame/server/conf/settings.py`. It's empty by default. Copy and paste **only** the settings you want/need from the [default settings file](./Settings-Default.md) to your server's `settings.py`. See the [Settings](./Settings.md) documentation for more information before configuring your server at this time.
## Register with the Evennia Game Index (optional)
To let the world know that you are working on a new Evennia-based game, you may register your server with the _Evennia game index_ by issuing:
evennia connections
Then, just follow the prompts. You don't have to be open for players to do this — simply mark your game as closed and "pre-alpha."
See [here](./Evennia-Game-Index.md) for more instructions and please [check out the index](https://games.evennia.com) beforehand to make sure you don't pick a game name that is already taken — be nice!
## Next Steps
You are good to go!
Next, why not head over to the [Starting Tutorial](../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.md) to learn how to begin making your new game!

6
docs/source/Setup/Installation-Troubleshooting.md
View File

@ -7,12 +7,12 @@ you can run `evennia -l`, or start/reload the server with `evennia start -l` or
## Check your Requirements
Any system that supports Python3.10+ should work.
Any system that supports Python3.12+ should work.
- Linux/Unix
- Windows (Win7, Win8, Win10, Win11)
- Mac OSX (>10.5 recommended)
- [Python](https://www.python.org) (3.11, 3.12 and 3.13 are tested. 3.13 is recommended)
- [Python](https://www.python.org) (3.12, 3.13 and 3.14 are tested. 3.14 is recommended)
- [Twisted](https://twistedmatrix.com) (v24.11+)
- [ZopeInterface](https://www.zope.org/Products/ZopeInterface) (v3.0+) - usually included in Twisted packages
- Linux/Mac users may need the `gcc` and `python-dev` packages or equivalent.
@ -41,7 +41,7 @@ When doing the `python3.x -m venv evenv` (where x is the python3 version) step,
Error: Command '['evenv', '-Im', 'ensurepip', '--upgrade', '--default-pip']'
returned non-zero exit status 1
You can solve this by installing the `python3.11-venv` (or later) package (or equivalent for your OS). Alternatively you can bootstrap it in this way:
You can solve this by installing the `python3.12-venv` (or later) package (or equivalent for your OS). Alternatively you can bootstrap it in this way:
python3.x -m --without-pip evenv

175
docs/source/Setup/Installation.md
View File

@ -1,125 +1,92 @@
# Installation
The fastest way to install Evennia is to use the `pip` installer that comes with Python (read on). 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).
Evennia requires having [Python](https://www.python.org/downloads/) and pip installed. Python 3.12, 3.13 and 3.14 are supported (3.14 is recommended).
If you are converting an existing game, please follow the [upgrade instructions](./Installation-Upgrade.md).
## Requirements
```{sidebar} Develop in isolation
Installing Evennia doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection if you want to.
```
- Evennia requires [Python](https://www.python.org/downloads/) 3.11, 3.12 or 3.13 (recommended). Any OS that supports Python should work.
- _Windows_: In the installer, make sure to 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.
- Don't install Evennia as administrator or superuser.
- If you run into trouble, see [installation troubleshooting](./Installation-Troubleshooting.md).
## Install with `pip`
```{important}
You are recommended to setup a light-weight Python virtualenv to install Evennia in. Using a virtualenv is standard practice in Python and allows you to install what you want in isolation from other programs. The virtualenv system is a part of Python and will make your life easier!
```{note}
As this is not a Python installation guide, please consult the instructions for installing Python+pip for your operating system if it is not already installed.
```
You re recommended to [setup a light-weight Python virtualenv](./Installation-Git.md#virtualenv) first.
## Quickstart
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python installed—and after activating your virtualenv if you are using one—install Evennia with:
Make sure you have a supported Python version installed, navigate to your development directory in a terminal, and execute the following commands appropriate for your operating system.
pip install evennia
#### Linux/Mac
Optional: If you use a [contrib](../Contribs/Contribs-Overview.md) that warns you that it needs additional packages, you can install all extra dependencies with:
$ python -m venv evenv
$ source evenv/bin/activate
$ pip install evennia
pip install evennia[extra]
#### Windows
To update Evennia later, do the following:
py -m venv evenv
.\evenv\Scripts\activate
pip install evennia
py -m evennia
pip install --upgrade evennia
## Alternative Installations
```{note} **Windows users only -**
You now must run `python -m evennia` once. This should permanently make the `evennia` command available in your environment.
If you have specific install environment needs that differ from the standard instructions, the following additional guides are available:
- [Docker](./Installation-Docker.md)
- [Git](./Installation-Git.md)
- [Android](./Installation-Android.md)
- [Upgrading from a beta version of Evennia](./Installation-Upgrade.md)
## Install Guide
### 1. Set up a development environment
You will need to install Evennia to a *python virtual environment*, so the first step is to create one. This is done using the `venv` package in python:
$ python -m venv evenv
```{note}
**Windows Only**: The recommended way to run python from the Windows command line is the `py` launcher command, so you will most likely want to use `py` instead of `python` here and for the rest of the instructions. However, you can also directly reference the python version. Consult the official [Python on Windows](https://docs.python.org/3/faq/windows.html) documentation for more information.
```
This will create a new directory named `evenv` containing the *virtual environment* - a set of python packages and executables installed locally, rather than system-wide. Doing this prevents permissions and conflict issues later.
Once it's created, you *activate* it in order to use that environment - it'll keep the python version and anything you install via `pip` contained within it.
Linux/Mac:
$ source evenv/bin/activate
Windows:
.\evenv\Scripts\activate
You'll need to do this step - activating the environment - every time you open a new terminal to work on your Evennia game.
### 2. Install Evennia
Once your virtual environment is activated, you can install Evennia into it:
pip install evennia
This will install the latest release version of Evennia into your virtual environment.
If you use a [contrib](../Contribs/Contribs-Overview.md) that warns you that it needs additional packages, use the following to install all of the extra dependencies:
pip install evennia[extra]
```{note}
**Windows only**: After installing, you will need to enter one more command - `py -m evennia` - to make sure that the `evennia` command is available in your terminal.
```
Once installed, make sure the `evennia` command works. Use `evennia -h` for usage help. If you are using a virtualenv, make sure it is active whenever you need to use the `evennia` command later.
### 3. Upgrading Evennia
## Initialize a New Game
To update to a new release of Evennia, first ensure your same virtual environment is active, then run the upgrade install command:
We will create a new "game dir" in which to create your game. 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. To create the new `mygame` folder—or whatever you choose—in your current location:
pip install --upgrade evennia
```{sidebar} Game Dir vs Game Name
The game dir you create doesn't have to match the name of your game. You can change the name of your game later by editing `mygame/server/conf/settings.py`.
```
This will upgrade evennia and all its dependencies to the latest version. If you used the extra dependencies installation, just add it to the end to upgrade those as well:
evennia --init mygame
The resultant folder contains all the empty templates and default settings needed to start the Evennia server.
## Start the New Game
First, create the default database (Sqlite3):
cd mygame
evennia migrate
The resulting database file is created in `mygame/server/evennia.db3`. If you ever want to start from a fresh database, just delete this file and re-run the `evennia migrate` command.
Next, start the Evennia server with:
evennia start
When prompted, enter a username and password for the in-game "god" or "superuser." Providing an email address is optional.
> You can also [automate](./Installation-Non-Interactive.md) creation of the superuser.
If all went well, your new Evennia server is now up and running! To play your new—albeit empty—game, point a legacy MUD/telnet client to `localhost:4000` or a web browser to [http://localhost:4001](http://localhost:4001). You may log in as a new account or use the superuser account you created above.
## Restarting and Stopping
You can restart the server (without disconnecting players) by issuing:
evennia restart
And, to do a full stop and restart (with disconnecting players) use:
evennia reboot
A full stop of the server (use `evennia start` to restart) is achieved with:
evennia stop
See the [Server start-stop-reload](./Running-Evennia.md) documentation page for details.
## View Server Logs
Log files are located in `mygame/server/logs`. You can tail the logging in real-time with:
evennia --log
or just:
evennia -l
Press `Ctrl-C` (`Cmd-C` for Mac) to stop viewing the live log.
You may also begin viewing the real-time log immediately by adding `-l/--log` to `evennia` commands, such as when starting the server:
evennia start -l
## Server Configuration
Your server's configuration file is `mygame/server/conf/settings.py`. It's empty by default. Copy and paste **only** the settings you want/need from the [default settings file](./Settings-Default.md) to your server's `settings.py`. See the [Settings](./Settings.md) documentation for more information before configuring your server at this time.
## Register with the Evennia Game Index (optional)
To let the world know that you are working on a new Evennia-based game, you may register your server with the _Evennia game index_ by issuing:
evennia connections
Then, just follow the prompts. You don't have to be open for players to do this — simply 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!
pip install --upgrade evennia[extra]
## Next Steps
You are good to go!
Next, why not head over to the [Starting Tutorial](../Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.md) to learn how to begin making your new game!
That's it! Check out the guide for [setting up a new game](./Create-Game-Dir.md) to get started developing!

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

@ -14,6 +14,7 @@ Installation-Troubleshooting
Installation-Android
Installation-Upgrade
Installation-Non-Interactive
Create-Game-Dir
Running-Evennia
Updating-Evennia
```
@ -45,4 +46,4 @@ Security-Practices
Config-HAProxy
Config-Nginx
Config-Apache-Proxy
```
```