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

split install/setup, rewrite installation

Browse Source
This commit is contained in:
Cal
2026-04-19 16:09:27 -06:00
parent 50cda824a8
commit 4ce5205257
3 changed files with 159 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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](http: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!

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

@ -1,125 +1,94 @@
# 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. The current recommended versions are 3.12 or 3.13.
If you are converting an existing game, please follow the [upgrade instructions](./Installation-Upgrade.md).
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.
## Requirements
## Quickstart
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, replacing `mygame` with the directory to create for your game files.
#### Linux/Mac
```{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!
$ python -m venv evenv
$ source evenv/bin/activate
$ pip install evennia
$ evennia --init mygame
```
You re recommended to [setup a light-weight Python virtualenv](./Installation-Git.md#virtualenv) first.
#### Windows
```
py -m venv evenv
.\evenv\lib\activate
pip install evennia
py -m evennia
evennia --init mygame
```
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:
## Alternative Installations
pip install evennia
If you have specific install environment needs that differ from the standard instructions, the following additional guides are available:
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:
- [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: 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 for Windows 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\lib\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]
To update Evennia later, do the following:
**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.
pip install --upgrade evennia
### 3. Upgrading Evennia
```{note} **Windows users only -**
You now must run `python -m evennia` once. This should permanently make the `evennia` command available in your environment.
```
To update to a new release of Evennia, first ensure your same virtual environment is active, then run the upgrade install command:
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.
pip install --upgrade evennia
## Initialize a New Game
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:
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](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](./Creating-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
```
```