Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 12:56:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Considerable cleanup of installation docs

Browse source
This commit is contained in:
Griatch 2022-02-05 14:03:01 +01:00
parent f7c01c2ee4
commit ca7bee9d99
38 changed files with 2660 additions and 739 deletions
Download patch file Download diff file Expand all files Collapse all files

16
.github/workflows/github_action_test_suite.yml vendored
View file

@ -18,7 +18,7 @@ jobs:
strategy:
fail-fast: false
matrix:
python-version: [3.9, 3.10]
python-version: ["3.9", "3.10"]
TESTING_DB: ['sqlite3', 'postgresql', 'mysql']
steps:
@ -94,7 +94,7 @@ jobs:
# it's also not critical if pushing to either service fails (happens for PRs since env is not
# available outside of the evennia org)
- name: Send data to Coveralls
if: ${{ matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7 }}
if: ${{ matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10" }}
continue-on-error: true
env:
COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
@ -103,7 +103,7 @@ jobs:
coveralls
- name: Send data to Codacy
if: ${{ matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7 }}
if: ${{ matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10" }}
continue-on-error: true
uses: codacy/codacy-coverage-reporter-action@master
with:
@ -113,22 +113,22 @@ jobs:
# docker setup and push
-
name: Set up QEMU
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10"
uses: docker/setup-qemu-action@v1
-
name: Set up Docker Buildx
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10"
uses: docker/setup-buildx-action@v1
-
name: Login to DockerHub
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7 && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop')
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10" && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/develop')
uses: docker/login-action@v1
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push for master
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7 && github.ref == 'refs/heads/master'
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10" && github.ref == 'refs/heads/master'
id: docker_build_master
uses: docker/build-push-action@v2
with:
@ -136,7 +136,7 @@ jobs:
tags: evennia/evennia:latest
-
name: Build and push for develop
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == 3.7 && github.ref == 'refs/heads/develop'
if: matrix.TESTING_DB == 'sqlite3' && matrix.python-version == "3.10" && github.ref == 'refs/heads/develop'
id: docker_build_develop
uses: docker/build-push-action@v2
with:

48
CHANGELOG.md
View file

@ -1,6 +1,9 @@
# Changelog
## Evennia 1.0 (2019-) (develop branch, WIP)
### Evennia 1.0
> Not released yet
> 2019-2022 develop branch (WIP)
Up requirements to Django 4.0+, Twisted 22+, Python 3.9 or 3.10
@ -144,10 +147,11 @@ Up requirements to Django 4.0+, Twisted 22+, Python 3.9 or 3.10
on location for easy use in game dir.
### Evennia 0.9.5 (2019-2020)
## Evennia 0.9.5
Released 2020-11-14.
A transitional release, including new doc system.
> 2019-2020
> Released 2020-11-14.
> Transitional release, including new doc system.
Backported from develop: Python 3.8, 3.9 support. Django 3.2+ support, Twisted 21+ support.
@ -234,8 +238,10 @@ without arguments starts a full interactive Python console.
`INPUT_CLEANUP_BYPASS_PERMISSIONS` is a list of perms that bypass this safety stripping.
- Make default `set` and `examine` commands aware of Attribute categories.
## Evennia 0.9
## Evennia 0.9 (2018-2019)
> 2018-2019
> Released Oct 2019
### Distribution
@ -433,7 +439,10 @@ without arguments starts a full interactive Python console.
- Simplified chinese, courtesy of user MaxAlex.
## Evennia 0.8 (2018)
## Evennia 0.8
> 2017-2018
> Released Nov 2018
### Requirements
@ -560,7 +569,9 @@ without arguments starts a full interactive Python console.
- Polish translation by user ogotai
# Overviews
# Overview-Changelogs
> These are changelogs from a time before we used formal version numbers.
## Sept 2017:
Release of Evennia 0.7; upgrade to Django 1.11, change 'Player' to
@ -682,24 +693,9 @@ to Events, Commands and Permissions.
Griatch takes over Maintainership of the Evennia project from
the original creator Greg Taylor.
(Earlier revisions, with previous maintainer, go back to 2005)
# Older
Earlier revisions, with previous maintainer, used SVN on Google Code
and have no changelogs.
# Contact, Support and Development
Make a post to the mailing list or chat us up on IRC. We also have a
bug tracker if you want to report bugs. Finally, if you are willing to
help with the code work, we much appreciate all help! Visit either of
the following resources:
* Evennia Webpage
http://evennia.com
* Evennia manual (wiki)
https://github.com/evennia/evennia/wiki
* Evennia Code Page (See INSTALL text for installation)
https://github.com/evennia/evennia
* Bug tracker
https://github.com/evennia/evennia/issues
* IRC channel
visit channel #evennia on irc.freenode.com
or the webclient: http://tinyurl.com/evchat
First commit (Evennia's birthday) was November 20, 2006.

81
docs/pylib/update_dynamic_pages.py Normal file
View file

@ -0,0 +1,81 @@
"""
Update dynamically generated doc pages based on github sources.
"""
from os.path import dirname, abspath, join as pathjoin
ROOTDIR = dirname(dirname(dirname(abspath(__file__))))
DOCDIR = pathjoin(ROOTDIR, "docs")
DOCSRCDIR = pathjoin(DOCDIR, "source")
EVENNIADIR = pathjoin(ROOTDIR, "evennia")
def update_changelog():
"""
Plain CHANGELOG copy
"""
sourcefile = pathjoin(ROOTDIR, "CHANGELOG.md")
targetfile = pathjoin(DOCSRCDIR, "Setup", "Changelog.md")
with open(sourcefile) as fil:
txt = fil.read()
with open(targetfile, 'w') as fil:
fil.write(txt)
print(" -- Updated Changelog.md")
def update_default_settings():
"""
Make a copy of the default settings file for easy reference in docs
"""
sourcefile = pathjoin(EVENNIADIR, "settings_default.py")
targetfile = pathjoin(DOCSRCDIR, "Setup", "Settings-Default.md")
with open(sourcefile) as fil:
txt = fil.read()
txt = f"""
# Evennia Default settings file
Master file is located at `evennia/evennia/settings_default.py`. Read
its comments to see what each setting does and copy only what you want
to change into `mygame/server/conf/settings.py`.
Example of accessing settings:
```
from django.conf import settings
if settings.SERVERNAME == "Evennia":
print("Yay!")
```
----
```python
{txt}
```
"""
with open(targetfile, 'w') as fil:
fil.write(txt)
print(" -- Updated Settings-Default.md")
def update_dynamic_pages():
"""
Run the various updaters
"""
update_changelog()
update_default_settings()
if __name__ == "__main__":
update_dynamic_pages()

2
docs/source/Coding/Quirks.md
View file

@ -110,7 +110,7 @@ Try to avoid doing so.
distributions (notably Ubuntu 16.04 LTS). Zope is a dependency of Twisted. The error manifests in
the server not starting with an error that `zope.interface` is not found even though `pip list`
shows it's installed. The reason is a missing empty `__init__.py` file at the root of the zope
package. If the virtualenv is named "evenv" as suggested in the [Setup Quickstart](../Setup/Setup-Quickstart.md)
package. If the virtualenv is named "evenv" as suggested in the [Setup Quickstart](../Setup/Installation.md)
instructions, use the following command to fix it:
```shell

2
docs/source/Coding/Updating-Your-Game.md
View file

@ -2,7 +2,7 @@
Fortunately, it's extremely easy to keep your Evennia server up-to-date. If you haven't already, see
the [Getting Started guide](../Setup/Setup-Quickstart.md) and get everything running.
the [Getting Started guide](../Setup/Installation.md) and get everything running.
## Updating with the latest Evennia code changes

2
docs/source/Concepts/Internationalization.md
View file

@ -88,7 +88,7 @@ translation bad ... You are welcome to help improve the situation!
To start a new translation you need to first have cloned the Evennia repositry
with GIT and activated a python virtualenv as described on the
[Setup Quickstart](../Setup/Setup-Quickstart.md) page.
[Setup Quickstart](../Setup/Installation.md) page.
Go to `evennia/evennia/` - that is, not your game dir, but inside the `evennia/`
repo itself. If you see the `locale/` folder you are in the right place. Make

4
docs/source/Contribs/Arxcode-installing-help.md
View file

@ -23,7 +23,7 @@ better match with the vanilla Evennia install.
Firstly, set aside a folder/directory on your drive for everything to follow.
You need to start by installing [Evennia](https://www.evennia.com) by following most of the
[Getting Started Instructions](../Setup/Setup-Quickstart.md) for your OS. The difference is that you need to `git clone
[Getting Started Instructions](../Setup/Installation.md) for your OS. The difference is that you need to `git clone
https://github.com/TehomCD/evennia.git` instead of Evennia's repo because Arx uses TehomCD's older
Evennia 0.8 [fork](https://github.com/TehomCD/evennia), notably still using Python2. This detail is
important if referring to newer Evennia documentation.
@ -31,7 +31,7 @@ important if referring to newer Evennia documentation.
If you are new to Evennia it's *highly* recommended that you run through the
instructions in full - including initializing and starting a new empty game and connecting to it.
That way you can be sure Evennia works correctly as a base line. If you have trouble, make sure to
read the [Troubleshooting instructions](../Setup/Extended-Installation.md#troubleshooting) for your
read the [Troubleshooting instructions](../Setup/Installation-Git.md#troubleshooting) for your
operating system. You can also drop into our
[forums](https://groups.google.com/forum/#%21forum/evennia), join `#evennia` on `irc.freenode.net`
or chat from the linked [Discord Server](https://discord.gg/NecFePw).

2
docs/source/Contributing-Docs.md
View file

@ -720,7 +720,7 @@ available at https://evennia.github.io/evennia/latest/.
[commonmark-help]: https://commonmark.org/help/
[sphinx-autodoc]: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc
[sphinx-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
[getting-started]: Setup/Setup-Quickstart
[getting-started]: Setup/Installation
[contributing]: ./Contributing
[ReST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
[ReST-tables]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

4
docs/source/Evennia-Introduction.md
View file

@ -49,11 +49,11 @@ connect to the demo via your telnet client you can do so at `demo.evennia.com`,
Once you installed Evennia yourself it comes with its own tutorial - this shows off some of the
possibilities _and_ gives you a small single-player quest to play. The tutorial takes only one
single in-game command to install as explained [here](Howto/Starting/Part1/Tutorial-World-Introduction.md).
single in-game command to install as explained [here](Howto/Starting/Part1/Tutorial-World.md).
## What you need to know to work with Evennia
Assuming you have Evennia working (see the [quick start instructions](Setup/Setup-Quickstart.md)) and have
Assuming you have Evennia working (see the [quick start instructions](Setup/Installation.md)) and have
gotten as far as to start the server and connect to it with the client of your choice, here's what
you need to know depending on your skills and needs.

14
docs/source/Glossary.md
View file

@ -340,12 +340,12 @@ something like "the command 'evennia' is not available" - it's probably because
not 'active' yet (see below).
Usage:
- `virtualenv <name>` - initialize a new virtualenv `<name>` in a new folder `<name>` in the current
location. Called `evenv` in these docs.
- `virtualenv -p path/to/alternate/python_executable <name>` - create a virtualenv using another
Python version than default.
- `source <folder_name>/bin/activate`(linux/mac) - activate the virtualenv in `<folder_name>`.
- `<folder_name>\Scripts\activate` (windows)
- `python3.10 -m venv evenv` - initialize a new virtualenv-folder `evenv` in the current
location. You can call this whatever you like. The Python-version you use for this call will be the one used
for everything inside the virtualenv.
- `source evenv/bin/activate` (linux/mac) or `evenv\Scripts\activate`(windows) - this activates the
virtualenv.
- `deactivate` - turn off the currently activated virtualenv.
A virtualenv is 'activated' only for the console/terminal it was started in, but it's safe to
@ -377,6 +377,6 @@ never have to actually `cd` into the `evenv` folder. You can activate it from an
still be considered "in" the virtualenv wherever you go until you `deactivate` or close the
console/terminal.
So, when do I *need* to activate my virtualenv? If the virtualenv is not active, none of the Python
So, when do you *need* to activate my virtualenv? If the virtualenv is not active, none of the Python
packages/programs you installed in it will be available to you. So at a minimum, *it needs to be
activated whenever you want to use the `evennia` command* for any reason.

4
docs/source/Howto/Evennia-for-MUSH-Users.md
View file

@ -88,7 +88,7 @@ based inheritance of MUSH.
There are other differences for sure, but that should give some feel for things. Enough with the
theory. Let's get down to more practical matters next. To install, see the
[Getting Started instructions](../Setup/Setup-Quickstart.md).
[Getting Started instructions](../Setup/Installation.md).
## A first step making things more familiar
@ -211,7 +211,7 @@ for-roleplaying-sessions) that can be of interest.
An important aspect of making things more familiar for *Players* is adding new and tweaking existing
commands. How this is done is covered by the [Tutorial on adding new commands](Adding-Command-
Tutorial). You may also find it useful to shop through the `evennia/contrib/` folder. The
[Tutorial world](Starting/Part1/Tutorial-World-Introduction.md) is a small single-player quest you can try (it’s not very MUSH-
[Tutorial world](Starting/Part1/Tutorial-World.md) is a small single-player quest you can try (it’s not very MUSH-
like but it does show many Evennia concepts in action). Beyond that there are [many more tutorials](./Howto-Overview.md)
to try out. If you feel you want a more visual overview you can also look at
[Evennia in pictures](https://evennia.blogspot.se/2016/05/evennia-in-pictures.html).

2
docs/source/Howto/Evennia-for-roleplaying-sessions.md
View file

@ -26,7 +26,7 @@ defaults for our particular use-case. Below we will flesh out these components f
## Starting out
We will assume you start from scratch. You need Evennia installed, as per the [Setup Quickstart](../Setup/Setup-Quickstart.md)
We will assume you start from scratch. You need Evennia installed, as per the [Setup Quickstart](../Setup/Installation.md)
instructions. Initialize a new game directory with `evennia init
<gamedirname>`. In this tutorial we assume your game dir is simply named `mygame`. You can use the
default database and keep all other settings to default for now. Familiarize yourself with the

2
docs/source/Howto/Howto-Overview.md
View file

@ -16,7 +16,7 @@ in mind for your own game, this will give you a good start.
1. [Introduction & Overview](Starting/Part1/Starting-Part1.md)
1. [Building stuff](Starting/Part1/Building-Quickstart.md)
1. [The Tutorial World](Starting/Part1/Tutorial-World-Introduction.md)
1. [The Tutorial World](Starting/Part1/Tutorial-World.md)
1. [Python basics](Starting/Part1/Python-basic-introduction.md)
1. [Game dir overview](Starting/Part1/Gamedir-Overview.md)
1. [Python classes and objects](Starting/Part1/Python-classes-and-objects.md)

2
docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md
View file

@ -16,7 +16,7 @@ what you can download from us. The github repo is also searchable.
Finally, you can clone the evennia repo to your own computer and read the sources locally. This is necessary
if you want to help with Evennia's development itself. See the
[extended install instructions](../../../Setup/Extended-Installation.md) if you want to do this.
[extended install instructions](../../../Setup/Installation-Git.md) if you want to do this.
## Where is it?

2
docs/source/Howto/Starting/Part1/Gamedir-Overview.md
View file

@ -200,7 +200,7 @@ people change and re-structure this in various ways to better fit their ideas.
- [batch_cmds.ev](github:evennia/game_template/world/batch_cmds.ev) - This is an `.ev` file, which is essentially
just a list of Evennia commands to execute in sequence. This one is empty and ready to expand on. The
[Tutorial World](./Tutorial-World-Introduction.md) was built with such a batch-file.
[Tutorial World](./Tutorial-World.md) was built with such a batch-file.
- [prototypes.py](github:evennia/game_template/world/prototypes.py) - A [prototype](../../../Components/Prototypes.md) is a way
to easily vary objects without changing their base typeclass. For example, one could use prototypes to
tell that Two goblins, while both of the class 'Goblin' (so they follow the same code logic), should have different

2
docs/source/Howto/Starting/Part1/More-on-Commands.md
View file

@ -144,7 +144,7 @@ change (no code changed, only stuff in the database).
The commands of a cmdset attached to an object with `obj.cmdset.add()` will by default be made available to that object
but _also to those in the same location as that object_. If you did the [Building introduction](./Building-Quickstart.md)
you've seen an example of this with the "Red Button" object. The [Tutorial world](./Tutorial-World-Introduction.md)
you've seen an example of this with the "Red Button" object. The [Tutorial world](./Tutorial-World.md)
also has many examples of objects with commands on them.
To show how this could work, let's put our 'hit' Command on our simple `sword` object from the previous section.

4
docs/source/Howto/Starting/Part1/Starting-Part1.md
View file

@ -25,7 +25,7 @@ and share with others!
1. Introduction (you are here)
1. [Building stuff](./Building-Quickstart.md)
1. [The Tutorial World](./Tutorial-World-Introduction.md)
1. [The Tutorial World](./Tutorial-World.md)
1. [Python basics](./Python-basic-introduction.md)
1. [Game dir overview](./Gamedir-Overview.md)
1. [Python classes and objects](./Python-classes-and-objects.md)
@ -79,7 +79,7 @@ things don't change much from year to year. Popular choices for Python are PyCha
### Set up a game dir for the tutorial
Next you should make sure you have [installed Evennia](../../../Setup/Setup-Quickstart.md). If you followed the instructions
Next you should make sure you have [installed Evennia](../../../Setup/Installation.md). If you followed the instructions
you will already have created a game-dir. You could use that for this tutorial or you may want to do the
tutorial in its own, isolated game dir; it's up to you.

0
docs/source/Howto/Starting/Part1/Tutorial-World-Introduction.md → docs/source/Howto/Starting/Part1/Tutorial-World.md
View file

2
docs/source/Howto/Starting/Part3/Tutorial-for-basic-MUSH-like-game.md
View file

@ -660,6 +660,6 @@ The simple "Power" game mechanic should be easily expandable to something more f
useful, same is true for the combat score principle. The `+attack` could be made to target a
specific player (or npc) and automatically compare their relevant attributes to determine a result.
To continue from here, you can take a look at the [Tutorial World](../Part1/Tutorial-World-Introduction.md). For
To continue from here, you can take a look at the [Tutorial World](../Part1/Tutorial-World.md). For
more specific ideas, see the [other tutorials and hints](../../Howto-Overview.md) as well
as the [Evennia Component overview](../../../Components/Components-Overview.md).

701
docs/source/Setup/Changelog.md Normal file
View file

@ -0,0 +1,701 @@
# Changelog
### Evennia 1.0
> Not released yet
> 2019-2022 develop branch (WIP)
Up requirements to Django 4.0+, Twisted 22+, Python 3.9 or 3.10
- New `drop:holds()` lock default to limit dropping nonsensical things. Access check
defaults to True for backwards-compatibility in 0.9, will be False in 1.0
- REST API allows you external access to db objects through HTTP requests (Tehom)
- `Object.normalize_name` and `.validate_name` added to (by default) enforce latinify
on character name and avoid potential exploits using clever Unicode chars (trhr)
- New `utils.format_grid` for easily displaying long lists of items in a block.
- Using `lunr` search indexing for better `help` matching and suggestions. Also improve
the main help command's default listing output.
- Added `content_types` indexing to DefaultObject's ContentsHandler. (volund)
- Made most of the networking classes such as Protocols and the SessionHandlers
replaceable via `settings.py` for modding enthusiasts. (volund)
- The `initial_setup.py` file can now be substituted in `settings.py` to customize
initial game database state. (volund)
- Added new Traits contrib, converted and expanded from Ainneve project.
- Added new `requirements_extra.txt` file for easily getting all optional dependencies.
- Change default multi-match syntax from 1-obj, 2-obj to obj-1, obj-2.
- Make `object.search` support 'stacks=0' keyword - if ``>0``, the method will return
N identical matches instead of triggering a multi-match error.
- Add `tags.has()` method for checking if an object has a tag or tags (PR by ChrisLR)
- Make IP throttle use Django-based cache system for optional persistence (PR by strikaco)
- Renamed Tutorial classes "Weapon" and "WeaponRack" to "TutorialWeapon" and
"TutorialWeaponRack" to prevent collisions with classes in mygame
- New `crafting` contrib, adding a full crafting subsystem (Griatch 2020)
- The `rplanguage` contrib now auto-capitalizes sentences and retains ellipsis (...). This
change means that proper nouns at the start of sentences will not be treated as nouns.
- Make MuxCommand `lhs/rhslist` always be lists, also if empty (used to be the empty string)
- Fix typo in UnixCommand contrib, where `help` was given as `--hel`.
- Latin (la) i18n translation (jamalainm)
- Made the `evennia` dir possible to use without gamedir for purpose of doc generation.
- Make Scripts' timer component independent from script object deletion; can now start/stop
timer without deleting Script. The `.persistent` flag now only controls if timer survives
reload - Script has to be removed with `.delete()` like other typeclassed entities.
- Add `utils.repeat` and `utils.unrepeat` as shortcuts to TickerHandler add/remove, similar
to how `utils.delay` is a shortcut for TaskHandler add.
- Refactor the classic `red_button` example to use `utils.delay/repeat` and modern recommended
code style and paradigms instead of relying on `Scripts` for everything.
- Expand `CommandTest` with ability to check multiple message-receivers; inspired by PR by
user davewiththenicehat. Also add new doc string.
- Add central `FuncParser` as a much more powerful replacement for the old `parse_inlinefunc`
function.
- Add `evennia/utils/verb_conjugation` for automatic verb conjugation (English only). This
is useful for implementing actor-stance emoting for sending a string to different targets.
- New version of Italian translation (rpolve)
- `utils.evmenu.ask_yes_no` is a helper function that makes it easy to ask a yes/no question
to the user and respond to their input. This complements the existing `get_input` helper.
- Allow sending messages with `page/tell` without a `=` if target name contains no spaces.
- New FileHelpStorage system allows adding help entries via external files.
- `sethelp` command now warns if shadowing other help-types when creating a new
entry.
- Help command now uses `view` lock to determine if cmd/entry shows in index and
`read` lock to determine if it can be read. It used to be `view` in the role
of the latter. Migration swaps these around.
- In modules given by `settings.PROTOTYPE_MODULES`, spawner will now first look for a global
list `PROTOTYPE_LIST` of dicts before loading all dicts in the module as prototypes.
- New Channel-System using the `channel` command and nicks. Removed the `ChannelHandler` and the
concept of a dynamically created `ChannelCmdSet`.
- Add `Msg.db_receiver_external` field to allowe external, string-id message-receivers.
- Renamed `app.css` to `website.css` for consistency. Removed old prosimii-css files.
- Remove `mygame/web/static_overrides` and -`template_overrides`, reorganize website/admin/client/api
into a more consistent structure for overriding. Expanded webpage documentation considerably.
- REST API list-view was shortened (#2401). New CSS/HTML. Add ReDoc for API autodoc page.
- Update and fix dummyrunner with cleaner code and setup.
- Made `iter_to_str` format prettier strings, using Oxford comma.
- Added an MXP anchor tag to also support clickable web links.
- New `tasks` command for managing tasks started with `utils.delay` (PR by davewiththenicehat)
- Make `help` index output clickable for webclient/clients with MXP (PR by davewiththenicehat)
- Custom `evennia` launcher commands (e.g. `evennia mycmd foo bar`). Add new commands as callables
accepting `*args`, as `settings.EXTRA_LAUNCHER_COMMANDS = {'mycmd': 'path.to.callable', ...}`.
- New `XYZGrid` contrib, adding x,y,z grid coordinates with in-game map and
pathfinding. Controlled outside of the game via custom evennia launcher command.
- `Script.delete` has new kwarg `stop_task=True`, that can be used to avoid
infinite recursion when wanting to set up Script to delete-on-stop.
- Command executions now done on copies to make sure `yield` don't cause crossovers. Add
`Command.retain_instance` flag for reusing the same command instance.
- The `typeclass` command will now correctly search the correct database-table for the target
obj (avoids mistakenly assigning an AccountDB-typeclass to a Character etc).
- Merged `script` and `scripts` commands into one, for both managing global- and
on-object Scripts. Moved `CmdScripts` and `CmdObjects` to `commands/default/building.py`.
- Keep GMCP function case if outputfunc starts with capital letter (so `cmd_name` -> `Cmd.Name`
but `Cmd_nAmE` -> `Cmd.nAmE`). This helps e.g Mudlet's legacy `Client_GUI` implementation)
- Prototypes now allow setting `prototype_parent` directly to a prototype-dict.
This makes it easier when dynamically building in-module prototypes.
- `RPSystem contrib` was expanded to support case, so /tall becomes 'tall man'
while /Tall becomes 'Tall man'. One can turn this off if wanting the old style.
- Change `EvTable` fixed-height rebalance algorithm to fill with empty lines at end of
column instead of inserting rows based on cell-size (could be mistaken for a bug).
- Split `return_appearance` hook with helper methods and have it use a template
string in order to make it easier to override.
- Add validation question to default account creation.
- Add `LOCALECHO` client option to add server-side echo for clients that does
not support this (useful for getting a complete log).
- Make `@lazy_property` decorator create read/delete-protected properties. This is
because it's used for handlers, and e.g. self.locks=[] is a common beginner mistake.
- Add `$pron()` inlinefunc for pronoun parsing in actor-stance strings using
`msg_contents`.
- Update defauklt website to show Telnet/SSL/SSH connect info. Added new
`SERVER_HOSTNAME` setting for use in the server:port stanza.
- Changed all `at_before/after_*` hooks to `at_pre/post_*` for consistency
across Evennia (the old names still work but are deprecated)
- Change `settings.COMMAND_DEFAULT_ARG_REGEX` default from `None` to a regex meaning that
a space or `/` must separate the cmdname and args. This better fits common expectations.
- Add confirmation question to `ban`/`unban` commands.
- Check new `teleport` and `teleport_here` lock-types in `teleport` command to optionally
allow to limit teleportation of an object or to a specific destination.
- Add `settings.MXP_ENABLED=True` and `settings.MXP_OUTGOING_ONLY=True` as sane defaults,
to avoid known security issues with players entering MXP links.
- Add browser name to webclient `CLIENT_NAME` in `session.protocol_flags`, e.g.
`"Evennia webclient (websocket:firefox)"` or `"evennia webclient (ajax:chrome)"`.
- `TagHandler.add/has(tag=...)` kwarg changed to `add/has(key=...)` for consistency
with other handlers.
- Make `DefaultScript.delete`, `DefaultChannel.delete` and `DefaultAccount.delete` return
bool True/False if deletion was successful (like `DefaultObject.delete` before them)
- `contrib.custom_gametime` days/weeks/months now always starts from 1 (to match
the standard calendar form ... there is no month 0 every year after all).
- `AttributeProperty`/`NAttributeProperty` to allow managing Attributes/NAttributes
on typeclasses in the same way as Django fields.
- Give build/system commands a `@name` to fall back to if the non-@ name is used
by another command (like `open` and `@open`. If no duplicate, @ is optional.
- Move legacy channel-management commands (`ccreate`, `addcom` etc) to a contrib
since their work is now fully handled by the single `channel` command.
- Expand `examine` command's code to much more extensible and modular. Show
attribute categories and value types (when not strings).
- `AttributeHandler.remove(key, return_exception=False, category=None, ...)` changed
to `.remove(key, category=None, return_exception=False, ...)` for consistency.
- New `command cooldown` contrib for making it easier to manage commands using
dynamic cooldowns between uses (owllex)
- Restructured `contrib/` folder, placing all contribs as separate packages under
subfolders. All imports will need to be updated.
- Made `MonitorHandler.add/remove` support `category` for monitoring Attributes
with a category (before only key was used, ignoring category entirely).
- Move `create_*` functions into db managers, leaving `utils.create` only being
wrapper functions (consistent with `utils.search`). No change of api otherwise.
- Add support for `$dbref()` and `$search` when assigning an Attribute value
with the `set` command. This allows assigning real objects from in-game.
- Add ability to examine `/script` and `/channel` entities with `examine` command.
- Homogenize manager search methods to return querysets and not lists.
- Restructure unit tests to always honor default settings; make new parents in
on location for easy use in game dir.
## Evennia 0.9.5
> 2019-2020
> Released 2020-11-14.
> Transitional release, including new doc system.
Backported from develop: Python 3.8, 3.9 support. Django 3.2+ support, Twisted 21+ support.
- `is_typeclass(obj (Object), exact (bool))` now defaults to exact=False
- `py` command now reroutes stdout to output results in-game client. `py`
without arguments starts a full interactive Python console.
- Webclient default to a single input pane instead of two. Now defaults to no help-popup.
- Webclient fix of prompt display
- Webclient multimedia support for relaying images, video and sounds via
`.msg(image=URL)`, `.msg(video=URL)`
and `.msg(audio=URL)`
- Add Spanish translation (fermuch)
- Expand `GLOBAL_SCRIPTS` container to always start scripts and to include all
global scripts regardless of how they were created.
- Change settings to always use lists instead of tuples, to make mutable
settings easier to add to. (#1912)
- Make new `CHANNEL_MUDINFO` setting for specifying the mudinfo channel
- Make `CHANNEL_CONNECTINFO` take full channel definition
- Make `DEFAULT_CHANNELS` list auto-create channels missing at reload
- Webclient `ANSI->HTML` parser updated. Webclient line width changed from 1.6em to 1.1em
to better make ANSI graphics look the same as for third-party clients
- `AttributeHandler.get(return_list=True)` will return `[]` if there are no
Attributes instead of `[None]`.
- Remove `pillow` requirement (install especially if using imagefield)
- Add Simplified Korean translation (aceamro)
- Show warning on `start -l` if settings contains values unsafe for production.
- Make code auto-formatted with Black.
- Make default `set` command able to edit nested structures (PR by Aaron McMillan)
- Allow running Evennia test suite from core repo with `make test`.
- Return `store_key` from `TickerHandler.add` and add `store_key` as a kwarg to
the `TickerHandler.remove` method. This makes it easier to manage tickers.
- EvMore auto-justify now defaults to False since this works better with all types
of texts (such as tables). New `justify` bool. Old `justify_kwargs` remains
but is now only used to pass extra kwargs into the justify function.
- EvMore `text` argument can now also be a list or a queryset. Querysets will be
sliced to only return the required data per page.
- Improve performance of `find` and `objects` commands on large data sets (strikaco)
- New `CHANNEL_HANDLER_CLASS` setting allows for replacing the ChannelHandler entirely.
- Made `py` interactive mode support regular quit() and more verbose.
- Made `Account.options.get` accept `default=None` kwarg to mimic other uses of get. Set
the new `raise_exception` boolean if ranting to raise KeyError on a missing key.
- Moved behavior of unmodified `Command` and `MuxCommand` `.func()` to new
`.get_command_info()` method for easier overloading and access. (Volund)
- Removed unused `CYCLE_LOGFILES` setting. Added `SERVER_LOG_DAY_ROTATION`
and `SERVER_LOG_MAX_SIZE` (and equivalent for PORTAL) to control log rotation.
- Addded `inside_rec` lockfunc - if room is locked, the normal `inside()` lockfunc will
fail e.g. for your inventory objs (since their loc is you), whereas this will pass.
- RPSystem contrib's CmdRecog will now list all recogs if no arg is given. Also multiple
bugfixes.
- Remove `dummy@example.com` as a default account email when unset, a string is no longer
required by Django.
- Fixes to `spawn`, make updating an existing prototype/object work better. Add `/raw` switch
to `spawn` command to extract the raw prototype dict for manual editing.
- `list_to_string` is now `iter_to_string` (but old name still works as legacy alias). It will
now accept any input, including generators and single values.
- EvTable should now correctly handle columns with wider asian-characters in them.
- Update Twisted requirement to >=2.3.0 to close security vulnerability
- Add `$random` inlinefunc, supports minval,maxval arguments that can be ints and floats.
- Add `evennia.utils.inlinefuncs.raw(<str>)` as a helper to escape inlinefuncs in a string.
- Make CmdGet/Drop/Give give proper error if `obj.move_to` returns `False`.
- Make `Object/Room/Exit.create`'s `account` argument optional. If not given, will set perms
to that of the object itself (along with normal Admin/Dev permission).
- Make `INLINEFUNC_STACK_MAXSIZE` default visible in `settings_default.py`.
- Change how `ic` finds puppets; non-priveleged users will use `_playable_characters` list as
candidates, Builders+ will use list, local search and only global search if no match found.
- Make `cmd.at_post_cmd()` always run after `cmd.func()`, even when the latter uses delays
with yield.
- `EvMore` support for db queries and django paginators as well as easier to override for custom
pagination (e.g. to create EvTables for every page instead of splittine one table)
- Using `EvMore pagination`, dramatically improves performance of `spawn/list` and `scripts` listings
(100x speed increase for displaying 1000+ prototypes/scripts).
- `EvMenu` now uses the more logically named `.ndb._evmenu` instead of `.ndb._menutree` to store itself.
Both still work for backward compatibility, but `_menutree` is deprecated.
- `EvMenu.msg(txt)` added as a central place to send text to the user, makes it easier to override.
Default `EvMenu.msg` sends with OOB type="menu" for use with OOB and webclient pane-redirects.
- New EvMenu templating system for quickly building simpler EvMenus without as much code.
- Add `Command.client_height()` method to match existing `.client_width` (stricako)
- Include more Web-client info in `session.protocol_flags`.
- Fixes in multi-match situations - don't allow finding/listing multimatches for 3-box when
only two boxes in location.
- Fix for TaskHandler with proper deferred returns/ability to cancel etc (PR by davewiththenicehat)
- Add `PermissionHandler.check` method for straight string perm-checks without needing lockstrings.
- Add `evennia.utils.utils.strip_unsafe_input` for removing html/newlines/tags from user input. The
`INPUT_CLEANUP_BYPASS_PERMISSIONS` is a list of perms that bypass this safety stripping.
- Make default `set` and `examine` commands aware of Attribute categories.
## Evennia 0.9
> 2018-2019
> Released Oct 2019
### Distribution
- New requirement: Python 3.7 (py2.7 support removed)
- Django 2.1
- Twisted 19.2.1
- Autobahn websockets (removed old tmwx)
- Docker image updated
### Commands
- Remove `@`-prefix from all default commands (prefixes still work, optional)
- Removed default `@delaccount` command, incorporating as `@account/delete` instead. Added confirmation
question.
- Add new `@force` command to have another object perform a command.
- Add the Portal uptime to the `@time` command.
- Make the `@link` command first make a local search before a global search.
- Have the default Unloggedin-look command look for optional `connection_screen()` callable in
`mygame/server/conf/connection_screen.py`. This allows for more flexible welcome screens
that are calculated on the fly.
- `@py` command now defaults to escaping html tags in its output when viewing in the webclient.
Use new `/clientraw` switch to get old behavior (issue #1369).
- Shorter and more informative, dynamic, listing of on-command vars if not
setting func() in child command class.
- New Command helper methods
- `.client_width()` returns client width of the session running the command.
- `.styled_table(*args, **kwargs)` returns a formatted evtable styled by user's options
- `.style_header(*args, **kwargs)` creates styled header entry
- `.style_separator(*args, **kwargs)` " separator
- `.style_footer(*args, **kwargs)` " footer
### Web
- Change webclient from old txws version to use more supported/feature-rich Autobahn websocket library
#### Evennia game index
- Made Evennia game index client a part of core - now configured from settings file (old configs
need to be moved)
- The `evennia connections` command starts a wizard that helps you connect your game to the game index.
- The game index now accepts games with no public telnet/webclient info (for early prototypes).
#### New golden-layout based Webclient UI (@friarzen)
- Features
- Much slicker behavior and more professional look
- Allows tabbing as well as click and drag of panes in any grid position
- Renaming tabs, assignments of data tags and output types are simple per-pane menus now
- Any number of input panes, with separate histories
- Button UI (disabled in JS by default)
#### Web/Django standard initiative (@strikaco)
- Features
- Adds a series of web-based forms and generic class-based views
- Accounts
- Register - Enhances registration; allows optional collection of email address
- Form - Adds a generic Django form for creating Accounts from the web
- Characters
- Create - Authenticated users can create new characters from the website (requires associated form)
- Detail - Authenticated and authorized users can view select details about characters
- List - Authenticated and authorized users can browse a list of all characters
- Manage - Authenticated users can edit or delete owned characters from the web
- Form - Adds a generic Django form for creating characters from the web
- Channels
- Detail - Authorized users can view channel logs from the web
- List - Authorized users can browse a list of all channels
- Help Entries
- Detail - Authorized users can view help entries from the web
- List - Authorized users can browse a list of all help entries from the web
- Navbar changes
- Characters - Link to character list
- Channels - Link to channel list
- Help - Link to help entry list
- Puppeting
- Users can puppet their own characters within the context of the website
- Dropdown
- Link to create characters
- Link to manage characters
- Link to quick-select puppets
- Link to password change workflow
- Functions
- Updates Bootstrap to v4 stable
- Enables use of Django Messages framework to communicate with users in browser
- Implements webclient/website `_shared_login` functionality as Django middleware
- 'account' and 'puppet' are added to all request contexts for authenticated users
- Adds unit tests for all web views
- Cosmetic
- Prettifies Django 'forgot password' workflow (requires SMTP to actually function)
- Prettifies Django 'change password' workflow
- Bugfixes
- Fixes bug on login page where error messages were not being displayed
- Remove strvalue field from admin; it made no sense to have here, being an optimization field
for internal use.
### Prototypes
- `evennia.prototypes.save_prototype` now takes the prototype as a normal
argument (`prototype`) instead of having to give it as `**prototype`.
- `evennia.prototypes.search_prototype` has a new kwarg `require_single=False` that
raises a KeyError exception if query gave 0 or >1 results.
- `evennia.prototypes.spawner` can now spawn by passing a `prototype_key`
### Typeclasses
- Add new methods on all typeclasses, useful specifically for object handling from the website/admin:
+ `web_get_admin_url()`: Returns the path to the object detail page in the Admin backend.
+ `web_get_create_url()`: Returns the path to the typeclass' creation page on the website, if implemented.
+ `web_get_absolute_url()`: Returns the path to the object's detail page on the website, if implemented.
+ `web_get_update_url()`: Returns the path to the object's update page on the website, if implemented.
+ `web_get_delete_url()`: Returns the path to the object's delete page on the website, if implemented.
- All typeclasses have new helper class method `create`, which encompasses useful functionality
that used to be embedded for example in the respective `@create` or `@connect` commands.
- DefaultAccount now has new class methods implementing many things that used to be in unloggedin
commands (these can now be customized on the class instead):
+ `is_banned()`: Checks if a given username or IP is banned.
+ `get_username_validators`: Return list of validators for username validation (see
`settings.AUTH_USERNAME_VALIDATORS`)
+ `authenticate`: Method to check given username/password.
+ `normalize_username`: Normalizes names so (for Unicode environments) users cannot mimic existing usernames by replacing select characters with visually-similar Unicode chars.
+ `validate_username`: Mechanism for validating a username based on predefined Django validators.
+ `validate_password`: Mechanism for validating a password based on predefined Django validators.
+ `set_password`: Apply password to account, using validation checks.
- `AttributeHandler.remove` and `TagHandler.remove` can now be used to delete by-category. If neither
key nor category is given, they now work the same as .clear().
### Protocols
- Support for `Grapevine` MUD-chat network ("channels" supported)
### Server
- Convert ServerConf model to store its values as a Picklefield (same as
Attributes) instead of using a custom solution.
- OOB: Add support for MSDP LIST, REPORT, UNREPORT commands (re-mapped to `msdp_list`,
`msdp_report`, `msdp_unreport`, inlinefuncs)
- Added `evennia.ANSIString` to flat API.
- Server/Portal log files now cycle to names on the form `server_.log_19_03_08_` instead of `server.log___19.3.8`, retaining
unix file sorting order.
- Django signals fire for important events: Puppet/Unpuppet, Object create/rename, Login,
Logout, Login fail Disconnect, Account create/rename
### Settings
- `GLOBAL_SCRIPTS` - dict defining typeclasses of global scripts to store on the new
`evennia.GLOBAL_SCRIPTS` container. These will auto-start when Evennia start and will always
exist.
- `OPTIONS_ACCOUNTS_DEFAULT` - option dict with option defaults and Option classes
- `OPTION_CLASS_MODULES` - classes representing an on-Account Option, on special form
- `VALIDATOR_FUNC_MODULES` - (general) text validator functions, for verifying an input
is on a specific form.
### Utils
- `evennia` launcher now fully handles all django-admin commands, like running tests in parallel.
- `evennia.utils.create.account` now also takes `tags` and `attrs` keywords.
- `evennia.utils.interactive` decorator can now allow you to use yield(secs) to pause operation
in any function, not just in Command.func. Likewise, response = yield(question) will work
if the decorated function has an argument or kwarg `caller`.
- Added many more unit tests.
- Swap argument order of `evennia.set_trace` to `set_trace(term_size=(140, 40), debugger='auto')`
since the size is more likely to be changed on the command line.
- `utils.to_str(text, session=None)` now acts as the old `utils.to_unicode` (which was removed).
This converts to the str() type (not to a byte-string as in Evennia 0.8), trying different
encodings. This function will also force-convert any object passed to it into a string (so
`force_string` flag was removed and assumed always set).
- `utils.to_bytes(text, session=None)` replaces the old `utils.to_str()` functionality and converts
str to bytes.
- `evennia.MONITOR_HANDLER.all` now takes keyword argument `obj` to only retrieve monitors from that specific
Object (rather than all monitors in the entire handler).
- Support adding `\f` in command doc strings to force where EvMore puts page breaks.
- Validation Functions now added with standard API to homogenize user input validation.
- Option Classes added to make storing user-options easier and smoother.
- `evennia.VALIDATOR_CONTAINER` and `evennia.OPTION_CONTAINER` added to load these.
### Contribs
- Evscaperoom - a full puzzle engine for making multiplayer escape rooms in Evennia. Used to make
the entry for the MUD-Coder's Guild's 2019 Game Jam with the theme "One Room", where it ranked #1.
- Evennia game-index client no longer a contrib - moved into server core and configured with new
setting `GAME_INDEX_ENABLED`.
- The `extended_room` contrib saw some backwards-incompatible refactoring:
+ All commands now begin with `CmdExtendedRoom`. So before it was `CmdExtendedLook`, now
it's `CmdExtendedRoomLook` etc.
+ The `detail` command was broken out of the `desc` command and is now a new, stand-alone command
`CmdExtendedRoomDetail`. This was done to make things easier to extend and to mimic how the detail
command works in the tutorial-world.
+ The `detail` command now also supports deleting details (like the tutorial-world version).
+ The new `ExtendedRoomCmdSet` includes all the extended-room commands and is now the recommended way
to install the extended-room contrib.
- Reworked `menu_login` contrib to use latest EvMenu standards. Now also supports guest logins.
- Mail contrib was refactored to have optional Command classes `CmdMail` for OOC+IC mail (added
to the CharacterCmdSet and `CmdMailCharacter` for IC-only mailing between chars (added to CharacterCmdSet)
### Translations
- Simplified chinese, courtesy of user MaxAlex.
## Evennia 0.8
> 2017-2018
> Released Nov 2018
### Requirements
- Up requirements to Django 1.11.x, Twisted 18 and pillow 5.2.0
- Add `inflect` dependency for automatic pluralization of object names.
### Server/Portal
- Removed `evennia_runner`, completely refactor `evennia_launcher.py` (the 'evennia' program)
with different functionality).
- Both Portal/Server are now stand-alone processes (easy to run as daemon)
- Made Portal the AMP Server for starting/restarting the Server (the AMP client)
- Dynamic logging now happens using `evennia -l` rather than by interactive mode.
- Made AMP secure against erroneous HTTP requests on the wrong port (return error messages).
- The `evennia istart` option will start/switch the Server in foreground (interactive) mode, where it logs
to terminal and can be stopped with Ctrl-C. Using `evennia reload`, or reloading in-game, will
return Server to normal daemon operation.
- For validating passwords, use safe Django password-validation backend instead of custom Evennia one.
- Alias `evennia restart` to mean the same as `evennia reload`.
### Prototype changes
- New OLC started from `olc` command for loading/saving/manipulating prototypes in a menu.
- Moved evennia/utils/spawner.py into the new evennia/prototypes/ along with all new
functionality around prototypes.
- A new form of prototype - database-stored prototypes, editable from in-game, was added. The old,
module-created prototypes remain as read-only prototypes.
- All prototypes must have a key `prototype_key` identifying the prototype in listings. This is
checked to be server-unique. Prototypes created in a module will use the global variable name they
are assigned to if no `prototype_key` is given.
- Prototype field `prototype` was renamed to `prototype_parent` to avoid mixing terms.
- All prototypes must either have `typeclass` or `prototype_parent` defined. If using
`prototype_parent`, `typeclass` must be defined somewhere in the inheritance chain. This is a
change from Evennia 0.7 which allowed 'mixin' prototypes without `typeclass`/`prototype_key`. To
make a mixin now, give it a default typeclass, like `evennia.objects.objects.DefaultObject` and just
override in the child as needed.
- Spawning an object using a prototype will automatically assign a new tag to it, named the same as
the `prototype_key` and with the category `from_prototype`.
- The spawn command was extended to accept a full prototype on one line.
- The spawn command got the /save switch to save the defined prototype and its key
- The command spawn/menu will now start an OLC (OnLine Creation) menu to load/save/edit/spawn prototypes.
### EvMenu
- Added `EvMenu.helptext_formatter(helptext)` to allow custom formatting of per-node help.
- Added `evennia.utils.evmenu.list_node` decorator for turning an EvMenu node into a multi-page listing.
- A `goto` option callable returning None (rather than the name of the next node) will now rerun the
current node instead of failing.
- Better error handling of in-node syntax errors.
- Improve dedent of default text/helptext formatter. Right-strip whitespace.
- Add `debug` option when creating menu - this turns off persistence and makes the `menudebug`
command available for examining the current menu state.
### Webclient
- Webclient now uses a plugin system to inject new components from the html file.
- Split-windows - divide input field into any number of horizontal/vertical panes and
assign different types of server messages to them.
- Lots of cleanup and bug fixes.
- Hot buttons plugin (friarzen) (disabled by default).
### Locks
- New function `evennia.locks.lockhandler.check_lockstring`. This allows for checking an object
against an arbitrary lockstring without needing the lock to be stored on an object first.
- New function `evennia.locks.lockhandler.validate_lockstring` allows for stand-alone validation
of a lockstring.
- New function `evennia.locks.lockhandler.get_all_lockfuncs` gives a dict {"name": lockfunc} for
all available lock funcs. This is useful for dynamic listings.
### Utils
- Added new `columnize` function for easily splitting text into multiple columns. At this point it
is not working too well with ansi-colored text however.
- Extend the `dedent` function with a new `baseline_index` kwarg. This allows to force all lines to
the indentation given by the given line regardless of if other lines were already a 0 indentation.
This removes a problem with the original `textwrap.dedent` which will only dedent to the least
indented part of a text.
- Added `exit_cmd` to EvMore pager, to allow for calling a command (e.g. 'look') when leaving the pager.
- `get_all_typeclasses` will return dict `{"path": typeclass, ...}` for all typeclasses available
in the system. This is used by the new `@typeclass/list` subcommand (useful for builders etc).
- `evennia.utils.dbserialize.deserialize(obj)` is a new helper function to *completely* disconnect
a mutable recovered from an Attribute from the database. This will convert all nested `_Saver*`
classes to their plain-Python counterparts.
### General
- Start structuring the `CHANGELOG` to list features in more detail.
- Docker image `evennia/evennia:develop` is now auto-built, tracking the develop branch.
- Inflection and grouping of multiple objects in default room (an box, three boxes)
- `evennia.set_trace()` is now a shortcut for launching pdb/pudb on a line in the Evennia event loop.
- Removed the enforcing of `MAX_NR_CHARACTERS=1` for `MULTISESSION_MODE` `0` and `1` by default.
- Add `evennia.utils.logger.log_sec` for logging security-related messages (marked SS in log).
### Contribs
- `Auditing` (Johnny): Log and filter server input/output for security purposes
- `Build Menu` (vincent-lg): New @edit command to edit object properties in a menu.
- `Field Fill` (Tim Ashley Jenkins): Wraps EvMenu for creating submittable forms.
- `Health Bar` (Tim Ashley Jenkins): Easily create colorful bars/meters.
- `Tree select` (Fluttersprite): Wrap EvMenu to create a common type of menu from a string.
- `Turnbattle suite` (Tim Ashley Jenkins)- the old `turnbattle.py` was moved into its own
`turnbattle/` package and reworked with many different flavors of combat systems:
- `tb_basic` - The basic turnbattle system, with initiative/turn order attack/defense/damage.
- `tb_equip` - Adds weapon and armor, wielding, accuracy modifiers.
- `tb_items` - Extends `tb_equip` with item use with conditions/status effects.
- `tb_magic` - Extends `tb_equip` with spellcasting.
- `tb_range` - Adds system for abstract positioning and movement.
- The `extended_room` contrib saw some backwards-incompatible refactoring:
- All commands now begin with `CmdExtendedRoom`. So before it was `CmdExtendedLook`, now
it's `CmdExtendedRoomLook` etc.
- The `detail` command was broken out of the `desc` command and is now a new, stand-alone command
`CmdExtendedRoomDetail`. This was done to make things easier to extend and to mimic how the detail
command works in the tutorial-world.
- The `detail` command now also supports deleting details (like the tutorial-world version).
- The new `ExtendedRoomCmdSet` includes all the extended-room commands and is now the recommended way
to install the extended-room contrib.
- Updates and some cleanup of existing contribs.
### Internationalization
- Polish translation by user ogotai
# Overview-Changelogs
> These are changelogs from a time before we used formal version numbers.
## Sept 2017:
Release of Evennia 0.7; upgrade to Django 1.11, change 'Player' to
'Account', rework the website template and a slew of other updates.
Info on what changed and how to migrate is found here:
https://groups.google.com/forum/#!msg/evennia/0JYYNGY-NfE/cDFaIwmPBAAJ
## Feb 2017:
New devel branch created, to lead up to Evennia 0.7.
## Dec 2016:
Lots of bugfixes and considerable uptick in contributors. Unittest coverage
and PEP8 adoption and refactoring.
## May 2016:
Evennia 0.6 with completely reworked Out-of-band system, making
the message path completely flexible and built around input/outputfuncs.
A completely new webclient, split into the evennia.js library and a
gui library, making it easier to customize.
## Feb 2016:
Added the new EvMenu and EvMore utilities, updated EvEdit and cleaned up
a lot of the batchcommand functionality. Started work on new Devel branch.
## Sept 2015:
Evennia 0.5. Merged devel branch, full library format implemented.
## Feb 2015:
Development currently in devel/ branch. Moved typeclasses to use
django's proxy functionality. Changed the Evennia folder layout to a
library format with a stand-alone launcher, in preparation for making
an 'evennia' pypy package and using versioning. The version we will
merge with will likely be 0.5. There is also work with an expanded
testing structure and the use of threading for saves. We also now
use Travis for automatic build checking.
## Sept 2014:
Updated to Django 1.7+ which means South dependency was dropped and
minimum Python version upped to 2.7. MULTISESSION_MODE=3 was added
and the web customization system was overhauled using the latest
functionality of django. Otherwise, mostly bug-fixes and
implementation of various smaller feature requests as we got used
to github. Many new users have appeared.
## Jan 2014:
Moved Evennia project from Google Code to github.com/evennia/evennia.
## Nov 2013:
Moved the internal webserver into the Server and added support for
out-of-band protocols (MSDP initially). This large development push
also meant fixes and cleanups of the way attributes were handled.
Tags were added, along with proper handlers for permissions, nicks
and aliases.
## May 2013:
Made players able to control more than one Character at the same
time, through the MULTISESSION_MODE=2 addition. This lead to a lot
of internal changes for the server.
## Oct 2012:
Changed Evennia from the Modified Artistic 1.0 license to the more
standard and permissive BSD license. Lots of updates and bug fixes as
more people start to use it in new ways. Lots of new caching and
speed-ups.
## March 2012:
Evennia's API has changed and simplified slightly in that the
base-modules where removed from game/gamesrc. Instead admins are
encouraged to explicitly create new modules under game/gamesrc/ when
they want to implement their game - gamesrc/ is empty by default
except for the example folders that contain template files to use for
this purpose. We also added the ev.py file, implementing a new, flat
API. Work is ongoing to add support for mud-specific telnet
extensions, notably the MSDP and GMCP out-of-band extensions. On the
community side, evennia's dev blog was started and linked on planet
Mud-dev aggregator.
## Nov 2011:
After creating several different proof-of-concept game systems (in
contrib and privately) as well testing lots of things to make sure the
implementation is basically sound, we are declaring Evennia out of
Alpha. This can mean as much or as little as you want, admittedly -
development is still heavy but the issue list is at an all-time low
and the server is slowly stabilizing as people try different things
with it. So Beta it is!
## Aug 2011:
Split Evennia into two processes: Portal and Server. After a lot of
work trying to get in-memory code-reloading to work, it's clear this
is not Python's forte - it's impossible to catch all exceptions,
especially in asynchronous code like this. Trying to do so results in
hackish, flakey and unstable code. With the Portal-Server split, the
Server can simply be rebooted while players connected to the Portal
remain connected. The two communicates over twisted's AMP protocol.
## May 2011:
The new version of Evennia, originally hitting trunk in Aug2010, is
maturing. All commands from the pre-Aug version, including IRC/IMC2
support works again. An ajax web-client was added earlier in the year,
including moving Evennia to be its own webserver (no more need for
Apache or django-testserver). Contrib-folder added.
## Aug 2010:
Evennia-griatch-branch is ready for merging with trunk. This marks a
rather big change in the inner workings of the server, such as the
introduction of TypeClasses and Scripts (as compared to the old
ScriptParents and Events) but should hopefully bring everything
together into one consistent package as code development continues.
## May 2010:
Evennia is currently being heavily revised and cleaned from
the years of gradual piecemeal development. It is thus in a very
'Alpha' stage at the moment. This means that old code snippets
will not be backwards compatabile. Changes touch almost all
parts of Evennia's innards, from the way Objects are handled
to Events, Commands and Permissions.
## April 2010:
Griatch takes over Maintainership of the Evennia project from
the original creator Greg Taylor.
# Older
Earlier revisions, with previous maintainer, used SVN on Google Code
and have no changelogs.
First commit (Evennia's birthday) was November 20, 2006.

557
docs/source/Setup/Extended-Installation.md
View file

@ -1,557 +0,0 @@
# Getting Started
This will help you download, install and start Evennia for the first time.
> Note: You don't need to make anything visible to the 'net in order to run and
> test out Evennia. Apart from downloading and updating you don't even need an
> internet connection until you feel ready to share your game with the world.
- [Quick Start](#quick-start)
- [Requirements](#requirements)
- [Linux Install](#linux-install)
- [Mac Install](#mac-install)
- [Windows Install](#windows-install)
- [Running in Docker](./Running-Evennia-in-Docker.md)
- [Where to Go Next](#where-to-go-next)
- [Troubleshooting](#troubleshooting)
- [Glossary of terms](../Glossary.md)
## Quick Start
For the impatient. If you have trouble with a step, you should jump on to the
more detailed instructions for your platform.
1. Install Python, GIT and python-virtualenv. Start a Console/Terminal.
2. `cd` to some place you want to do your development (like a folder
`/home/anna/muddev/` on Linux or a folder in your personal user directory on Windows).
3. `git clone https://github.com/evennia/evennia.git` (a new folder `evennia` is created)
4. `python -m venv evenv` (a new folder `evenv` is created)
5. `source evenv/bin/activate` (Linux, Mac), `evenv\Scripts\activate` (Windows)
6. `pip install -e evennia`
7. `evennia --init mygame`
8. `cd mygame`
9. `evennia migrate`
10. `evennia start` (make sure to make a superuser when asked)
Evennia should now be running and you can connect to it by pointing a web browser to
`http://localhost:4001` or a MUD telnet client to `localhost:4000` (use `127.0.0.1` if your OS does
not recognize `localhost`).
We also release [Docker images](./Running-Evennia-in-Docker.md)
based on `master` and `develop` branches.
## Requirements
Any system that supports Python3.7+ should work. We'll describe how to install
everything in the following sections.
- Linux/Unix
- Windows (Vista, Win7, Win8, Win10)
- Mac OSX (>=10.5 recommended)
- [Python](https://www.python.org) (v3.7, 3.8 and 3.9 are tested)
- [virtualenv](https://pypi.python.org/pypi/virtualenv) for making isolated
Python environments. Installed with `pip install virtualenv`.
- [GIT](https://git-scm.com/) - version control software for getting and
updating Evennia itself - Mac users can use the
[git-osx-installer](https://code.google.com/p/git-osx-installer/) or the
[MacPorts version](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
- [Twisted](https://twistedmatrix.com) (v19.0+)
- [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.
- Windows users need [MS Visual C++](https://aka.ms/vs/16/release/vs_buildtools.exe) and *maybe*
[pypiwin32](https://pypi.python.org/pypi/pypiwin32).
- [Django](https://www.djangoproject.com) (v2.2.x), be warned that latest dev
version is usually untested with Evennia)
## Linux Install
If you run into any issues during the installation and first start, please
check out [Linux Troubleshooting](#linux-troubleshooting).
For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the [dependencies](#requirements):
```
sudo apt-get update
sudo apt-get install python3 python3-pip python3-dev python3-setuptools python3-git
python3-virtualenv gcc
# If you are using an Ubuntu version that defaults to Python3, like 18.04+, use this instead:
sudo apt-get update
sudo apt-get install python3.7 python3-pip python3.7-dev python3-setuptools virtualenv gcc
```
Note that, the default Python version for your distribution may still not be Python3.7 after this.
This is ok - we'll specify exactly which Python to use later.
You should make sure to *not* be `root` after this step, running as `root` is a
security risk. Now create a folder where you want to do all your Evennia
development:
```
mkdir muddev
cd muddev
```
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on
virtualenv](../Glossary.md#virtualenv).
Run `python -V` to see which version of Python your system defaults to.
```
# If your Linux defaults to Python3.7+:
virtualenv evenv
# If your Linux defaults to Python2 or an older version
# of Python3, you must instead point to Python3.7+ explicitly:
virtualenv -p /usr/bin/python3.7 evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system (or the Linux distro lagging behind
on Python package versions). It will also always use the right version of Python.
Activate the virtualenv:
```
source evenv/bin/activate
```
The text `(evenv)` should appear next to your prompt to show that the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new terminal to get access to the Python packages (notably the
> important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia/` and `evenv/`
folders) and run
```
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](../Glossary.md#pip). If
install failed with any issues, see [Linux Troubleshooting](#linux-troubleshooting).
Next we'll start our new game, here called "mygame". This will create yet
another new folder where you will be creating your new game:
```
evennia --init mygame
```
Your final folder structure should look like this:
```
./muddev
evenv/
evennia/
mygame/
```
You can [configure Evennia](./Server-Conf.md#settings-file) extensively, for example
to use a [different database](./Choosing-An-SQL-Server.md). For now we'll just stick
to the defaults though.
```
cd mygame
evennia migrate # (this creates the database)
evennia start # (create a superuser when asked. Email is optional.)
```
> Server logs are found in `mygame/server/logs/`. To easily view server logs
> live in the terminal, use `evennia -l` (exit the log-view with Ctrl-C).
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](#where-to-go-next).
## Mac Install
The Evennia server is a terminal program. Open the terminal e.g. from
*Applications->Utilities->Terminal*. [Here is an introduction to the Mac
terminal](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
if you are unsure how it works. If you run into any issues during the
installation, please check out [Mac Troubleshooting](#mac-troubleshooting).
* Python should already be installed but you must make sure it's a high enough version.
([This](https://docs.python-guide.org/en/latest/starting/install/osx/) discusses
how you may upgrade it). Remember that you need Python3.7, not Python2.7!
* GIT can be obtained with
[git-osx-installer](https://code.google.com/p/git-osx-installer/) or via
MacPorts [as described
here](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
* If you run into issues with installing `Twisted` later you may need to
install gcc and the Python headers.
After this point you should not need `sudo` or any higher privileges to install anything.
Now create a folder where you want to do all your Evennia development:
```
mkdir muddev
cd muddev
```
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on virtualenv](../Glossary.md#virtualenv).
Run `python -V` to check which Python your system defaults to.
```
# If your Mac defaults to Python3:
virtualenv evenv
# If your Mac defaults to Python2 you need to specify the Python3.7 binary explicitly:
virtualenv -p /path/to/your/python3.7 evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:
```
source evenv/bin/activate
```
The text `(evenv)` should appear next to your prompt to show the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new terminal to get access to the Python packages (notably the
> important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia/` and `evenv/`
folders) and run
```
pip install --upgrade pip # Old pip versions may be an issue on Mac.
pip install --upgrade setuptools # Ditto concerning Mac issues.
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](../Glossary.md#pip). If
install failed with any issues, see [Mac Troubleshooting](#mac-troubleshooting).
Next we'll start our new game. We'll call it "mygame" here. This creates a new
folder where you will be creating your new game:
```
evennia --init mygame
```
Your final folder structure should look like this:
```
./muddev
evenv/
evennia/
mygame/
```
You can [configure Evennia](./Server-Conf.md#settings-file) extensively, for example
to use a [different database](./Choosing-An-SQL-Server.md). We'll go with the
defaults here.
```
cd mygame
evennia migrate # (this creates the database)
evennia start # (create a superuser when asked. Email is optional.)
```
> Server logs are found in `mygame/server/logs/`. To easily view server logs
> live in the terminal, use `evennia -l` (exit the log-view with Ctrl-C).
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](#where-to-go-next).
## Windows Install
If you run into any issues during the installation, please check out
[Windows Troubleshooting](#windows-troubleshooting).
> If you are running Windows10, consider using the Windows Subsystem for Linux
> ([WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)) instead.
> You should then follow the Linux install instructions above.
The Evennia server itself is a command line program. In the Windows launch
menu, start *All Programs -> Accessories -> command prompt* and you will get
the Windows command line interface. Here is [one of many tutorials on using the Windows command
line](https://www.bleepingcomputer.com/tutorials/windows-command-prompt-introduction/)
if you are unfamiliar with it.
* Install Python [from the Python homepage](https://www.python.org/downloads/windows/). You will
need to be a
Windows Administrator to install packages. You want Python version **3.7.0** (latest verified
version), usually
the 64-bit version (although it doesn't matter too much). **When installing, 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.
* You need to also get [GIT](https://git-scm.com/downloads) and install it. You
can use the default install options but when you get asked to "Adjust your PATH
environment", you should select the second option "Use Git from the Windows
Command Prompt", which gives you more freedom as to where you can use the
program.
* Finally you must install the [Microsoft Visual C++ compiler for
Python](https://aka.ms/vs/16/release/vs_buildtools.exe). Download and run the linked installer and
install the C++ tools. Keep all the defaults. Allow the install of the "Win10 SDK", even if you are
on Win7 (not tested on older Windows versions). If you later have issues with installing Evennia due
to a failure to build the "Twisted wheels", this is where you are missing things.
* You *may* need the [pypiwin32](https://pypi.python.org/pypi/pypiwin32) Python headers. Install
these only if you have issues.
You can install Evennia wherever you want. `cd` to that location and create a
new folder for all your Evennia development (let's call it `muddev`).
```
mkdir muddev
cd muddev
```
> Hint: If `cd` isn't working you can use `pushd` instead to force the
> directory change.
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on virtualenv](../Glossary.md#virtualenv).
In your console, try `python -V` to see which version of Python your system
defaults to.
```
pip install virtualenv
# If your setup defaults to Python3.7:
virtualenv evenv
# If your setup defaults to Python2, specify path to python3.exe explicitly:
virtualenv -p C:\Python37\python.exe evenv
# If you get an infinite spooling response, press CTRL + C to interrupt and try using:
python -m venv evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:
```
# If you are using a standard command prompt, you can use the following:
evenv\scripts\activate.bat
# If you are using a PS Shell, Git Bash, or other, you can use the following:
.\evenv\scripts\activate
```
The text `(evenv)` should appear next to your prompt to show the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new console window if you want to get access to the Python packages
> (notably the important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia` and `evenv`
folders when you use the `dir` command) and run
```
pip install -e evennia
```
For more info about `pip`, see the [Glossary entry on pip](../Glossary.md#pip). If
the install failed with any issues, see [Windows Troubleshooting](#windows-
troubleshooting).
Next we'll start our new game, we'll call it "mygame" here. This creates a new folder where you will
be
creating your new game:
```
evennia --init mygame
```
Your final folder structure should look like this:
```
path\to\muddev
evenv\
evennia\
mygame\
```
You can [configure Evennia](./Server-Conf.md#settings-file) extensively, for example
to use a [different database](./Choosing-An-SQL-Server.md). We'll go with the
defaults here.
```
cd mygame
evennia migrate # (this creates the database)
evennia start # (create a superuser when asked. Email is optional.)
```
> Server logs are found in `mygame/server/logs/`. To easily view server logs
> live in the terminal, use `evennia -l` (exit the log-view with Ctrl-C).
Your game should now be running! Open a web browser at `http://localhost:4001`
or point a telnet client to `localhost:4000` and log in with the user you
created. Check out [where to go next](#where-to-go-next).
## Non-interactive setup
When you first run `evennia start` after having created the database, you will be asked
to interactively insert the superuser username, email and password. If you need to do
this in an automated faction (such as in an automated build flow), you can supply those
values as environment variables, `EVENNIA_SUPERUSER_USERNAME`, `EVENNIA_SUPERUSER_EMAIL` and
`EVENNIA_SUPERUSER_PASSWORD`. The email can be left out and will then be set to be the
empty string.
Use this to start Evennia (the envvars will be ignored on subsequent starts):
```
EVENNIA_SUPERUSER_USERNAME=Foo EVENNIA_SUPERUSER_PASSWORD=MygreatPwd evennia start
```
## Where to Go Next
Welcome to Evennia! Your new game is fully functioning, but empty. If you just
logged in, stand in the `Limbo` room and run
@batchcommand tutorial_world.build
to build [Evennia's tutorial world](../Howto/Starting/Part1/Tutorial-World-Introduction.md) - it's a small solo quest to
explore. Only run the instructed `@batchcommand` once. You'll get a lot of text scrolling by as the
tutorial is built. Once done, the `tutorial` exit will have appeared out of Limbo - just write
`tutorial` to enter it.
Once you get back to `Limbo` from the tutorial (if you get stuck in the tutorial quest you can do
`@tel #2` to jump to Limbo), a good idea is to learn how to [start, stop and reload](Start-Stop-
Reload) the Evennia server. You may also want to familiarize yourself with some
[commonly used terms in our Glossary](../Glossary.md). After that, why not experiment with
[creating some new items and build some new rooms](../Howto/Starting/Part1/Building-Quickstart.md) out from Limbo.
From here on, you could move on to do one of our [introductory tutorials](../Howto/Howto-Overview.md) or simply dive
headlong into Evennia's comprehensive [manual](https://github.com/evennia/evennia/wiki). While
Evennia has no major game systems out of the box, we do supply a range of optional *contribs* that
you can use or borrow from. They range from dice rolling and alternative color schemes to barter and
combat systems. You can find the [growing list of contribs
here](https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md).
If you have any questions, you can always ask in [the developer
chat](https://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb)
`#evennia` on `irc.freenode.net` or by posting to the [Evennia
forums](https://groups.google.com/forum/#%21forum/evennia). You can also join the [Discord
Server](https://discord.gg/NecFePw).
Finally, if you are itching to help out or support Evennia (awesome!) have an
issue to report or a feature to request, [see here](../Contributing.md).
Enjoy your stay!
## Troubleshooting
If you have issues with installing or starting Evennia for the first time,
check the section for your operating system below. If you have an issue not
covered here, [please report it](https://github.com/evennia/evennia/issues)
so it can be fixed or a workaround found!
Remember, the server logs are in `mygame/server/logs/`. To easily view server logs in the terminal,
you can run `evennia -l`, or (in the future) start the server with `evennia start -l`.
### Linux Troubleshooting
- If you get an error when installing Evennia (especially with lines mentioning
failing to include `Python.h`) then try `sudo apt-get install python3-setuptools python3-dev`.
Once installed, run `pip install -e evennia` again.
- Under some not-updated Linux distributions you may run into errors with a
too-old `setuptools` or missing `functools`. If so, update your environment
with `pip install --upgrade pip wheel setuptools`. Then try `pip install -e evennia` again.
- If you get an `setup.py not found` error message while trying to `pip install`, make sure you are
in the right directory. You should be at the same level of the `evenv` directory, and the
`evennia` git repository. Note that there is an `evennia` directory inside of the repository too.
- One user reported a rare issue on Ubuntu 16 is an install error on installing Twisted; `Command
"python setup.py egg_info" failed with error code 1 in /tmp/pip-build-vnIFTg/twisted/` with errors
like `distutils.errors.DistutilsError: Could not find suitable distribution for
Requirement.parse('incremental>=16.10.1')`. This appears possible to solve by simply updating Ubuntu
with `sudo apt-get update && sudo apt-get dist-upgrade`.
- Users of Fedora (notably Fedora 24) has reported a `gcc` error saying the directory
`/usr/lib/rpm/redhat/redhat-hardened-cc1` is missing, despite `gcc` itself being installed. [The
confirmed work-around](https://gist.github.com/yograterol/99c8e123afecc828cb8c) seems to be to
install the `redhat-rpm-config` package with e.g. `sudo dnf install redhat-rpm-config`.
- Some users trying to set up a virtualenv on an NTFS filesystem find that it fails due to issues
with symlinks not being supported. Answer is to not use NTFS (seriously, why would you do that to
yourself?)
### Mac Troubleshooting
- Mac users have reported a critical `MemoryError` when trying to start Evennia on Mac with a Python
version below `2.7.12`. If you get this error, update to the latest XCode and Python2 version.
- Some Mac users have reported not being able to connect to `localhost` (i.e. your own computer). If
so, try to connect to `127.0.0.1` instead, which is the same thing. Use port 4000 from mud clients
and port 4001 from the web browser as usual.
### Windows Troubleshooting
- If you installed Python but the `python` command is not available (even in a new console), then
you might have missed installing Python on the path. In the Windows Python installer you get a list
of options for what to install. Most or all options are pre-checked except this one, and you may
even have to scroll down to see it. Reinstall Python and make sure it's checked.
- If your MUD client cannot connect to `localhost:4000`, try the equivalent `127.0.0.1:4000`
instead. Some MUD clients on Windows does not appear to understand the alias `localhost`.
- If you run `virtualenv evenv` and get a `'virtualenv' is not recognized as an internal or external
command,
operable program or batch file.` error, you can `mkdir evenv`, `cd evenv` and then `python -m
virtualenv .` as a workaround.
- Some Windows users get an error installing the Twisted 'wheel'. A wheel is a pre-compiled binary
package for Python. A common reason for this error is that you are using a 32-bit version of Python,
but Twisted has not yet uploaded the latest 32-bit wheel. Easiest way to fix this is to install a
slightly older Twisted version. So if, say, version `18.1` failed, install `18.0` manually with `pip
install twisted==18.0`. Alternatively you could try to get a 64-bit version of Python (uninstall the
32bit one). If so, you must then `deactivate` the virtualenv, delete the `evenv` folder and recreate
it anew (it will then use the new Python executable).
- If your server won't start, with no error messages (and no log files at all when starting from
scratch), try to start with `evennia ipstart` instead. If you then see an error about `system cannot
find the path specified`, it may be that the file `evennia/evennia/server/twistd.bat` has the wrong
path to the `twistd` executable. This file is auto-generated, so try to delete it and then run
`evennia start` to rebuild it and see if it works. If it still doesn't work you need to open it in a
text editor like Notepad. It's just one line containing the path to the `twistd.exe` executable as
determined by Evennia. If you installed Twisted in a non-standard location this might be wrong and
you should update the line to the real location.
- Some users have reported issues with Windows WSL and anti-virus software during Evennia
development. Timeout errors and the inability to run `evennia connections` may be due to your anti-
virus software interfering. Try disabling or changing your anti-virus software settings.

11
docs/source/Setup/Installing-on-Android.md → docs/source/Setup/Installation-Android.md
View file

@ -5,6 +5,11 @@ This page describes how to install and run the Evennia server on an Android phon
installing a slew of third-party programs from the Google Play store, so make sure you are okay with
this before starting.
```warning
Android installation is experimental and not tested with later versions of Android.
Report your findings.
```
## Install Termux
The first thing to do is install a terminal emulator that allows a "full" version of linux to be
@ -80,7 +85,7 @@ Install the latest Evennia in a way that lets you edit the source
This step will possibly take quite a while - we are downloading Evennia and are then installing it,
building all of the requirements for Evennia to run. If you run into trouble on this step, please
see [Troubleshooting](./Installing-on-Android.md#troubleshooting).
see [Troubleshooting](./Installation-Android.md#troubleshooting).
You can go to the dir where Evennia is installed with `cd $VIRTUAL_ENV/src/evennia`. `git grep
(something)` can be handy, as can `git diff`
@ -88,7 +93,7 @@ You can go to the dir where Evennia is installed with `cd $VIRTUAL_ENV/src/evenn
### Final steps
At this point, Evennia is installed on your phone! You can now continue with the original
[Setup Quickstart](./Setup-Quickstart.md) instruction, we repeat them here for clarity.
[Setup Quickstart](./Installation.md) instruction, we repeat them here for clarity.
To start a new game:
@ -120,7 +125,7 @@ $ cd ~ && source evenv/bin/activate
(evenv) $ evennia start
```
You may wish to look at the [Linux Instructions](./Extended-Installation.md#linux-install) for more.
You may wish to look at the [Linux Instructions](./Installation-Git.md#linux-install) for more.
## Caveats

2
docs/source/Setup/Running-Evennia-in-Docker.md → docs/source/Setup/Installation-Docker.md
View file

@ -34,7 +34,7 @@ evennia|docker /usr/src/game $
This is a normal shell prompt. We are in the `/usr/src/game` location inside the docker container.
If you had anything in the folder you started from, you should see it here (with `ls`) since we
mounted the current directory to `usr/src/game` (with `-v` above). You have the `evennia` command
available and can now proceed to create a new game as per the [Setup Quickstart](./Setup-Quickstart.md)
available and can now proceed to create a new game as per the [Setup Quickstart](./Installation.md)
instructions (you can skip the virtualenv and install 'globally' in the container though).
You can run Evennia from inside this container if you want to, it's like you are root in a little

302
docs/source/Setup/Installation-Git.md Normal file
View file

@ -0,0 +1,302 @@
# 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
a quick installation of the library. See the [troubleshooting](./Installation-Troubleshooting.md) if you run
into trouble.
- [Quick Start](#quick-start)
- [Linux Install](#linux-install)
- [Mac Install](#mac-install)
- [Windows Install](#windows-install)
- [Running in Docker](./Installation-Docker.md)
- [Where to Go Next](#where-to-go-next)
- [Troubleshooting](#troubleshooting)
- [Glossary of terms](../Glossary.md)
## Summary
For the impatient. If you have trouble with a step, you should jump on to the
more detailed instructions for your platform.
1. Install Python, GIT and python-virtualenv. Start a Console/Terminal.
2. `cd` to some place you want to do your development (like a folder
`/home/anna/muddev/` on Linux or a folder in your personal user directory on Windows).
3. `git clone https://github.com/evennia/evennia.git` (a new folder `evennia` is created)
4. `python3.10 -m venv evenv` (a new folder `evenv` is created)
5. `source evenv/bin/activate` (Linux, Mac), `evenv\Scripts\activate` (Windows)
6. `pip install -e evennia`
7. `evennia --init mygame`
8. `cd mygame`
9. `evennia migrate`
10. `evennia start` (make sure to make a superuser when asked)
Evennia should now be running and you can connect to it by pointing a web browser to
`http://localhost:4001` or a MUD telnet client to `localhost:4000` (use `127.0.0.1` if your OS does
not recognize `localhost`).
## Linux Install
If you run into any issues during the installation and first start, please
check out [Linux Troubleshooting](#linux-troubleshooting).
For Debian-derived systems (like Ubuntu, Mint etc), start a terminal and
install the [dependencies](#requirements):
```
sudo apt-get update
sudo apt-get install python3.10 python3.10-venv python3.10-dev gcc
```
You should make sure to *not* be `root` after this step, running as `root` is a
security risk. Now create a folder where you want to do all your Evennia
development:
```
mkdir muddev
cd muddev
```
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on
virtualenv](../Glossary.md#virtualenv).
```
python3.10 -m venv evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system (or the Linux distro lagging behind
on Python package versions). It will also always use the right version of Python.
Activate the virtualenv:
```
source evenv/bin/activate
```
The text `(evenv)` should appear next to your prompt to show that the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new terminal to get access to the Python packages (notably the
> important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia/` and `evenv/`
folders) and run
```
pip install -e evennia
```
Test that you can run the `evennia` command everywhere while your virtualenv (evenv) is active.
Next you can continue initializing your game from the regular [Installation instructions](./Installation.md).
## Mac Install
The Evennia server is a terminal program. Open the terminal e.g. from
*Applications->Utilities->Terminal*. [Here is an introduction to the Mac
terminal](https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
if you are unsure how it works. If you run into any issues during the
installation, please check out [Mac Troubleshooting](#mac-troubleshooting).
* Python should already be installed but you must make sure it's a high enough version - go for
3.10.
([This](https://docs.python-guide.org/en/latest/starting/install/osx/) discusses
how you may upgrade it).
* GIT can be obtained with
[git-osx-installer](https://code.google.com/p/git-osx-installer/) or via MacPorts [as described
here](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
* If you run into issues with installing `Twisted` later you may need to
install gcc and the Python headers.
After this point you should not need `sudo` or any higher privileges to install anything.
Now create a folder where you want to do all your Evennia development:
```
mkdir muddev
cd muddev
```
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on virtualenv](../Glossary.md#virtualenv).
```
python3.10 -m venv evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:
```
source evenv/bin/activate
```
The text `(evenv)` should appear next to your prompt to show the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new terminal to get access to the Python packages (notably the
> important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia/` and `evenv/`
folders) and run
```
pip install --upgrade pip # Old pip versions may be an issue on Mac.
pip install --upgrade setuptools # Ditto concerning Mac issues.
pip install -e evennia
```
Test that you can run the `evennia` command everywhere while your virtualenv (evenv) is active.
Next you can continue initializing your game from the regular [Installation instructions](./Installation.md).
## Windows Install
> If you are running Windows10, consider using the _Windows Subsystem for Linux_
> ([WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux)) instead.
> Just set up WSL with an Ubuntu image and follow the Linux install instructions above.
The Evennia server itself is a command line program. In the Windows launch
menu, start *All Programs -> Accessories -> command prompt* and you will get
the Windows command line interface. Here is [one of many tutorials on using the Windows command
line](https://www.bleepingcomputer.com/tutorials/windows-command-prompt-introduction/)
if you are unfamiliar with it.
* Install Python [from the Python homepage](https://www.python.org/downloads/windows/). You will
need to be a
Windows Administrator to install packages. Get Python any version of Python **3.10**, usually
the 64-bit version (although it doesn't matter too much). **When installing, 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.
* You need to also get [GIT](https://git-scm.com/downloads) and install it. You
can use the default install options but when you get asked to "Adjust your PATH
environment", you should select the second option "Use Git from the Windows
Command Prompt", which gives you more freedom as to where you can use the
program.
* Finally you must install the [Microsoft Visual C++ compiler for
Python](https://aka.ms/vs/16/release/vs_buildtools.exe). Download and run the linked installer and
install the C++ tools. Keep all the defaults. Allow the install of the "Win10 SDK", even if you are
on Win7 (not tested on older Windows versions). If you later have issues with installing Evennia due
to a failure to build the "Twisted wheels", this is where you are missing things.
* You *may* need the [pypiwin32](https://pypi.python.org/pypi/pypiwin32) Python headers. Install
these only if you have issues.
You can install Evennia wherever you want. `cd` to that location and create a
new folder for all your Evennia development (let's call it `muddev`).
```
mkdir muddev
cd muddev
```
> Hint: If `cd` isn't working you can use `pushd` instead to force the
> directory change.
Next we fetch Evennia itself:
```
git clone https://github.com/evennia/evennia.git
```
A new folder `evennia` will appear containing the Evennia library. This only
contains the source code though, it is not *installed* yet. To isolate the
Evennia install and its dependencies from the rest of the system, it is good
Python practice to install into a _virtualenv_. If you are unsure about what a
virtualenv is and why it's useful, see the [Glossary entry on virtualenv](../Glossary.md#virtualenv).
```
python3.10 -m venv evenv
```
A new folder `evenv` will appear (we could have called it anything). This
folder will hold a self-contained setup of Python packages without interfering
with default Python packages on your system. Activate the virtualenv:
```
# If you are using a standard command prompt, you can use the following:
evenv\scripts\activate.bat
# If you are using a PS Shell, Git Bash, or other, you can use the following:
.\evenv\scripts\activate
```
The text `(evenv)` should appear next to your prompt to show the virtual
environment is active.
> Remember that you need to activate the virtualenv like this *every time* you
> start a new console window if you want to get access to the Python packages
> (notably the important `evennia` program) we are about to install.
Next, install Evennia into your active virtualenv. Make sure you are standing
at the top of your mud directory tree (so you see the `evennia` and `evenv`
folders when you use the `dir` command) and run
```
pip install -e evennia
```
Test that you can run the `evennia` command everywhere while your virtualenv (evenv) is active.
Next you can continue initializing your game from the regular [Installation instructions](./Installation.md).
## Where to Go Next
Welcome to Evennia! Your new game is fully functioning, but empty. If you just
logged in, stand in the `Limbo` room and run
@batchcommand tutorial_world.build
to build [Evennia's tutorial world](../Howto/Starting/Part1/Tutorial-World.md) - it's a small solo quest to
explore. Only run the instructed `@batchcommand` once. You'll get a lot of text scrolling by as the
tutorial is built. Once done, the `tutorial` exit will have appeared out of Limbo - just write
`tutorial` to enter it.
Once you get back to `Limbo` from the tutorial (if you get stuck in the tutorial quest you can do
`@tel #2` to jump to Limbo), a good idea is to learn how to [start, stop and reload](Start-Stop-
Reload) the Evennia server. You may also want to familiarize yourself with some
[commonly used terms in our Glossary](../Glossary.md). After that, why not experiment with
[creating some new items and build some new rooms](../Howto/Starting/Part1/Building-Quickstart.md) out from Limbo.
From here on, you could move on to do one of our [introductory tutorials](../Howto/Howto-Overview.md) or simply dive
headlong into Evennia's comprehensive [manual](https://github.com/evennia/evennia/wiki). While
Evennia has no major game systems out of the box, we do supply a range of optional *contribs* that
you can use or borrow from. They range from dice rolling and alternative color schemes to barter and
combat systems. You can find the [growing list of contribs
here](https://github.com/evennia/evennia/blob/master/evennia/contrib/README.md).
If you have any questions, you can always ask in [the developer
chat](https://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb)
`#evennia` on `irc.freenode.net` or by posting to the [Evennia
forums](https://groups.google.com/forum/#%21forum/evennia). You can also join the [Discord
Server](https://discord.gg/NecFePw).
Finally, if you are itching to help out or support Evennia (awesome!) have an
issue to report or a feature to request, [see here](../Contributing.md).
Enjoy your stay!

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

@ -0,0 +1,19 @@
# Non-interactive setup
The first ime 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.
You can have the superuser be created automatically by passing environment variables to your
build script:
- `EVENNIA_SUPERUSER_USERNAME`
- `EVENNIA_SUPERUSER_PASSWORD`
- `EVENNIA_SUPERUSER_EMAIL` is optional. If not given, empty string is used.
These envvars will only be used on the _very first_ server start and then ignored. For example:
```
EVENNIA_SUPERUSER_USERNAME=myname EVENNIA_SUPERUSER_PASSWORD=mypwd evennia start
```

115
docs/source/Setup/Installation-Troubleshooting.md Normal file
View file

@ -0,0 +1,115 @@
# Installation Troubleshooting
If you have an issue not covered here, [please report it](https://github.com/evennia/evennia/issues/new/choose)
so it can be fixed or a workaround found!
The server logs are in `mygame/server/logs/`. To easily view server logs in the terminal,
you can run `evennia -l`, or (in the future) start the server with `evennia start -l`.
## Check your Requirements
Any system that supports Python3.9+ should work. We'll describe how to install
everything in the following sections.
- Linux/Unix
- Windows (Win7, Win8, Win10, Win11)
- Mac OSX (>10.5 recommended)
- [Python](https://www.python.org) (v3.9 and 3.10 are tested)
- [virtualenv](https://pypi.python.org/pypi/virtualenv) for making isolated
Python environments. Installed with `pip install virtualenv`.
- [Twisted](https://twistedmatrix.com) (v22.0+)
- [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.
- Windows users need [MS Visual C++](https://aka.ms/vs/16/release/vs_buildtools.exe) and *maybe*
[pypiwin32](https://pypi.python.org/pypi/pypiwin32).
- [Django](https://www.djangoproject.com) (v4.0.1+), be warned that latest dev
version is usually untested with Evennia.
- [GIT](https://git-scm.com/) - version control software used if you want to install the sources
(but also useful to track your own code) - Mac users can use the
[git-osx-installer](https://code.google.com/p/git-osx-installer/) or the
[MacPorts version](https://git-scm.com/book/en/Getting-Started-Installing-Git#Installing-on-Mac).
## Confusion of location (GIT installation)
It's common to be confused and install Evennia in the wrong location. After following the
[git install](./Installation-Git.md) instructions, the folder structure should look like this:
```
muddev/
evenv/
evennia/
mygame/
```
The evennia code itself is found inside `evennia/evennia/` (so two levels down). Your settings file
is `mygame/server/conf/settings.py` and the _parent_ setting file is `evennia/evennia/settings_default.py`.
## Localhost not found
If `localhost` doesn't work when trying to connect to your local game, try `127.0.0.1`, which is the same thing.
## Linux Troubleshooting
- If you get an error when installing Evennia (especially with lines mentioning
failing to include `Python.h`) then try `sudo apt-get install python3-setuptools python3-dev`.
Once installed, run `pip install -e evennia` again.
- When doing a [git install](./Installation-Git.md), some not-updated Linux distributions may give errors
about a too-old `setuptools` or missing `functools`. If so, update your environment
with `pip install --upgrade pip wheel setuptools`. Then try `pip install -e evennia` again.
- One user reported a rare issue on Ubuntu 16 is an install error on installing Twisted; `Command
"python setup.py egg_info" failed with error code 1 in /tmp/pip-build-vnIFTg/twisted/` with errors
like `distutils.errors.DistutilsError: Could not find suitable distribution for
Requirement.parse('incremental>=16.10.1')`. This appears possible to solve by simply updating Ubuntu
with `sudo apt-get update && sudo apt-get dist-upgrade`.
- Users of Fedora (notably Fedora 24) has reported a `gcc` error saying the directory
`/usr/lib/rpm/redhat/redhat-hardened-cc1` is missing, despite `gcc` itself being installed. [The
confirmed work-around](https://gist.github.com/yograterol/99c8e123afecc828cb8c) seems to be to
install the `redhat-rpm-config` package with e.g. `sudo dnf install redhat-rpm-config`.
- Some users trying to set up a virtualenv on an NTFS filesystem find that it fails due to issues
with symlinks not being supported. Answer is to not use NTFS (seriously, why would you do that to
yourself?)
## Mac Troubleshooting
- Mac users have reported a critical `MemoryError` when trying to start Evennia on Mac with a Python
version below `2.7.12`. If you get this error, update to the latest XCode and Python2 version.
- Some Mac users have reported not being able to connect to `localhost` (i.e. your own computer). If
so, try to connect to `127.0.0.1` instead, which is the same thing. Use port 4000 from mud clients
and port 4001 from the web browser as usual.
## Windows Troubleshooting
- 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.
- If you get a `command not found` when trying to run the `evennia` program after installation, try closing the
Console and starting it again (remember to re-activate the virtualenv!). Sometimes Windows is not updating
its environment properly.
- If you installed Python but the `python` command is not available (even in a new console), then
you might have missed installing Python on the path. In the Windows Python installer you get a list
of options for what to install. Most or all options are pre-checked except this one, and you may
even have to scroll down to see it. Reinstall Python and make sure it's checked.
- If your MUD client cannot connect to `localhost:4000`, try the equivalent `127.0.0.1:4000`
instead. Some MUD clients on Windows does not appear to understand the alias `localhost`.
- Some Windows users get an error installing the Twisted 'wheel'. A wheel is a pre-compiled binary
package for Python. A common reason for this error is that you are using a 32-bit version of Python,
but Twisted has not yet uploaded the latest 32-bit wheel. Easiest way to fix this is to install a
slightly older Twisted version. So if, say, version `22.1` failed, install `22.0` manually with `pip
install twisted==22.0`. Alternatively you could check that you are using the 64-bit version of Python
and uninstall any 32bit one. If so, you must then `deactivate` the virtualenv, delete the `evenv` folder
and recreate it anew with your new Python.
- If your server won't start, with no error messages (and no log files at all when starting from
scratch), try to start with `evennia ipstart` instead. If you then see an error about `system cannot
find the path specified`, it may be that the file `evennia\evennia\server\twistd.bat` has the wrong
path to the `twistd` executable. This file is auto-generated, so try to delete it and then run
`evennia start` to rebuild it and see if it works. If it still doesn't work you need to open it in a
text editor like Notepad. It's just one line containing the path to the `twistd.exe` executable as
determined by Evennia. If you installed Twisted in a non-standard location this might be wrong and
you should update the line to the real location.
- Some users have reported issues with Windows WSL and anti-virus software during Evennia
development. Timeout errors and the inability to run `evennia connections` may be due to your anti-
virus software interfering. Try disabling or changing your anti-virus software settings.

44
docs/source/Setup/Installation-Upgrade.md Normal file
View file

@ -0,0 +1,44 @@
# Upgrading an existing installation
These are steps to take when you have an _exiting game dir that you want to keep_.
If you don't, you can always just delete your old game dir and initialize a fresh one using
the normal [install instructions](./Installation.md).
## Evennia v0.9.5 to 1.0
Prior to 1.0, all Evennia installs were [Git-installs](./Installation-Git.md). These instructions
assume that you have a cloned `evennia` repo and use a virtualenv (best practices).
- Make sure to stop Evennia 0.9.5 entirely with `evennia stop`.
- `deactivate` to leave your active virtualenv.
- Make a _backup_ of your entire `mygame` folder, just to be sure!
- Delete the old `evenv` folder, or rename it (in case you want to keep using 0.9.5 for a while).
- Install Python 3.10 (recommended) or 3.9. Follow the [Git-installation](./Installation-Git.md) for your OS if needed.
- If using virtualenv, make a _new_ one with `python3.10 -m venv evenv`, then activate with `source evenv/bin/activate`
(linux/mac) or `\evenv\Script\activate` (windows)
- `cd` into your `evennia/` folder (you want to see the `docs/`, `bin/` directories as well as a nested `evennia/` folder)
- **Prior to 1.0 release only** - do `git checkout develop` to switch to the develop branch. After release, this will
be found on the default master branch.
- `git pull`
- `pip install -e .`
- If you want the optional extra libs, do `pip install -r requirements_extra.txt`.
- Test that you can run the `evennia` command.
- Next, `cd` to your game folder (like `mygame`.)
- If you have changed `mygame/web`, _rename_ the folder to `web_0.9.5`. If you didn't change anything (or don't have
anything you want to keep), you can _delete_ it entirely.
- Copy `evennia/evennia/game_template/web` to `mygame/` (e.g. using `cp -Rf` or a file manager). This new `web` folder
replaces the old one and has a very different structure.
- `evennia migrate`
- `evennia start`
If you made extensive work in your game dir, you may well find that you need to do some (hopefully minor)
changes to your code before it will start with Evennia 1.0. Some important points:
- The `evennia/contrib/` folder changed structure - there are now categorized sub-folders, so you have to update
your imports.
- Any `web` changes need to be moved back from your backup into the new structure of `web/` manually.
- See the [Evennia 1.0 Changelog](./Changelog.md) for all changes.

110
docs/source/Setup/Installation.md Normal file
View file

@ -0,0 +1,110 @@
# 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).
```
```{warning}
If you are converting an existing game from a previous version, [see here](./Installation-Upgrade.md).
```
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-Troubleshootin.md) if you run into problems. Some
users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Initialize a new game
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.
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.
## Start the new game
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.
evennia start
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!
Log in as a new account or use the superuser you just created.
## Restarting and stopping
You can restart the server without disconnecting players:
evennia restart
To do a full stop and restart (will disconnect players):
evennia reboot
Full stop of the server (use `evennia start` to restart):
evennia stop
## See server logs
Log files are in `mygame/server/logs`. You can tail them live with
evennia --log
or
evennia -l
You can start viewing the log immediately when running `evennia` commands, such as
evennia start -l
To exit the log tailing, enter `Ctrl-C` (`Cmd-C` for Mac). This will not affect the server.
## 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 Next steps
You are good to go!
Evennia comes with a small [Tutorial World](../Howto/Starting/Part1/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](../Howto/Starting/Part1/Starting-Part1.md)
to learn how to start making your new game!

4
docs/source/Setup/Online-Setup.md
View file

@ -344,7 +344,7 @@ game stays online. Many services guarantee a certain level of up-time and also d
for you. Make sure to check, some offer lower rates in exchange for you yourself being fully
responsible for your data/backups.
- Usually offers a fixed domain name, so no need to mess with IP addresses.
- May have the ability to easily deploy [docker](./Running-Evennia-in-Docker.md) versions of evennia
- May have the ability to easily deploy [docker](./Installation-Docker.md) versions of evennia
and/or your game.
**Disadvantages**
@ -362,7 +362,7 @@ Docker) to deploy your game to the remote server; it will likely ease installati
Docker images may be a little confusing if you are completely new to them though.
If not using docker, and assuming you know how to connect to your account over ssh/PuTTy, you should
be able to follow the [Setup Quickstart](./Setup-Quickstart.md) instructions normally. You only need Python
be able to follow the [Setup Quickstart](./Installation.md) instructions normally. You only need Python
and GIT pre-installed; these should both be available on any servers (if not you should be able to
easily ask for them to be installed). On a VPS or Cloud service you can install them yourself as
needed.

2
docs/source/Setup/Server-Conf.md
View file

@ -8,7 +8,7 @@ ways to customize the server and expand it with your own plugins.
The "Settings" file referenced throughout the documentation is the file
`mygame/server/conf/settings.py`. This is automatically created on the first run of `evennia --init`
(see the [Setup Quickstart](./Setup-Quickstart.md) page).
(see the [Setup Quickstart](./Installation.md) page).
Your new `settings.py` is relatively bare out of the box. Evennia's core settings file is actually
[evennia/settings_default.py](https://github.com/evennia/evennia/blob/master/evennia/settings_default.py)

1201
docs/source/Setup/Settings-Default.md Normal file
View file

File diff suppressed because it is too large Load diff

3
docs/source/Setup/Settings-File.md
View file

@ -1,3 +0,0 @@
# The Evennia Default Settings file
TODO

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

@ -4,10 +4,10 @@ This documentation covers how to setup and maintain the server, from first insta
## Installation & running
- [Installation & Setup quick-start](./Setup-Quickstart.md) - one page to quickly get you going
- [Extended Install instructions](./Extended-Installation.md) - if you have trouble or want to contribute to Evennia itself
- [Running through Docker](./Running-Evennia-in-Docker.md) - alternative install method, useful for quick deployment on remote servers
- [Installing Evennia on Android](./Installing-on-Android.md) - for those craving a mobile life
- [Installation & Setup quick-start](./Installation.md) - one page to quickly get you going
- [Extended Install instructions](./Installation-Git.md) - if you have trouble or want to contribute to Evennia itself
- [Running through Docker](./Installation-Docker.md) - alternative install method, useful for quick deployment on remote servers
- [Installing Evennia on Android](./Installation-Android.md) - for those craving a mobile life
- [Controlling the server](./Start-Stop-Reload.md) - an extended view on how to start/stop/update the server
## Installing custom game dirs
@ -16,7 +16,7 @@ This documentation covers how to setup and maintain the server, from first insta
## Configuring
- [The settings file](./Settings-File.md) - how and where to change the main settings of the server
- [The settings file](./Settings-Default.md) - how and where to change the main settings of the server
- [Change database engine](./Choosing-An-SQL-Server.md) - if you want to use something other than SQLite3
- [Evennia game index](./Evennia-Game-Index.md) - register your upcoming game with the index to start the hype going

99
docs/source/Setup/Setup-Quickstart.md
View file

@ -1,99 +0,0 @@
# Setup quickstart
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.
## Installation
Evennia supports Python 3.7 to 3.9. As with most Python packages, using a
[virtualenv](../Glossary.md#virtualenv) is recommended in order to keep your
installation independent from the system libraries. It's _not_ recommended
to install Evennia as superuser.
```{warning}
This is not yet available. Switch to the 0.9.5 version of these docs to install Evennia.
```
pip install evennia
Make sure the `evennia` command works. Use `evennia -h` for usage help (or read on).
If you are having trouble, want to install in some other way (like with Docker)
or want to contribute to Evennia itself, check out the [Extended Installation
instructions](./Extended-Installation.md). It also has a [troubleshooting
section](./Extended-Installation.md#troubleshooting) for different operating
systems.
## Initialize a new game
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:
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.
## Start the new game
`cd` into your game folder (`mygame` in our case). Next, run
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.
evennia start
Set your user-name and password when prompted. This will be the "god user" or "superuser" in-game. The email is optional.
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 `localhost` doesn't work on your computer, use `127.0.0.1`, which is the same thing.
## See server logs
This will echol the server logs to the terminal as they come in:
evennia --log
or
evennia -l
You can also start logging immediately when running `evennia` commands, such as
evennia start -l
To exit the log view, enter `Ctrl-C` (`Cmd-C` for Mac). This will not affect the server.
## Restarting and stopping
You can restart the server without disconnecting any connected players:
evennia restart
To do a full stop and restart (will disconnect everyone):
evennia reboot
Full stop of the server (will need to use `start` to activate it again):
evennia stop
## The Next step
Why not head into the [Starting Tutorial](../Howto/Starting/Part1/Starting-Part1.md) to learn how to start making your new game!

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

@ -3,7 +3,7 @@
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](./Setup-Quickstart.md) page.
Evennia as described in the [Setup Quickstart](./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.

4
docs/source/conf.py
View file

@ -345,11 +345,13 @@ def setup(app):
# build toctree file
sys.path.insert(1, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
from docs.pylib import auto_link_remapper, update_default_cmd_index, contrib_readmes2docs
from docs.pylib import (auto_link_remapper, update_default_cmd_index,
contrib_readmes2docs, update_dynamic_pages)
_no_autodoc = os.environ.get("NOAUTODOC")
update_default_cmd_index.run_update(no_autodoc=_no_autodoc)
contrib_readmes2docs.readmes2docs()
update_dynamic_pages.update_dynamic_pages()
auto_link_remapper.auto_link_remapper(no_autodoc=_no_autodoc)
# custom lunr-based search

2
docs/source/index.md
View file

@ -17,7 +17,7 @@ This is the manual of [Evennia](https://www.evennia.com), the open source Python
`MU*` creation system.
- [Evennia Introduction](./Evennia-Introduction.md)
- [Install & Setup Quickstart](Setup/Setup-Quickstart.md)
- [Install & Setup Quickstart](Setup/Installation.md)
- [Starting tutorial](Howto/Starting/Part1/Starting-Part1.md)
- [How to contribute and get help](./Contributing.md)

16
docs/source/toc.md
View file

@ -155,7 +155,7 @@ Howto/Starting/Part1/Python-basic-introduction
Howto/Starting/Part1/Python-classes-and-objects
Howto/Starting/Part1/Searching-Things
Howto/Starting/Part1/Starting-Part1
Howto/Starting/Part1/Tutorial-World-Introduction
Howto/Starting/Part1/Tutorial-World
Howto/Starting/Part2/Game-Planning
Howto/Starting/Part2/Planning-Some-Useful-Contribs
Howto/Starting/Part2/Planning-The-Tutorial-Game
@ -182,23 +182,27 @@ Howto/Web-Character-View-Tutorial
Licensing
Links
Setup/Apache-Config
Setup/Changelog
Setup/Choosing-An-SQL-Server
Setup/Client-Support-Grid
Setup/Evennia-Game-Index
Setup/Extended-Installation
Setup/Grapevine
Setup/HAProxy-Config
Setup/How-to-connect-Evennia-to-Twitter
Setup/IRC
Setup/Installing-on-Android
Setup/Installation
Setup/Installation-Android
Setup/Installation-Docker
Setup/Installation-Git
Setup/Installation-Non-Interactive
Setup/Installation-Troubleshooting
Setup/Installation-Upgrade
Setup/Online-Setup
Setup/RSS
Setup/Running-Evennia-in-Docker
Setup/Security
Setup/Server-Conf
Setup/Settings-File
Setup/Settings-Default
Setup/Setup-Overview
Setup/Setup-Quickstart
Setup/Start-Stop-Reload
Unimplemented
api/evennia