From ca7bee9d9968bc30716f4b3acb246505d0e2547d Mon Sep 17 00:00:00 2001 From: Griatch Date: Sat, 5 Feb 2022 14:03:01 +0100 Subject: [PATCH] Considerable cleanup of installation docs --- .../workflows/github_action_test_suite.yml | 16 +- CHANGELOG.md | 48 +- docs/pylib/update_dynamic_pages.py | 81 ++ docs/source/Coding/Quirks.md | 2 +- docs/source/Coding/Updating-Your-Game.md | 2 +- docs/source/Concepts/Internationalization.md | 2 +- .../Contribs/Arxcode-installing-help.md | 4 +- docs/source/Contributing-Docs.md | 2 +- docs/source/Evennia-Introduction.md | 4 +- docs/source/Glossary.md | 14 +- docs/source/Howto/Evennia-for-MUSH-Users.md | 4 +- .../Howto/Evennia-for-roleplaying-sessions.md | 2 +- docs/source/Howto/Howto-Overview.md | 2 +- .../Part1/Evennia-Library-Overview.md | 2 +- .../Howto/Starting/Part1/Gamedir-Overview.md | 2 +- .../Howto/Starting/Part1/More-on-Commands.md | 2 +- .../Howto/Starting/Part1/Starting-Part1.md | 4 +- ...orld-Introduction.md => Tutorial-World.md} | 0 .../Tutorial-for-basic-MUSH-like-game.md | 2 +- docs/source/Setup/Changelog.md | 701 ++++++++++ docs/source/Setup/Extended-Installation.md | 557 -------- ...-on-Android.md => Installation-Android.md} | 11 +- ...ia-in-Docker.md => Installation-Docker.md} | 2 +- docs/source/Setup/Installation-Git.md | 302 +++++ .../Setup/Installation-Non-Interactive.md | 19 + .../Setup/Installation-Troubleshooting.md | 115 ++ docs/source/Setup/Installation-Upgrade.md | 44 + docs/source/Setup/Installation.md | 110 ++ docs/source/Setup/Online-Setup.md | 4 +- docs/source/Setup/Server-Conf.md | 2 +- docs/source/Setup/Settings-Default.md | 1201 +++++++++++++++++ docs/source/Setup/Settings-File.md | 3 - docs/source/Setup/Setup-Overview.md | 10 +- docs/source/Setup/Setup-Quickstart.md | 99 -- docs/source/Setup/Start-Stop-Reload.md | 2 +- docs/source/conf.py | 4 +- docs/source/index.md | 2 +- docs/source/toc.md | 16 +- 38 files changed, 2660 insertions(+), 739 deletions(-) create mode 100644 docs/pylib/update_dynamic_pages.py rename docs/source/Howto/Starting/Part1/{Tutorial-World-Introduction.md => Tutorial-World.md} (100%) create mode 100644 docs/source/Setup/Changelog.md delete mode 100644 docs/source/Setup/Extended-Installation.md rename docs/source/Setup/{Installing-on-Android.md => Installation-Android.md} (92%) rename docs/source/Setup/{Running-Evennia-in-Docker.md => Installation-Docker.md} (99%) create mode 100644 docs/source/Setup/Installation-Git.md create mode 100644 docs/source/Setup/Installation-Non-Interactive.md create mode 100644 docs/source/Setup/Installation-Troubleshooting.md create mode 100644 docs/source/Setup/Installation-Upgrade.md create mode 100644 docs/source/Setup/Installation.md create mode 100644 docs/source/Setup/Settings-Default.md delete mode 100644 docs/source/Setup/Settings-File.md delete mode 100644 docs/source/Setup/Setup-Quickstart.md diff --git a/.github/workflows/github_action_test_suite.yml b/.github/workflows/github_action_test_suite.yml index 26d6b5f559..83fb7616b9 100644 --- a/.github/workflows/github_action_test_suite.yml +++ b/.github/workflows/github_action_test_suite.yml @@ -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: diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b8082c52e..d3b02f135e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/docs/pylib/update_dynamic_pages.py b/docs/pylib/update_dynamic_pages.py new file mode 100644 index 0000000000..69048a9c9f --- /dev/null +++ b/docs/pylib/update_dynamic_pages.py @@ -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() diff --git a/docs/source/Coding/Quirks.md b/docs/source/Coding/Quirks.md index 0e2274a588..f0275289e9 100644 --- a/docs/source/Coding/Quirks.md +++ b/docs/source/Coding/Quirks.md @@ -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 diff --git a/docs/source/Coding/Updating-Your-Game.md b/docs/source/Coding/Updating-Your-Game.md index 617d482ac0..6805a1ab77 100644 --- a/docs/source/Coding/Updating-Your-Game.md +++ b/docs/source/Coding/Updating-Your-Game.md @@ -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 diff --git a/docs/source/Concepts/Internationalization.md b/docs/source/Concepts/Internationalization.md index 994729158e..1db1753dd2 100644 --- a/docs/source/Concepts/Internationalization.md +++ b/docs/source/Concepts/Internationalization.md @@ -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 diff --git a/docs/source/Contribs/Arxcode-installing-help.md b/docs/source/Contribs/Arxcode-installing-help.md index a49f01bf67..fb90bb6aa6 100644 --- a/docs/source/Contribs/Arxcode-installing-help.md +++ b/docs/source/Contribs/Arxcode-installing-help.md @@ -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). diff --git a/docs/source/Contributing-Docs.md b/docs/source/Contributing-Docs.md index 3b29e37d19..fea633d96c 100644 --- a/docs/source/Contributing-Docs.md +++ b/docs/source/Contributing-Docs.md @@ -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 diff --git a/docs/source/Evennia-Introduction.md b/docs/source/Evennia-Introduction.md index 7ecceb7f5d..76d02a5acf 100644 --- a/docs/source/Evennia-Introduction.md +++ b/docs/source/Evennia-Introduction.md @@ -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. diff --git a/docs/source/Glossary.md b/docs/source/Glossary.md index cfdfaf4ff6..b53008d649 100644 --- a/docs/source/Glossary.md +++ b/docs/source/Glossary.md @@ -340,12 +340,12 @@ something like "the command 'evennia' is not available" - it's probably because not 'active' yet (see below). Usage: -- `virtualenv ` - initialize a new virtualenv `` in a new folder `` in the current -location. Called `evenv` in these docs. -- `virtualenv -p path/to/alternate/python_executable ` - create a virtualenv using another -Python version than default. -- `source /bin/activate`(linux/mac) - activate the virtualenv in ``. -- `\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. diff --git a/docs/source/Howto/Evennia-for-MUSH-Users.md b/docs/source/Howto/Evennia-for-MUSH-Users.md index e5dd840db1..752047ecb4 100644 --- a/docs/source/Howto/Evennia-for-MUSH-Users.md +++ b/docs/source/Howto/Evennia-for-MUSH-Users.md @@ -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). diff --git a/docs/source/Howto/Evennia-for-roleplaying-sessions.md b/docs/source/Howto/Evennia-for-roleplaying-sessions.md index 59dbc1ccf4..7e68968cf3 100644 --- a/docs/source/Howto/Evennia-for-roleplaying-sessions.md +++ b/docs/source/Howto/Evennia-for-roleplaying-sessions.md @@ -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 `. 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 diff --git a/docs/source/Howto/Howto-Overview.md b/docs/source/Howto/Howto-Overview.md index 3d07ddbe6e..a944ca0b78 100644 --- a/docs/source/Howto/Howto-Overview.md +++ b/docs/source/Howto/Howto-Overview.md @@ -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) diff --git a/docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md b/docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md index 70c66ce882..3a2dd11252 100644 --- a/docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md +++ b/docs/source/Howto/Starting/Part1/Evennia-Library-Overview.md @@ -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? diff --git a/docs/source/Howto/Starting/Part1/Gamedir-Overview.md b/docs/source/Howto/Starting/Part1/Gamedir-Overview.md index 5c55ef9029..834fa3f546 100644 --- a/docs/source/Howto/Starting/Part1/Gamedir-Overview.md +++ b/docs/source/Howto/Starting/Part1/Gamedir-Overview.md @@ -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 diff --git a/docs/source/Howto/Starting/Part1/More-on-Commands.md b/docs/source/Howto/Starting/Part1/More-on-Commands.md index 00911c05ba..6997d5993c 100644 --- a/docs/source/Howto/Starting/Part1/More-on-Commands.md +++ b/docs/source/Howto/Starting/Part1/More-on-Commands.md @@ -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. diff --git a/docs/source/Howto/Starting/Part1/Starting-Part1.md b/docs/source/Howto/Starting/Part1/Starting-Part1.md index dbe6881f37..4d434091c8 100644 --- a/docs/source/Howto/Starting/Part1/Starting-Part1.md +++ b/docs/source/Howto/Starting/Part1/Starting-Part1.md @@ -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. diff --git a/docs/source/Howto/Starting/Part1/Tutorial-World-Introduction.md b/docs/source/Howto/Starting/Part1/Tutorial-World.md similarity index 100% rename from docs/source/Howto/Starting/Part1/Tutorial-World-Introduction.md rename to docs/source/Howto/Starting/Part1/Tutorial-World.md diff --git a/docs/source/Howto/Starting/Part3/Tutorial-for-basic-MUSH-like-game.md b/docs/source/Howto/Starting/Part3/Tutorial-for-basic-MUSH-like-game.md index b9c345f88c..f57c6ac330 100644 --- a/docs/source/Howto/Starting/Part3/Tutorial-for-basic-MUSH-like-game.md +++ b/docs/source/Howto/Starting/Part3/Tutorial-for-basic-MUSH-like-game.md @@ -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). diff --git a/docs/source/Setup/Changelog.md b/docs/source/Setup/Changelog.md new file mode 100644 index 0000000000..d3b02f135e --- /dev/null +++ b/docs/source/Setup/Changelog.md @@ -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()` 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. diff --git a/docs/source/Setup/Extended-Installation.md b/docs/source/Setup/Extended-Installation.md deleted file mode 100644 index 9b7bcbe566..0000000000 --- a/docs/source/Setup/Extended-Installation.md +++ /dev/null @@ -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. diff --git a/docs/source/Setup/Installing-on-Android.md b/docs/source/Setup/Installation-Android.md similarity index 92% rename from docs/source/Setup/Installing-on-Android.md rename to docs/source/Setup/Installation-Android.md index f7ba8b04ea..d2f2892d64 100644 --- a/docs/source/Setup/Installing-on-Android.md +++ b/docs/source/Setup/Installation-Android.md @@ -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 diff --git a/docs/source/Setup/Running-Evennia-in-Docker.md b/docs/source/Setup/Installation-Docker.md similarity index 99% rename from docs/source/Setup/Running-Evennia-in-Docker.md rename to docs/source/Setup/Installation-Docker.md index 31d45cb0e8..b07953838f 100644 --- a/docs/source/Setup/Running-Evennia-in-Docker.md +++ b/docs/source/Setup/Installation-Docker.md @@ -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 diff --git a/docs/source/Setup/Installation-Git.md b/docs/source/Setup/Installation-Git.md new file mode 100644 index 0000000000..139267204b --- /dev/null +++ b/docs/source/Setup/Installation-Git.md @@ -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! \ No newline at end of file diff --git a/docs/source/Setup/Installation-Non-Interactive.md b/docs/source/Setup/Installation-Non-Interactive.md new file mode 100644 index 0000000000..7095260830 --- /dev/null +++ b/docs/source/Setup/Installation-Non-Interactive.md @@ -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 + +``` \ No newline at end of file diff --git a/docs/source/Setup/Installation-Troubleshooting.md b/docs/source/Setup/Installation-Troubleshooting.md new file mode 100644 index 0000000000..76ce5e5c18 --- /dev/null +++ b/docs/source/Setup/Installation-Troubleshooting.md @@ -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. diff --git a/docs/source/Setup/Installation-Upgrade.md b/docs/source/Setup/Installation-Upgrade.md new file mode 100644 index 0000000000..ff583a9039 --- /dev/null +++ b/docs/source/Setup/Installation-Upgrade.md @@ -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. \ No newline at end of file diff --git a/docs/source/Setup/Installation.md b/docs/source/Setup/Installation.md new file mode 100644 index 0000000000..ddd8a27a8e --- /dev/null +++ b/docs/source/Setup/Installation.md @@ -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! \ No newline at end of file diff --git a/docs/source/Setup/Online-Setup.md b/docs/source/Setup/Online-Setup.md index 5307021542..6107365717 100644 --- a/docs/source/Setup/Online-Setup.md +++ b/docs/source/Setup/Online-Setup.md @@ -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. diff --git a/docs/source/Setup/Server-Conf.md b/docs/source/Setup/Server-Conf.md index 88b717eab4..8c3265ca6c 100644 --- a/docs/source/Setup/Server-Conf.md +++ b/docs/source/Setup/Server-Conf.md @@ -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) diff --git a/docs/source/Setup/Settings-Default.md b/docs/source/Setup/Settings-Default.md new file mode 100644 index 0000000000..7617fefb59 --- /dev/null +++ b/docs/source/Setup/Settings-Default.md @@ -0,0 +1,1201 @@ + +# 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 +""" +Master configuration file for Evennia. + +NOTE: NO MODIFICATIONS SHOULD BE MADE TO THIS FILE! + +All settings changes should be done by copy-pasting the variable and +its value to /server/conf/settings.py. + +Hint: Don't copy&paste over more from this file than you actually want +to change. Anything you don't copy&paste will thus retain its default +value - which may change as Evennia is developed. This way you can +always be sure of what you have changed and what is default behaviour. + +""" +from django.contrib.messages import constants as messages +from django.urls import reverse_lazy + +import os +import sys + +###################################################################### +# Evennia base server config +###################################################################### + +# This is the name of your game. Make it catchy! +SERVERNAME = "Evennia" +# Short one-sentence blurb describing your game. Shown under the title +# on the website and could be used in online listings of your game etc. +GAME_SLOGAN = "The Python MUD/MU* creation system" +# The url address to your server, like mymudgame.com. This should be the publicly +# visible location. This is used e.g. on the web site to show how you connect to the +# game over telnet. Default is localhost (only on your machine). +SERVER_HOSTNAME = "localhost" +# Lockdown mode will cut off the game from any external connections +# and only allow connections from localhost. Requires a cold reboot. +LOCKDOWN_MODE = False +# Activate telnet service +TELNET_ENABLED = True +# A list of ports the Evennia telnet server listens on Can be one or many. +TELNET_PORTS = [4000] +# Interface addresses to listen to. If 0.0.0.0, listen to all. Use :: for IPv6. +TELNET_INTERFACES = ["0.0.0.0"] +# Activate Telnet+SSL protocol (SecureSocketLibrary) for supporting clients +SSL_ENABLED = False +# Ports to use for Telnet+SSL +SSL_PORTS = [4003] +# Telnet+SSL Interface addresses to listen to. If 0.0.0.0, listen to all. Use :: for IPv6. +SSL_INTERFACES = ["0.0.0.0"] +# OOB (out-of-band) telnet communication allows Evennia to communicate +# special commands and data with enabled Telnet clients. This is used +# to create custom client interfaces over a telnet connection. To make +# full use of OOB, you need to prepare functions to handle the data +# server-side (see INPUT_FUNC_MODULES). TELNET_ENABLED is required for this +# to work. +TELNET_OOB_ENABLED = False +# Activate SSH protocol communication (SecureShell) +SSH_ENABLED = False +# Ports to use for SSH +SSH_PORTS = [4004] +# Interface addresses to listen to. If 0.0.0.0, listen to all. Use :: for IPv6. +SSH_INTERFACES = ["0.0.0.0"] +# Start the evennia django+twisted webserver so you can +# browse the evennia website and the admin interface +# (Obs - further web configuration can be found below +# in the section 'Config for Django web features') +WEBSERVER_ENABLED = True +# This is a security setting protecting against host poisoning +# attacks. It defaults to allowing all. In production, make +# sure to change this to your actual host addresses/IPs. +ALLOWED_HOSTS = ["*"] +# The webserver sits behind a Portal proxy. This is a list +# of tuples (proxyport,serverport) used. The proxyports are what +# the Portal proxy presents to the world. The serverports are +# the internal ports the proxy uses to forward data to the Server-side +# webserver (these should not be publicly open) +WEBSERVER_PORTS = [(4001, 4005)] +# Interface addresses to listen to. If 0.0.0.0, listen to all. Use :: for IPv6. +WEBSERVER_INTERFACES = ["0.0.0.0"] +# IP addresses that may talk to the server in a reverse proxy configuration, +# like NginX. +UPSTREAM_IPS = ["127.0.0.1"] +# The webserver uses threadpool for handling requests. This will scale +# with server load. Set the minimum and maximum number of threads it +# may use as (min, max) (must be > 0) +WEBSERVER_THREADPOOL_LIMITS = (1, 20) +# Start the evennia webclient. This requires the webserver to be running and +# offers the fallback ajax-based webclient backbone for browsers not supporting +# the websocket one. +WEBCLIENT_ENABLED = True +# Activate Websocket support for modern browsers. If this is on, the +# default webclient will use this and only use the ajax version if the browser +# is too old to support websockets. Requires WEBCLIENT_ENABLED. +WEBSOCKET_CLIENT_ENABLED = True +# Server-side websocket port to open for the webclient. Note that this value will +# be dynamically encoded in the webclient html page to allow the webclient to call +# home. If the external encoded value needs to be different than this, due to +# working through a proxy or docker port-remapping, the environment variable +# WEBCLIENT_CLIENT_PROXY_PORT can be used to override this port only for the +# front-facing client's sake. +WEBSOCKET_CLIENT_PORT = 4002 +# Interface addresses to listen to. If 0.0.0.0, listen to all. Use :: for IPv6. +WEBSOCKET_CLIENT_INTERFACE = "0.0.0.0" +# Actual URL for webclient component to reach the websocket. You only need +# to set this if you know you need it, like using some sort of proxy setup. +# If given it must be on the form "ws[s]://hostname[:port]". If left at None, +# the client will itself figure out this url based on the server's hostname. +# e.g. ws://external.example.com or wss://external.example.com:443 +WEBSOCKET_CLIENT_URL = None +# This determine's whether Evennia's custom admin page is used, or if the +# standard Django admin is used. +EVENNIA_ADMIN = True +# The Server opens an AMP port so that the portal can +# communicate with it. This is an internal functionality of Evennia, usually +# operating between two processes on the same machine. You usually don't need to +# change this unless you cannot use the default AMP port/host for +# whatever reason. +AMP_HOST = "localhost" +AMP_PORT = 4006 +AMP_INTERFACE = "127.0.0.1" + + +# Path to the lib directory containing the bulk of the codebase's code. +EVENNIA_DIR = os.path.dirname(os.path.abspath(__file__)) +# Path to the game directory (containing the server/conf/settings.py file) +# This is dynamically created- there is generally no need to change this! +if EVENNIA_DIR.lower() == os.getcwd().lower() or ( + sys.argv[1] == "test" if len(sys.argv) > 1 else False +): + # unittesting mode + GAME_DIR = os.getcwd() +else: + # Fallback location (will be replaced by the actual game dir at runtime) + GAME_DIR = os.path.join(EVENNIA_DIR, "game_template") + for i in range(10): + gpath = os.getcwd() + if "server" in os.listdir(gpath): + if os.path.isfile(os.path.join("server", "conf", "settings.py")): + GAME_DIR = gpath + break + os.chdir(os.pardir) +# Place to put log files, how often to rotate the log and how big each log file +# may become before rotating. +LOG_DIR = os.path.join(GAME_DIR, "server", "logs") +SERVER_LOG_FILE = os.path.join(LOG_DIR, "server.log") +SERVER_LOG_DAY_ROTATION = 7 +SERVER_LOG_MAX_SIZE = 1000000 +PORTAL_LOG_FILE = os.path.join(LOG_DIR, "portal.log") +PORTAL_LOG_DAY_ROTATION = 7 +PORTAL_LOG_MAX_SIZE = 1000000 +# The http log is usually only for debugging since it's very spammy +HTTP_LOG_FILE = os.path.join(LOG_DIR, "http_requests.log") +# if this is set to the empty string, lockwarnings will be turned off. +LOCKWARNING_LOG_FILE = os.path.join(LOG_DIR, "lockwarnings.log") +# Number of lines to append to rotating channel logs when they rotate +CHANNEL_LOG_NUM_TAIL_LINES = 20 +# Max size (in bytes) of channel log files before they rotate +CHANNEL_LOG_ROTATE_SIZE = 1000000 +# Unused by default, but used by e.g. the MapSystem contrib. A place for storing +# semi-permanent data and avoid it being rebuilt over and over. It is created +# on-demand only. +CACHE_DIR = os.path.join(GAME_DIR, "server", ".cache") +# Local time zone for this installation. All choices can be found here: +# http://www.postgresql.org/docs/8.0/interactive/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE +TIME_ZONE = "UTC" +# Activate time zone in datetimes +USE_TZ = True +# Authentication backends. This is the code used to authenticate a user. +AUTHENTICATION_BACKENDS = ["evennia.web.utils.backends.CaseInsensitiveModelBackend"] +# Language code for this installation. All choices can be found here: +# http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes +LANGUAGE_CODE = "en-us" +# How long time (in seconds) a user may idle before being logged +# out. This can be set as big as desired. A user may avoid being +# thrown off by sending the empty system command 'idle' to the server +# at regular intervals. Set <=0 to deactivate idle timeout completely. +IDLE_TIMEOUT = -1 +# The idle command can be sent to keep your session active without actually +# having to spam normal commands regularly. It gives no feedback, only updates +# the idle timer. Note that "idle" will *always* work, even if a different +# command-name is given here; this is because the webclient needs a default +# to send to avoid proxy timeouts. +IDLE_COMMAND = "idle" +# The set of encodings tried. An Account object may set an attribute "encoding" on +# itself to match the client used. If not set, or wrong encoding is +# given, this list is tried, in order, aborting on the first match. +# Add sets for languages/regions your accounts are likely to use. +# (see http://en.wikipedia.org/wiki/Character_encoding) +# Telnet default encoding, unless specified by the client, will be ENCODINGS[0]. +ENCODINGS = ["utf-8", "latin-1", "ISO-8859-1"] +# Regular expression applied to all output to a given session in order +# to strip away characters (usually various forms of decorations) for the benefit +# of users with screen readers. Note that ANSI/MXP doesn't need to +# be stripped this way, that is handled automatically. +SCREENREADER_REGEX_STRIP = r"\+-+|\+$|\+~|--+|~~+|==+" +# MXP support means the ability to show clickable links in the client. Clicking +# the link will execute a game command. It's a way to add mouse input to the game. +MXP_ENABLED = True +# If this is set, MXP can only be sent by the server and not added from the +# client side. Disabling this is a potential security risk because it could +# allow malevolent players to lure others to execute commands they did not +# intend to. +MXP_OUTGOING_ONLY = True +# Database objects are cached in what is known as the idmapper. The idmapper +# caching results in a massive speedup of the server (since it dramatically +# limits the number of database accesses needed) and also allows for +# storing temporary data on objects. It is however also the main memory +# consumer of Evennia. With this setting the cache can be capped and +# flushed when it reaches a certain size. Minimum is 50 MB but it is +# not recommended to set this to less than 100 MB for a distribution +# system. +# Empirically, N_objects_in_cache ~ ((RMEM - 35) / 0.0157): +# mem(MB) | objs in cache || mem(MB) | objs in cache +# 50 | ~1000 || 800 | ~49 000 +# 100 | ~4000 || 1200 | ~75 000 +# 200 | ~10 000 || 1600 | ~100 000 +# 500 | ~30 000 || 2000 | ~125 000 +# Note that the estimated memory usage is not exact (and the cap is only +# checked every 5 minutes), so err on the side of caution if +# running on a server with limited memory. Also note that Python +# will not necessarily return the memory to the OS when the idmapper +# flashes (the memory will be freed and made available to the Python +# process only). How many objects need to be in memory at any given +# time depends very much on your game so some experimentation may +# be necessary (use @server to see how many objects are in the idmapper +# cache at any time). Setting this to None disables the cache cap. +IDMAPPER_CACHE_MAXSIZE = 200 # (MB) +# This determines how many connections per second the Portal should +# accept, as a DoS countermeasure. If the rate exceeds this number, incoming +# connections will be queued to this rate, so none will be lost. +# Must be set to a value > 0. +MAX_CONNECTION_RATE = 2 +# Determine how many commands per second a given Session is allowed +# to send to the Portal via a connected protocol. Too high rate will +# drop the command and echo a warning. Note that this will also cap +# OOB messages so don't set it too low if you expect a lot of events +# from the client! To turn the limiter off, set to <= 0. +MAX_COMMAND_RATE = 80 +# The warning to echo back to users if they send commands too fast +COMMAND_RATE_WARNING = "You entered commands too fast. Wait a moment and try again." +# custom, extra commands to add to the `evennia` launcher. This is a dict +# of {'cmdname': 'path.to.callable', ...}, where the callable will be passed +# any extra args given on the command line. For example `evennia cmdname foo bar`. +EXTRA_LAUNCHER_COMMANDS = {} + +# Determine how large of a string can be sent to the server in number +# of characters. If they attempt to enter a string over this character +# limit, we stop them and send a message. To make unlimited, set to +# 0 or less. +MAX_CHAR_LIMIT = 6000 +# The warning to echo back to users if they enter a very large string +MAX_CHAR_LIMIT_WARNING = ( + "You entered a string that was too long. " "Please break it up into multiple parts." +) +# If this is true, errors and tracebacks from the engine will be +# echoed as text in-game as well as to the log. This can speed up +# debugging. OBS: Showing full tracebacks to regular users could be a +# security problem -turn this off in a production game! +IN_GAME_ERRORS = True +# Broadcast "Server restart"-like messages to all sessions. +BROADCAST_SERVER_RESTART_MESSAGES = True + +###################################################################### +# Evennia Database config +###################################################################### + +# Database config syntax: +# ENGINE - path to the the database backend. Possible choices are: +# 'django.db.backends.sqlite3', (default) +# 'django.db.backends.mysql', +# 'django.db.backends.postgresql', +# 'django.db.backends.oracle' (untested). +# NAME - database name, or path to the db file for sqlite3 +# USER - db admin (unused in sqlite3) +# PASSWORD - db admin password (unused in sqlite3) +# HOST - empty string is localhost (unused in sqlite3) +# PORT - empty string defaults to localhost (unused in sqlite3) +DATABASES = { + "default": { + "ENGINE": "django.db.backends.sqlite3", + "NAME": os.getenv("TEST_DB_PATH", os.path.join(GAME_DIR, "server", "evennia.db3")), + "USER": "", + "PASSWORD": "", + "HOST": "", + "PORT": "", + } +} +# How long the django-database connection should be kept open, in seconds. +# If you get errors about the database having gone away after long idle +# periods, shorten this value (e.g. MySQL defaults to a timeout of 8 hrs) +CONN_MAX_AGE = 3600 * 7 +# When removing or renaming models, such models stored in Attributes may +# become orphaned and will return as None. If the change is a rename (that +# is, there is a 1:1 pk mapping between the old and the new), the unserializer +# can convert old to new when retrieving them. This is a list of tuples +# (old_natural_key, new_natural_key). Note that Django ContentTypes' +# natural_keys are themselves tuples (appname, modelname). Creation-dates will +# not be checked for models specified here. If new_natural_key does not exist, +# `None` will be returned and stored back as if no replacement was set. +ATTRIBUTE_STORED_MODEL_RENAME = [ + (("players", "playerdb"), ("accounts", "accountdb")), + (("typeclasses", "defaultplayer"), ("typeclasses", "defaultaccount")), +] +# Default type of autofield (required by Django) +DEFAULT_AUTO_FIELD = 'django.db.models.AutoField' + +###################################################################### +# Evennia webclient options +###################################################################### + +# default webclient options (without user changing it) +WEBCLIENT_OPTIONS = { + # Gags prompts in output window and puts them on the input bar + "gagprompt": True, + # Shows help files in a new popup window instead of in-pane + "helppopup": False, + # Shows notifications of new messages as popup windows + "notification_popup": False, + # Plays a sound for notifications of new messages + "notification_sound": False +} + +###################################################################### +# Evennia pluggable modules +###################################################################### +# Plugin modules extend Evennia in various ways. In the cases with no +# existing default, there are examples of many of these modules +# in contrib/examples. + +# The command parser module to use. See the default module for which +# functions it must implement +COMMAND_PARSER = "evennia.commands.cmdparser.cmdparser" +# On a multi-match when search objects or commands, the user has the +# ability to search again with an index marker that differentiates +# the results. If multiple "box" objects +# are found, they can by default be separated as 1-box, 2-box. Below you +# can change the regular expression used. The regex must have one +# have two capturing groups (?P...) and (?P...) - the default +# parser expects this. It should also involve a number starting from 1. +# When changing this you must also update SEARCH_MULTIMATCH_TEMPLATE +# to properly describe the syntax. +SEARCH_MULTIMATCH_REGEX = r"(?P[^-]*)-(?P[0-9]+)(?P.*)" +# To display multimatch errors in various listings we must display +# the syntax in a way that matches what SEARCH_MULTIMATCH_REGEX understand. +# The template will be populated with data and expects the following markup: +# {number} - the order of the multimatch, starting from 1; {name} - the +# name (key) of the multimatched entity; {aliases} - eventual +# aliases for the entity; {info} - extra info like #dbrefs for staff. Don't +# forget a line break if you want one match per line. +SEARCH_MULTIMATCH_TEMPLATE = " {name}-{number}{aliases}{info}\n" +# The handler that outputs errors when using any API-level search +# (not manager methods). This function should correctly report errors +# both for command- and object-searches. This allows full control +# over the error output (it uses SEARCH_MULTIMATCH_TEMPLATE by default). +SEARCH_AT_RESULT = "evennia.utils.utils.at_search_result" +# Single characters to ignore at the beginning of a command. When set, e.g. +# cmd, @cmd and +cmd will all find a command "cmd" or one named "@cmd" etc. If +# you have defined two different commands cmd and @cmd you can still enter +# @cmd to exactly target the second one. Single-character commands consisting +# of only a prefix character will not be stripped. Set to the empty +# string ("") to turn off prefix ignore. +CMD_IGNORE_PREFIXES = "@&/+" +# The module holding text strings for the connection screen. +# This module should contain one or more variables +# with strings defining the look of the screen. +CONNECTION_SCREEN_MODULE = "server.conf.connection_screens" +# Delay to use before sending the evennia.syscmdkeys.CMD_LOGINSTART Command +# when a new session connects (this defaults the unloggedin-look for showing +# the connection screen). The delay is useful mainly for telnet, to allow +# client/server to establish client capabilities like color/mxp etc before +# sending any text. A value of 0.3 should be enough. While a good idea, it may +# cause issues with menu-logins and autoconnects since the menu will not have +# started when the autoconnects starts sending menu commands. +DELAY_CMD_LOGINSTART = 0.3 +# A module that must exist - this holds the instructions Evennia will use to +# first prepare the database for use (create user #1 and Limbo etc). Only override if +# you really know what # you are doing. If replacing, it must contain a function +# handle_setup(stepname=None). The function will start being called with no argument +# and is expected to maintain a named sequence of steps. Once each step is completed, it +# should be saved with ServerConfig.objects.conf('last_initial_setup_step', stepname) +# on a crash, the system will continue by calling handle_setup with the last completed +# step. The last step in the sequence must be named 'done'. Once this key is saved, +# initialization will not run again. +INITIAL_SETUP_MODULE = "evennia.server.initial_setup" +# An optional module that, if existing, must hold a function +# named at_initial_setup(). This hook method can be used to customize +# the server's initial setup sequence (the very first startup of the system). +# The check will fail quietly if module doesn't exist or fails to load. +AT_INITIAL_SETUP_HOOK_MODULE = "server.conf.at_initial_setup" +# Module containing your custom at_server_start(), at_server_reload() and +# at_server_stop() methods. These methods will be called every time +# the server starts, reloads and resets/stops respectively. +AT_SERVER_STARTSTOP_MODULE = "server.conf.at_server_startstop" +# List of one or more module paths to modules containing a function start_ +# plugin_services(application). This module will be called with the main +# Evennia Server application when the Server is initiated. +# It will be called last in the startup sequence. +SERVER_SERVICES_PLUGIN_MODULES = ["server.conf.server_services_plugins"] +# List of one or more module paths to modules containing a function +# start_plugin_services(application). This module will be called with the +# main Evennia Portal application when the Portal is initiated. +# It will be called last in the startup sequence. +PORTAL_SERVICES_PLUGIN_MODULES = ["server.conf.portal_services_plugins"] +# Module holding MSSP meta data. This is used by MUD-crawlers to determine +# what type of game you are running, how many accounts you have etc. +MSSP_META_MODULE = "server.conf.mssp" +# Module for web plugins. +WEB_PLUGINS_MODULE = "server.conf.web_plugins" +# Tuple of modules implementing lock functions. All callable functions +# inside these modules will be available as lock functions. +LOCK_FUNC_MODULES = ("evennia.locks.lockfuncs", "server.conf.lockfuncs") +# Module holding handlers for managing incoming data from the client. These +# will be loaded in order, meaning functions in later modules may overload +# previous ones if having the same name. +INPUT_FUNC_MODULES = ["evennia.server.inputfuncs", "server.conf.inputfuncs"] +# Modules that contain prototypes for use with the spawner mechanism. +PROTOTYPE_MODULES = ["world.prototypes"] +# Modules containining Prototype functions able to be embedded in prototype +# definitions from in-game. +PROT_FUNC_MODULES = ["evennia.prototypes.protfuncs"] +# Module holding settings/actions for the dummyrunner program (see the +# dummyrunner for more information) +DUMMYRUNNER_SETTINGS_MODULE = "evennia.server.profiling.dummyrunner_settings" +# Mapping to extend Evennia's normal ANSI color tags. The mapping is a list of +# tuples mapping the exact tag (not a regex!) to the ANSI convertion, like +# `(r"%c%r", ansi.ANSI_RED)` (the evennia.utils.ansi module contains all +# ANSI escape sequences). Default is to use `|` and `|[` -prefixes. +COLOR_ANSI_EXTRA_MAP = [] +# Extend the available regexes for adding XTERM256 colors in-game. This is given +# as a list of regexes, where each regex must contain three anonymous groups for +# holding integers 0-5 for the red, green and blue components Default is +# is r'\|([0-5])([0-5])([0-5])', which allows e.g. |500 for red. +# XTERM256 foreground color replacement +COLOR_XTERM256_EXTRA_FG = [] +# XTERM256 background color replacement. Default is \|\[([0-5])([0-5])([0-5])' +COLOR_XTERM256_EXTRA_BG = [] +# Extend the available regexes for adding XTERM256 grayscale values in-game. Given +# as a list of regexes, where each regex must contain one anonymous group containing +# a single letter a-z to mark the level from white to black. Default is r'\|=([a-z])', +# which allows e.g. |=k for a medium gray. +# XTERM256 grayscale foreground +COLOR_XTERM256_EXTRA_GFG = [] +# XTERM256 grayscale background. Default is \|\[=([a-z])' +COLOR_XTERM256_EXTRA_GBG = [] +# ANSI does not support bright backgrounds, so Evennia fakes this by mapping it to +# XTERM256 backgrounds where supported. This is a list of tuples that maps the wanted +# ansi tag (not a regex!) to a valid XTERM256 background tag, such as `(r'{[r', r'{[500')`. +COLOR_ANSI_XTERM256_BRIGHT_BG_EXTRA_MAP = [] +# If set True, the above color settings *replace* the default |-style color markdown +# rather than extend it. +COLOR_NO_DEFAULT = False + + +###################################################################### +# Default command sets and commands +###################################################################### + +# Command set used on session before account has logged in +CMDSET_UNLOGGEDIN = "commands.default_cmdsets.UnloggedinCmdSet" +# (Note that changing these three following cmdset paths will only affect NEW +# created characters/objects, not those already in play. So if you want to +# change this and have it apply to every object, it's recommended you do it +# before having created a lot of objects (or simply reset the database after +# the change for simplicity)). +# Command set used on the logged-in session +CMDSET_SESSION = "commands.default_cmdsets.SessionCmdSet" +# Default set for logged in account with characters (fallback) +CMDSET_CHARACTER = "commands.default_cmdsets.CharacterCmdSet" +# Command set for accounts without a character (ooc) +CMDSET_ACCOUNT = "commands.default_cmdsets.AccountCmdSet" + +# Location to search for cmdsets if full path not given +CMDSET_PATHS = ["commands", "evennia", "evennia.contrib"] +# Fallbacks for cmdset paths that fail to load. Note that if you change the path for your +# default cmdsets, you will also need to copy CMDSET_FALLBACKS after your change in your +# settings file for it to detect the change. +CMDSET_FALLBACKS = { + CMDSET_CHARACTER: "evennia.commands.default.cmdset_character.CharacterCmdSet", + CMDSET_ACCOUNT: "evennia.commands.default.cmdset_account.AccountCmdSet", + CMDSET_SESSION: "evennia.commands.default.cmdset_session.SessionCmdSet", + CMDSET_UNLOGGEDIN: "evennia.commands.default.cmdset_unloggedin.UnloggedinCmdSet", +} +# Parent class for all default commands. Changing this class will +# modify all default commands, so do so carefully. +COMMAND_DEFAULT_CLASS = "evennia.commands.default.muxcommand.MuxCommand" +# Command.arg_regex is a regular expression desribing how the arguments +# to the command must be structured for the command to match a given user +# input. By default the command-name should end with a space or / (since the +# default commands uses MuxCommand and /switches). +COMMAND_DEFAULT_ARG_REGEX = r'^[ /]+.*$|$' +# By default, Command.msg will only send data to the Session calling +# the Command in the first place. If set, Command.msg will instead return +# data to all Sessions connected to the Account/Character associated with +# calling the Command. This may be more intuitive for users in certain +# multisession modes. +COMMAND_DEFAULT_MSG_ALL_SESSIONS = False +# The default lockstring of a command. +COMMAND_DEFAULT_LOCKS = "" + +###################################################################### +# Typeclasses and other paths +###################################################################### + +# These are paths that will be prefixed to the paths given if the +# immediately entered path fail to find a typeclass. It allows for +# shorter input strings. They must either base off the game directory +# or start from the evennia library. +TYPECLASS_PATHS = [ + "typeclasses", + "evennia", + "evennia.contrib", + "evennia.contrib.game_systems", + "evennia.contrib.base_systems", + "evennia.contrib.full_systems", + "evennia.contrib.tutorials", + "evennia.contrib.utils", +] + +# Typeclass for account objects (linked to a character) (fallback) +BASE_ACCOUNT_TYPECLASS = "typeclasses.accounts.Account" +# Typeclass and base for all objects (fallback) +BASE_OBJECT_TYPECLASS = "typeclasses.objects.Object" +# Typeclass for character objects linked to an account (fallback) +BASE_CHARACTER_TYPECLASS = "typeclasses.characters.Character" +# Typeclass for rooms (fallback) +BASE_ROOM_TYPECLASS = "typeclasses.rooms.Room" +# Typeclass for Exit objects (fallback). +BASE_EXIT_TYPECLASS = "typeclasses.exits.Exit" +# Typeclass for Channel (fallback). +BASE_CHANNEL_TYPECLASS = "typeclasses.channels.Channel" +# Typeclass for Scripts (fallback). You usually don't need to change this +# but create custom variations of scripts on a per-case basis instead. +BASE_SCRIPT_TYPECLASS = "typeclasses.scripts.Script" +# The default home location used for all objects. This is used as a +# fallback if an object's normal home location is deleted. Default +# is Limbo (#2). +DEFAULT_HOME = "#2" +# The start position for new characters. Default is Limbo (#2). +# MULTISESSION_MODE = 0, 1 - used by default unloggedin create command +# MULTISESSION_MODE = 2, 3 - used by default character_create command +START_LOCATION = "#2" +# Lookups of Attributes, Tags, Nicks, Aliases can be aggressively +# cached to avoid repeated database hits. This often gives noticeable +# performance gains since they are called so often. Drawback is that +# if you are accessing the database from multiple processes (such as +# from a website -not- running Evennia's own webserver) data may go +# out of sync between the processes. Keep on unless you face such +# issues. +TYPECLASS_AGGRESSIVE_CACHE = True +# These are fallbacks for BASE typeclasses failing to load. Usually needed only +# during doc building. The system expects these to *always* load correctly, so +# only modify if you are making fundamental changes to how objects/accounts +# work and know what you are doing +FALLBACK_ACCOUNT_TYPECLASS = "evennia.accounts.accounts.DefaultAccount" +FALLBACK_OBJECT_TYPECLASS = "evennia.objects.objects.DefaultObject" +FALLBACK_CHARACTER_TYPECLASS = "evennia.objects.objects.DefaultCharacter" +FALLBACK_ROOM_TYPECLASS = "evennia.objects.objects.DefaultRoom" +FALLBACK_EXIT_TYPECLASS = "evennia.objects.objects.DefaultExit" +FALLBACK_CHANNEL_TYPECLASS = "evennia.comms.comms.DefaultChannel" +FALLBACK_SCRIPT_TYPECLASS = "evennia.scripts.scripts.DefaultScript" + + +###################################################################### +# Options and validators +###################################################################### + +# Options available on Accounts. Each such option is described by a +# class available from evennia.OPTION_CLASSES, in turn making use +# of validators from evennia.VALIDATOR_FUNCS to validate input when +# the user changes an option. The options are accessed through the +# `Account.options` handler. + +# ("Description", 'Option Class name in evennia.OPTION_CLASS_MODULES', 'Default Value') + +OPTIONS_ACCOUNT_DEFAULT = { + "border_color": ("Headers, footers, table borders, etc.", "Color", "n"), + "header_star_color": ("* inside Header lines.", "Color", "n"), + "header_text_color": ("Text inside Header lines.", "Color", "w"), + "header_fill": ("Fill for Header lines.", "Text", "="), + "separator_star_color": ("* inside Separator lines.", "Color", "n"), + "separator_text_color": ("Text inside Separator lines.", "Color", "w"), + "separator_fill": ("Fill for Separator Lines.", "Text", "-"), + "footer_star_color": ("* inside Footer lines.", "Color", "n"), + "footer_text_color": ("Text inside Footer Lines.", "Color", "n"), + "footer_fill": ("Fill for Footer Lines.", "Text", "="), + "column_names_color": ("Table column header text.", "Color", "w"), + "help_category_color": ("Help category names.", "Color", "n"), + "help_entry_color": ("Help entry names.", "Color", "n"), + "timezone": ("Timezone for dates. @tz for a list.", "Timezone", "UTC"), +} +# Modules holding Option classes, responsible for serializing the option and +# calling validator functions on it. Same-named functions in modules added +# later in this list will override those added earlier. +OPTION_CLASS_MODULES = ["evennia.utils.optionclasses"] +# Module holding validator functions. These are used as a resource for +# validating options, but can also be used as input validators in general. +# Same-named functions in modules added later in this list will override those +# added earlier. +VALIDATOR_FUNC_MODULES = ["evennia.utils.validatorfuncs"] + +###################################################################### +# Batch processors +###################################################################### + +# Python path to a directory to be searched for batch scripts +# for the batch processors (.ev and/or .py files). +BASE_BATCHPROCESS_PATHS = [ + "world", + "evennia.contrib", + "evennia.contrib.tutorials", +] + +###################################################################### +# Game Time setup +###################################################################### + +# You don't actually have to use this, but it affects the routines in +# evennia.utils.gametime.py and allows for a convenient measure to +# determine the current in-game time. You can of course interpret +# "week", "month" etc as your own in-game time units as desired. + +# The time factor dictates if the game world runs faster (timefactor>1) +# or slower (timefactor<1) than the real world. +TIME_FACTOR = 2.0 +# The starting point of your game time (the epoch), in seconds. +# In Python a value of 0 means Jan 1 1970 (use negatives for earlier +# start date). This will affect the returns from the utils.gametime +# module. If None, the server's first start-time is used as the epoch. +TIME_GAME_EPOCH = None +# Normally, game time will only increase when the server runs. If this is True, +# game time will not pause when the server reloads or goes offline. This setting +# together with a time factor of 1 should keep the game in sync with +# the real time (add a different epoch to shift time) +TIME_IGNORE_DOWNTIMES = False + +###################################################################### +# Help system +###################################################################### +# Help output from CmdHelp are wrapped in an EvMore call +# (excluding webclient with separate help popups). If continuous scroll +# is preferred, change 'HELP_MORE' to False. EvMORE uses CLIENT_DEFAULT_HEIGHT +HELP_MORE_ENABLED = True +# The help category of a command if not specified. +COMMAND_DEFAULT_HELP_CATEGORY = "general" +# The help category of a db or file-based help entry if not specified +DEFAULT_HELP_CATEGORY = "general" +# File-based help entries. These are modules containing dicts defining help +# entries. They can be used together with in-database entries created in-game. +FILE_HELP_ENTRY_MODULES = ["world.help_entries"] +# if topics listed in help should be clickable +# clickable links only work on clients that support MXP. +HELP_CLICKABLE_TOPICS = True + +###################################################################### +# FuncParser +# +# Strings parsed with the FuncParser can contain 'callables' on the +# form $funcname(args,kwargs), which will lead to actual Python functions +# being executed. +###################################################################### +# This changes the start-symbol for the funcparser callable. Note that +# this will make a lot of documentation invalid and there may also be +# other unexpected side effects, so change with caution. +FUNCPARSER_START_CHAR = '$' +# The symbol to use to escape Func +FUNCPARSER_ESCAPE_CHAR = '\\' +# This is the global max nesting-level for nesting functions in +# the funcparser. This protects against infinite loops. +FUNCPARSER_MAX_NESTING = 20 +# Activate funcparser for all outgoing strings. The current Session +# will be passed into the parser (used to be called inlinefuncs) +FUNCPARSER_PARSE_OUTGOING_MESSAGES_ENABLED = False +# Only functions defined globally (and not starting with '_') in +# these modules will be considered valid inlinefuncs. The list +# is loaded from left-to-right, same-named functions will overload +FUNCPARSER_OUTGOING_MESSAGES_MODULES = ["evennia.utils.funcparser", "server.conf.inlinefuncs"] +# Prototype values are also parsed with FuncParser. These modules +# define which $func callables are available to use in prototypes. +FUNCPARSER_PROTOTYPE_PARSING_MODULES = ["evennia.prototypes.protfuncs", + "server.conf.prototypefuncs"] + +###################################################################### +# Global Scripts +###################################################################### + +# Global scripts started here will be available through +# 'evennia.GLOBAL_SCRIPTS.key'. The scripts will survive a reload and be +# recreated automatically if deleted. Each entry must have the script keys, +# whereas all other fields in the specification are optional. If 'typeclass' is +# not given, BASE_SCRIPT_TYPECLASS will be assumed. Note that if you change +# typeclass for the same key, a new Script will replace the old one on +# `evennia.GLOBAL_SCRIPTS`. +GLOBAL_SCRIPTS = { + # 'key': {'typeclass': 'typeclass.path.here', + # 'repeats': -1, 'interval': 50, 'desc': 'Example script'}, +} + +###################################################################### +# Default Account setup and access +###################################################################### + +# Different Multisession modes allow a player (=account) to connect to the +# game simultaneously with multiple clients (=sessions). In modes 0,1 there is +# only one character created to the same name as the account at first login. +# In modes 2,3 no default character will be created and the MAX_NR_CHARACTERS +# value (below) defines how many characters the default char_create command +# allow per account. +# 0 - single session, one account, one character, when a new session is +# connected, the old one is disconnected +# 1 - multiple sessions, one account, one character, each session getting +# the same data +# 2 - multiple sessions, one account, many characters, one session per +# character (disconnects multiplets) +# 3 - like mode 2, except multiple sessions can puppet one character, each +# session getting the same data. +MULTISESSION_MODE = 0 +# The maximum number of characters allowed by the default ooc char-creation command +MAX_NR_CHARACTERS = 1 +# The access hierarchy, in climbing order. A higher permission in the +# hierarchy includes access of all levels below it. Used by the perm()/pperm() +# lock functions, which accepts both plural and singular (Admin & Admins) +PERMISSION_HIERARCHY = [ + "Guest", # note-only used if GUEST_ENABLED=True + "Player", + "Helper", + "Builder", + "Admin", + "Developer", +] +# The default permission given to all new accounts +PERMISSION_ACCOUNT_DEFAULT = "Player" +# Default sizes for client window (in number of characters), if client +# is not supplying this on its own +CLIENT_DEFAULT_WIDTH = 78 +# telnet standard height is 24; does anyone use such low-res displays anymore? +CLIENT_DEFAULT_HEIGHT = 45 +# Set rate limits per-IP on account creations and login attempts. Set limits +# to None to disable. +CREATION_THROTTLE_LIMIT = 2 +CREATION_THROTTLE_TIMEOUT = 10 * 60 +LOGIN_THROTTLE_LIMIT = 5 +LOGIN_THROTTLE_TIMEOUT = 5 * 60 +# Certain characters, like html tags, line breaks and tabs are stripped +# from user input for commands using the `evennia.utils.strip_unsafe_input` helper +# since they can be exploitative. This list defines Account-level permissions +# (and higher) that bypass this stripping. It is used as a fallback if a +# specific list of perms are not given to the helper function. +INPUT_CLEANUP_BYPASS_PERMISSIONS = ['Builder'] + + +###################################################################### +# Guest accounts +###################################################################### + +# This enables guest logins, by default via "connect guest". Note that +# you need to edit your login screen to inform about this possibility. +GUEST_ENABLED = False +# Typeclass for guest account objects (linked to a character) +BASE_GUEST_TYPECLASS = "typeclasses.accounts.Guest" +# The permission given to guests +PERMISSION_GUEST_DEFAULT = "Guests" +# The default home location used for guests. +GUEST_HOME = DEFAULT_HOME +# The start position used for guest characters. +GUEST_START_LOCATION = START_LOCATION +# The naming convention used for creating new guest +# accounts/characters. The size of this list also determines how many +# guests may be on the game at once. The default is a maximum of nine +# guests, named Guest1 through Guest9. +GUEST_LIST = ["Guest" + str(s + 1) for s in range(9)] + +###################################################################### +# In-game Channels created from server start +###################################################################### + +# The mudinfo channel is a read-only channel used by Evennia to replay status +# messages, connection info etc to staff. The superuser will automatically be +# subscribed to this channel. If set to None, the channel is disabled and +# status messages will only be logged (not recommended). +CHANNEL_MUDINFO = { + "key": "MudInfo", + "aliases": "", + "desc": "Connection log", + "locks": "control:perm(Developer);listen:perm(Admin);send:false()", +} +# Optional channel (same form as CHANNEL_MUDINFO) that will receive connection +# messages like (" has (dis)connected"). While the MudInfo channel +# will also receieve this info, this channel is meant for non-staffers. If +# None, this information will only be logged. +CHANNEL_CONNECTINFO = None +# New accounts will auto-sub to the default channels given below (but they can +# unsub at any time). Traditionally, at least 'public' should exist. Entries +# will be (re)created on the next reload, but removing or updating a same-key +# channel from this list will NOT automatically change/remove it in the game, +# that needs to be done manually. Note: To create other, non-auto-subbed +# channels, create them manually in server/conf/at_initial_setup.py. +DEFAULT_CHANNELS = [ + { + "key": "Public", + "aliases": ("pub",), + "desc": "Public discussion", + "locks": "control:perm(Admin);listen:all();send:all()", + "typeclass": BASE_CHANNEL_TYPECLASS, + } +] + +###################################################################### +# External Connections +###################################################################### + +# Note: You do *not* have to make your MUD open to +# the public to use the external connections, they +# operate as long as you have an internet connection, +# just like stand-alone chat clients. + +# The Evennia Game Index is a dynamic listing of Evennia games. You can add your game +# to this list also if it is in closed pre-alpha development. +GAME_INDEX_ENABLED = False +# This dict +GAME_INDEX_LISTING = { + "game_name": "Mygame", # usually SERVERNAME + "game_status": "pre-alpha", # pre-alpha, alpha, beta or launched + "short_description": "", # could be GAME_SLOGAN + "long_description": "", + "listing_contact": "", # email + "telnet_hostname": "", # mygame.com + "telnet_port": "", # 1234 + "game_website": "", # http://mygame.com + "web_client_url": "", # http://mygame.com/webclient +} +# Evennia can connect to external IRC channels and +# echo what is said on the channel to IRC and vice +# versa. Obs - make sure the IRC network allows bots. +# When enabled, command @irc2chan will be available in-game +# IRC requires that you have twisted.words installed. +IRC_ENABLED = False +# RSS allows to connect RSS feeds (from forum updates, blogs etc) to +# an in-game channel. The channel will be updated when the rss feed +# updates. Use @rss2chan in game to connect if this setting is +# active. OBS: RSS support requires the python-feedparser package to +# be installed (through package manager or from the website +# http://code.google.com/p/feedparser/) +RSS_ENABLED = False +RSS_UPDATE_INTERVAL = 60 * 10 # 10 minutes +# Grapevine (grapevine.haus) is a network for listing MUDs as well as allow +# users of said MUDs to communicate with each other on shared channels. To use, +# your game must first be registered by logging in and creating a game entry at +# https://grapevine.haus. Evennia links grapevine channels to in-game channels +# with the @grapevine2chan command, available once this flag is set +# Grapevine requires installing the pyopenssl library (pip install pyopenssl) +GRAPEVINE_ENABLED = False +# Grapevine channels to allow connection to. See https://grapevine.haus/chat +# for the available channels. Only channels in this list can be linked to in-game +# channels later. +GRAPEVINE_CHANNELS = ["gossip", "testing"] +# Grapevine authentication. Register your game at https://grapevine.haus to get +# them. These are secret and should thus be overridden in secret_settings file +GRAPEVINE_CLIENT_ID = "" +GRAPEVINE_CLIENT_SECRET = "" + +###################################################################### +# Django web features +###################################################################### + +# While DEBUG is False, show a regular server error page on the web +# stuff, email the traceback to the people in the ADMINS tuple +# below. If True, show a detailed traceback for the web +# browser to display. Note however that this will leak memory when +# active, so make sure to turn it off for a production server! +DEBUG = False +# Emails are sent to these people if the above DEBUG value is False. If you'd +# rather prefer nobody receives emails, leave this commented out or empty. +ADMINS = () # 'Your Name', 'your_email@domain.com'),) +# These guys get broken link notifications when SEND_BROKEN_LINK_EMAILS is True. +MANAGERS = ADMINS +# This is a public point of contact for players or the public to contact +# a staff member or administrator of the site. It is publicly posted. +STAFF_CONTACT_EMAIL = None +# If using Sites/Pages from the web admin, this value must be set to the +# database-id of the Site (domain) we want to use with this game's Pages. +SITE_ID = 1 +# The age for sessions. +# Default: 1209600 (2 weeks, in seconds) +SESSION_COOKIE_AGE = 1209600 +# Session cookie domain +# Default: None +SESSION_COOKIE_DOMAIN = None +# The name of the cookie to use for sessions. +# Default: 'sessionid' +SESSION_COOKIE_NAME = "sessionid" +# Should the session expire when the browser closes? +# Default: False +SESSION_EXPIRE_AT_BROWSER_CLOSE = False +# If you set this to False, Django will make some optimizations so as not +# to load the internationalization machinery. +USE_I18N = False + +# Where to find locales (no need to change this, most likely) +LOCALE_PATHS = [os.path.join(EVENNIA_DIR, "locale/")] +# How to display time stamps in e.g. the admin +SHORT_DATETIME_FORMAT = 'Y-m-d H:i:s.u' +DATETIME_FORMAT = 'Y-m-d H:i:s' # ISO 8601 but without T and timezone +# This should be turned off unless you want to do tests with Django's +# development webserver (normally Evennia runs its own server) +SERVE_MEDIA = False +# The master urlconf file that contains all of the sub-branches to the +# applications. Change this to add your own URLs to the website. +ROOT_URLCONF = "web.urls" +# Where users are redirected after logging in via contrib.auth.login. +LOGIN_REDIRECT_URL = "/" +# Where to redirect users when using the @login_required decorator. +LOGIN_URL = reverse_lazy("login") +# Where to redirect users who wish to logout. +LOGOUT_URL = reverse_lazy("logout") +# URL that handles the media served from MEDIA_ROOT. +# Example: "http://media.lawrence.com" +MEDIA_URL = "/media/" +# Absolute path to the directory that holds file uploads from web apps. +MEDIA_ROOT = os.path.join(GAME_DIR, "server", ".media") +# URL prefix for admin media -- CSS, JavaScript and images. Make sure +# to use a trailing slash. Admin-related files are searched under STATIC_URL/admin. +STATIC_URL = "/static/" +# Absolute path to directory where the static data will be gathered into to be +# served by webserver. +STATIC_ROOT = os.path.join(GAME_DIR, "server", ".static") +# Location of static data to overload the defaults from +# evennia/web/static. +STATICFILES_DIRS = [os.path.join(GAME_DIR, "web", "static")] +# Patterns of files in the static directories. Used here to make sure that +# its readme file is preserved but unused. +STATICFILES_IGNORE_PATTERNS = ["README.md"] +# The name of the currently selected web template. This corresponds to the +# directory names shown in the templates directory. +WEBSITE_TEMPLATE = "website" +WEBCLIENT_TEMPLATE = "webclient" +# We setup the location of the website template as well as the admin site. +TEMPLATES = [ + { + "BACKEND": "django.template.backends.django.DjangoTemplates", + "DIRS": [ + os.path.join(GAME_DIR, "web", "templates"), + os.path.join(GAME_DIR, "web", "templates", WEBSITE_TEMPLATE), + os.path.join(GAME_DIR, "web", "templates", WEBCLIENT_TEMPLATE), + os.path.join(EVENNIA_DIR, "web", "templates"), + os.path.join(EVENNIA_DIR, "web", "templates", WEBSITE_TEMPLATE), + os.path.join(EVENNIA_DIR, "web", "templates", WEBCLIENT_TEMPLATE), + ], + "APP_DIRS": True, + "OPTIONS": { + "context_processors": [ + "django.template.context_processors.i18n", + "django.template.context_processors.request", + "django.contrib.auth.context_processors.auth", + "django.template.context_processors.media", + "django.template.context_processors.debug", + "django.contrib.messages.context_processors.messages", + "sekizai.context_processors.sekizai", + "evennia.web.utils.general_context.general_context", + ], + # While true, show "pretty" error messages for template syntax errors. + "debug": DEBUG, + }, + } +] +# Django cache settings +# https://docs.djangoproject.com/en/dev/topics/cache/#setting-up-the-cache +CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache', + }, + 'throttle': { + 'BACKEND': 'django.core.cache.backends.locmem.LocMemCache', + 'TIMEOUT': 60 * 5, + 'OPTIONS': { + 'MAX_ENTRIES': 2000 + } + } +} +# MiddleWare are semi-transparent extensions to Django's functionality. +# see http://www.djangoproject.com/documentation/middleware/ for a more detailed +# explanation. +MIDDLEWARE = [ + "django.middleware.common.CommonMiddleware", + "django.contrib.sessions.middleware.SessionMiddleware", + "django.contrib.messages.middleware.MessageMiddleware", # 1.4? + "django.contrib.auth.middleware.AuthenticationMiddleware", + "django.middleware.csrf.CsrfViewMiddleware", + "django.contrib.admindocs.middleware.XViewMiddleware", + "django.contrib.flatpages.middleware.FlatpageFallbackMiddleware", + "evennia.web.utils.middleware.SharedLoginMiddleware", +] + +###################################################################### +# Evennia components +###################################################################### + +# Global and Evennia-specific apps. This ties everything together so we can +# refer to app models and perform DB syncs. +INSTALLED_APPS = [ + "django.contrib.auth", + "django.contrib.contenttypes", + "django.contrib.sessions", + "django.contrib.admindocs", + "django.contrib.flatpages", + "django.contrib.sites", + "django.contrib.staticfiles", + "evennia.web.utils.adminsite.EvenniaAdminApp", # replaces django.contrib.admin + "django.contrib.messages", + "rest_framework", + "django_filters", + "sekizai", + "evennia.utils.idmapper", + "evennia.server", + "evennia.typeclasses", + "evennia.accounts", + "evennia.objects", + "evennia.comms", + "evennia.help", + "evennia.scripts", + "evennia.web", +] +# The user profile extends the User object with more functionality; +# This should usually not be changed. +AUTH_USER_MODEL = "accounts.AccountDB" + +# Password validation plugins +# https://docs.djangoproject.com/en/1.11/ref/settings/#auth-password-validators +AUTH_PASSWORD_VALIDATORS = [ + {"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"}, + { + "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator", + "OPTIONS": {"min_length": 8}, + }, + {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"}, + {"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"}, + {"NAME": "evennia.server.validators.EvenniaPasswordValidator"}, +] + +# Username validation plugins +AUTH_USERNAME_VALIDATORS = [ + {"NAME": "django.contrib.auth.validators.ASCIIUsernameValidator"}, + {"NAME": "django.core.validators.MinLengthValidator", "OPTIONS": {"limit_value": 3},}, + {"NAME": "django.core.validators.MaxLengthValidator", "OPTIONS": {"limit_value": 30},}, + {"NAME": "evennia.server.validators.EvenniaUsernameAvailabilityValidator"}, +] + +# Use a custom test runner that just tests Evennia-specific apps. +TEST_RUNNER = "evennia.server.tests.testrunner.EvenniaTestSuiteRunner" + +# Messages and Bootstrap don't classify events the same way; this setting maps +# messages.error() to Bootstrap 'danger' classes. +MESSAGE_TAGS = {messages.ERROR: "danger"} + +# Django REST Framework settings +REST_FRAMEWORK = { + # django_filters allows you to specify search fields for models in an API View + "DEFAULT_FILTER_BACKENDS": ("django_filters.rest_framework.DjangoFilterBackend",), + # whether to paginate results and how many per page + "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.LimitOffsetPagination", + "PAGE_SIZE": 25, + # require logged in users to call API so that access checks can work on them + "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated",], + # These are the different ways people can authenticate for API requests - via + # session or with user/password. Other ways are possible, such as via tokens + # or oauth, but require additional dependencies. + "DEFAULT_AUTHENTICATION_CLASSES": [ + "rest_framework.authentication.BasicAuthentication", + "rest_framework.authentication.SessionAuthentication", + ], + # default permission checks used by the EvenniaPermission class + "DEFAULT_CREATE_PERMISSION": "builder", + "DEFAULT_LIST_PERMISSION": "builder", + "DEFAULT_VIEW_LOCKS": ["examine"], + "DEFAULT_DESTROY_LOCKS": ["delete"], + "DEFAULT_UPDATE_LOCKS": ["control", "edit"], + # No throttle class set by default. Setting one also requires a cache backend to be specified. +} + +# To enable the REST api, turn this to True +REST_API_ENABLED = False + +###################################################################### +# Networking Replaceables +###################################################################### +# This allows for replacing the very core of the infrastructure holding Evennia +# together with your own variations. You should usually never have to touch +# this, and if so, you really need to know what you are doing. + +# The Base Session Class is used as a parent class for all Protocols such as +# Telnet and SSH.) Changing this could be really dangerous. It will cascade +# to tons of classes. You generally shouldn't need to touch protocols. +BASE_SESSION_CLASS = "evennia.server.session.Session" + +# Telnet Protocol inherits from whatever above BASE_SESSION_CLASS is specified. +# It is used for all telnet connections, and is also inherited by the SSL Protocol +# (which is just TLS + Telnet). +TELNET_PROTOCOL_CLASS = "evennia.server.portal.telnet.TelnetProtocol" +SSL_PROTOCOL_CLASS = "evennia.server.portal.ssl.SSLProtocol" + +# Websocket Client Protocol. This inherits from BASE_SESSION_CLASS. It is used +# for all webclient connections. +WEBSOCKET_PROTOCOL_CLASS = "evennia.server.portal.webclient.WebSocketClient" + +# Protocol for the SSH interface. This inherits from BASE_SESSION_CLASS. +SSH_PROTOCOL_CLASS = "evennia.server.portal.ssh.SshProtocol" + +# Server-side session class used. This will inherit from BASE_SESSION_CLASS. +# This one isn't as dangerous to replace. +SERVER_SESSION_CLASS = "evennia.server.serversession.ServerSession" + +# The Server SessionHandler manages all ServerSessions, handling logins, +# ensuring the login process happens smoothly, handling expected and +# unexpected disconnects. You shouldn't need to touch it, but you can. +# Replace it to implement altered game logic. +SERVER_SESSION_HANDLER_CLASS = "evennia.server.sessionhandler.ServerSessionHandler" + +# The Portal SessionHandler manages all incoming connections regardless of +# the protocol in use. It is responsible for keeping them going and informing +# the Server Session Handler of the connections and synchronizing them across the +# AMP connection. You shouldn't ever need to change this. But you can. +PORTAL_SESSION_HANDLER_CLASS = "evennia.server.portal.portalsessionhandler.PortalSessionHandler" + + +# These are members / properties / attributes kept on both Server and +# Portal Sessions. They are sync'd at various points, such as logins and +# reloads. If you add to this, you may need to adjust the class __init__ +# so the additions have somewhere to go. These must be simple things that +# can be pickled - stuff you could serialize to JSON is best. +SESSION_SYNC_ATTRS = ( + "protocol_key", + "address", + "suid", + "sessid", + "uid", + "csessid", + "uname", + "logged_in", + "puid", + "conn_time", + "cmd_last", + "cmd_last_visible", + "cmd_total", + "protocol_flags", + "server_data", + "cmdset_storage_string", +) + +# The following are used for the communications between the Portal and Server. +# Very dragons territory. +AMP_SERVER_PROTOCOL_CLASS = "evennia.server.portal.amp_server.AMPServerProtocol" +AMP_CLIENT_PROTOCOL_CLASS = "evennia.server.amp_client.AMPServerClientProtocol" + +# don't change this manually, it can be checked from code to know if +# being run from a unit test (set by the evennia.utils.test_resources.BaseEvenniaTest +# and BaseEvenniaTestCase unit testing parents) +_TEST_ENVIRONMENT = False + +###################################################################### +# Django extensions +###################################################################### + +# Django extesions are useful third-party tools that are not +# always included in the default django distro. +try: + import django_extensions # noqa + + INSTALLED_APPS += ["django_extensions"] +except ImportError: + # Django extensions are not installed in all distros. + pass + +####################################################################### +# SECRET_KEY +####################################################################### +# This is the signing key for the cookies generated by Evennia's +# web interface. +# +# It is a fallback for the SECRET_KEY setting in settings.py, which +# is randomly seeded when settings.py is first created. If copying +# from here, make sure to change it! +SECRET_KEY = "changeme!(*#&*($&*(#*(&SDFKJJKLS*(@#KJAS" + +``` diff --git a/docs/source/Setup/Settings-File.md b/docs/source/Setup/Settings-File.md deleted file mode 100644 index a035a66873..0000000000 --- a/docs/source/Setup/Settings-File.md +++ /dev/null @@ -1,3 +0,0 @@ -# The Evennia Default Settings file - -TODO \ No newline at end of file diff --git a/docs/source/Setup/Setup-Overview.md b/docs/source/Setup/Setup-Overview.md index 6c49ae743d..456c3ddf3d 100644 --- a/docs/source/Setup/Setup-Overview.md +++ b/docs/source/Setup/Setup-Overview.md @@ -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 diff --git a/docs/source/Setup/Setup-Quickstart.md b/docs/source/Setup/Setup-Quickstart.md deleted file mode 100644 index b64350b72b..0000000000 --- a/docs/source/Setup/Setup-Quickstart.md +++ /dev/null @@ -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! diff --git a/docs/source/Setup/Start-Stop-Reload.md b/docs/source/Setup/Start-Stop-Reload.md index 32fc11189d..80cb76cf3e 100644 --- a/docs/source/Setup/Start-Stop-Reload.md +++ b/docs/source/Setup/Start-Stop-Reload.md @@ -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. diff --git a/docs/source/conf.py b/docs/source/conf.py index 2c4c846a39..1d93ec24dc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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 diff --git a/docs/source/index.md b/docs/source/index.md index f7dae8eef5..c9430d5754 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -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) diff --git a/docs/source/toc.md b/docs/source/toc.md index 61581c5989..e5556895fe 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -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