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

Refactored Contrib docs, renamed many files

Browse source
This commit is contained in:
Griatch 2022-11-23 21:15:23 +01:00
parent 7845369d50
commit da341af663
44 changed files with 664 additions and 917 deletions
Download patch file Download diff file Expand all files Collapse all files

114
docs/source/Howtos/Beginner-Tutorial/Beginner-Tutorial-Intro.md
View file

@ -1,114 +0,0 @@
# Beginner Tutorial
```{sidebar} Beginner Tutorial Parts
- **[Introduction](./Beginner-Tutorial-Intro.md)**
<br>Getting set up.
- Part 1: [What we have](Part1/Beginner-Tutorial-Part1-Intro.md)
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- Part 2: [What we want](Part2/Beginner-Tutorial-Part2-Intro.md)
<br>Planning our tutorial game and what to think about when planning your own in the future.
- Part 3: [How we get there](Part3/Beginner-Tutorial-Part3-Intro.md)
<br>Getting down to the meat of extending Evennia to make our game
- Part 4: [Using what we created](Part4/Beginner-Tutorial-Part4-Intro.md)
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](Part5/Beginner-Tutorial-Part5-Intro.md)
<br>Taking our new game online and let players try it out
```
Welcome to Evennia! This multi-part Beginner Tutorial will help you get off the ground. It consists
of five parts, each with several lessons. You can pick what seems interesting, but if you
follow through to the end you will have created a little online game of your own to play
and share with others!
Use the menu on the right to get the index of each tutorial-part. Use the [next](Part1/Beginner-Tutorial-Part1-Intro.md)
and [previous](../Howtos-Overview.md) links to step from lesson to lesson.
## Things you need
- A Command line
- A MUD client (or web browser)
- A text-editor/IDE
- Evennia installed and a game-dir initialized
### A Command line
You need to know how to find your Terminal/Console in your OS. The Evennia server can be controlled
from in-game, but you _will_ need to use the command-line to get anywhere. Here are some starters:
- [Django-girls' Intro to the Command line for different OS:es](https://tutorial.djangogirls.org/en/intro_to_command_line/)
Note that we usually only show forward-slashes `/` for file system paths. Windows users should mentally convert this to
back-slashes `\` instead.
### A MUD client
You might already have a MUD-client you prefer. Check out the [grid of supported clients](../../Setup/Client-Support-Grid.md) for aid.
If telnet's not your thing, you can also just use Evennia's web client in your browser.
> In this documentation we often use the terms 'MUD', 'MU' or 'MU*' interchangeably
to represent all the historically different forms of text-based multiplayer game-styles,
like MUD, MUX, MUSH, MUCK, MOO and others. Evennia can be used to create all those game-styles
and more.
### An Editor
You need a text-editor to edit Python source files. Most everything that can edit and output raw
text works (so not Word).
- [Here's a blog post summing up some of the alternatives](https://www.elegantthemes.com/blog/resources/best-code-editors) - these
things don't change much from year to year. Popular choices for Python are PyCharm, VSCode, Atom, Sublime Text and Notepad++.
Evennia is to a very large degree coded in VIM, but that's not suitable for beginners.
> Hint: When setting up your editor, make sure that pressing TAB inserts _4 spaces_ rather than a Tab-character. Since
> Python is whitespace-aware, this will make your life a lot easier.
### Set up a game dir for the tutorial
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.
- If you want a new gamedir for the tutorial game and already have Evennia running with another gamedir,
first enter that gamedir and run
evennia stop
> If you want to run two parallel servers, that'd be fine too, but one would have to use
> different ports from the defaults, or there'd be a clash. We will go into changing settings later.
- Now go to where you want to create your tutorial-game. We will always refer to it as `mygame` so
it may be convenient if you do too:
evennia --init mygame
cd mygame
evennia migrate
evennia start --log
Add your superuser name and password at the prompt (email is optional). Make sure you can
go to `localhost:4000` in your MUD client or to [http://localhost:4001](http://localhost:4001)
in your web browser (Mac users: Try `127.0.0.1` instead of `localhost` if you have trouble).
The above `--log` flag will have Evennia output all its logs to the terminal. This will block
the terminal from other input. To leave the log-view, press `Ctrl-C` (`Cmd-C` on Mac). To see
the log again just run
evennia --log
You should now be good to go on to [the first part of the tutorial](Part1/Beginner-Tutorial-Part1-Intro.md).
Good luck!
<details>
<summary>
Click here to expand a list of all Beginner-Tutorial sections (all parts).
</summary>
```{toctree}
Part1/Beginner-Tutorial-Part1-Intro
Part2/Beginner-Tutorial-Part2-Intro
Part3/Beginner-Tutorial-Part3-Intro
Part4/Beginner-Tutorial-Part4-Intro
Part5/Beginner-Tutorial-Part5-Intro
```
</details>

82
docs/source/Howtos/Beginner-Tutorial/Beginner-Tutorial-Overview.md Normal file
View file

@ -0,0 +1,82 @@
# Beginner Tutorial
```{sidebar} Beginner Tutorial Parts
- **[Introduction](./Beginner-Tutorial-Overview.md)**
<br>Getting set up.
- Part 1: [What we have](Part1/Beginner-Tutorial-Part1-Overview.md)
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- Part 2: [What we want](Part2/Beginner-Tutorial-Part2-Overview.md)
<br>Planning our tutorial game and what to think about when planning your own in the future.
- Part 3: [How we get there](Part3/Beginner-Tutorial-Part3-Overview.md)
<br>Getting down to the meat of extending Evennia to make our game
- Part 4: [Using what we created](Part4/Beginner-Tutorial-Part4-Overview.md)
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](Part5/Beginner-Tutorial-Part5-Overview.md)
<br>Taking our new game online and let players try it out
```
Welcome to Evennia! This multi-part Beginner Tutorial will help you get off the ground.
You can pick what seems interesting, but if you follow through to the end you will have created a little online game of your own to play and share with others!
Use the menu on the right to get the index of each tutorial-part. Use the [next](Part1/Beginner-Tutorial-Part1-Overview.md) and [previous](../Howtos-Overview.md) links at the top/bottom right of the page to step between lessons.
## Things you need
- A Command line
- A MUD client (or web browser)
- A text-editor/IDE
- Evennia installed and a game-dir initialized
### A Command line
You need to know how to find your Terminal/Console in your OS. The Evennia server can be controlled from in-game, but you _will_ need to use the command-line to get anywhere. Here are some starters:
- [Online Intro to the Command line for different OS:es](https://tutorial.djangogirls.org/en/intro_to_command_line/)
> Note that we usually only show forward-slashes `/` for file system paths. Windows users should mentally convert this to back-slashes `\` instead.
### A MUD client
You might already have a MUD-client you prefer. Check out the [grid of supported clients](../../Setup/Client-Support-Grid.md).
If telnet's not your thing, you can also just use Evennia's web client in your browser.
> In this documentation we often use the terms 'MUD', 'MU' or 'MU*' interchangeably to represent all the historically different forms of text-based multiplayer game-styles, like MUD, MUX, MUSH, MUCK, MOO and others. Evennia can be used to create all those game-styles and more.
### A text Editor or IDE
You need a text-editor to edit Python source files. Most everything that can edit and output raw
text works (so not Word).
- [Here's a blog post summing up some of the alternatives](https://www.elegantthemes.com/blog/resources/best-code-editors) - these things don't change much from year to year. Popular choices for Python are PyCharm, VSCode, Atom, Sublime Text and Notepad++. Evennia is to a very large degree coded in VIM, but that's not suitable for beginners.
```{important} Use spaces, not tabs
```
> Make sure to configure your editor so that pressing TAB inserts _4 spaces_ rather than a Tab-character. Since Python is whitespace-aware, this will make your life a lot easier.
### A fresh game dir?
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 re-use that or make a new one only for this tutorial, it's up to you.
If you already have a game dir and want a separate one for the tutorial, use `evennia stop` to halt the running server and then [Initialize a new game dir](../../Setup/Installation.md#initialize-a-new-game) somewhere else (_not_ inside the previous game dir!). We refer to it everywhere as `mygame`, so you may want to do the same.
You should now be ready to move on to the [first lesson](Part1/Beginner-Tutorial-Part1-Overview.md)
<details>
<summary>
Click here to expand a list of all Beginner-Tutorial sections (all parts).
</summary>
```{toctree}
Part1/Beginner-Tutorial-Part1-Overview
Part2/Beginner-Tutorial-Part2-Overview
Part3/Beginner-Tutorial-Part3-Overview
Part4/Beginner-Tutorial-Part4-Overview
Part5/Beginner-Tutorial-Part5-Overview
```
</details>

12
docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Intro.md → docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Part1-Overview.md
View file

@ -1,17 +1,17 @@
# Part 1: What we have
```{sidebar} Beginner Tutorial Parts
- [Introduction](../Beginner-Tutorial-Intro.md)
- [Introduction](../Beginner-Tutorial-Overview.md)
<br>Getting set up.
- Part 1: **[What we have](./Beginner-Tutorial-Part1-Intro.md)**
- Part 1: **[What we have](./Beginner-Tutorial-Part1-Overview.md)**
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- Part 2: [What we want](../Part2/Beginner-Tutorial-Part2-Intro.md)
- Part 2: [What we want](../Part2/Beginner-Tutorial-Part2-Overview.md)
<br>Planning our tutorial game and what to think about when planning your own in the future.
- Part 3: [How we get there](../Part3/Beginner-Tutorial-Part3-Intro.md)
- Part 3: [How we get there](../Part3/Beginner-Tutorial-Part3-Overview.md)
<br>Getting down to the meat of extending Evennia to make our game
- Part 4: [Using what we created](../Part4/Beginner-Tutorial-Part4-Intro.md)
- Part 4: [Using what we created](../Part4/Beginner-Tutorial-Part4-Overview.md)
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Intro.md)
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Overview.md)
<br>Taking our new game online and let players try it out
```

12
docs/source/Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Part2-Intro.md → docs/source/Howtos/Beginner-Tutorial/Part2/Beginner-Tutorial-Part2-Overview.md
View file

@ -1,17 +1,17 @@
# Part 2: What we want
```{sidebar} Beginner Tutorial Parts
- [Introduction](../Beginner-Tutorial-Intro.md)
- [Introduction](../Beginner-Tutorial-Overview.md)
<br>Getting set up.
- Part 1: [What we have](../Part1/Beginner-Tutorial-Part1-Intro.md)
- Part 1: [What we have](../Part1/Beginner-Tutorial-Part1-Overview.md)
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- **Part 2: [What we want](./Beginner-Tutorial-Part2-Intro.md)**
- **Part 2: [What we want](./Beginner-Tutorial-Part2-Overview.md)**
<br>Planning our tutorial game and what to think about when planning your own in the future.
- Part 3: [How we get there](../Part3/Beginner-Tutorial-Part3-Intro.md)
- Part 3: [How we get there](../Part3/Beginner-Tutorial-Part3-Overview.md)
<br>Getting down to the meat of extending Evennia to make our game
- Part 4: [Using what we created](../Part4/Beginner-Tutorial-Part4-Intro.md)
- Part 4: [Using what we created](../Part4/Beginner-Tutorial-Part4-Overview.md)
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Intro.md)
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Overview.md)
<br>Taking our new game online and let players try it out
```

12
docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Part3-Intro.md → docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Part3-Overview.md
View file

@ -7,17 +7,17 @@ from it at this time.
```
```{sidebar} Beginner Tutorial Parts
- [Introduction](../Beginner-Tutorial-Intro.md)
- [Introduction](../Beginner-Tutorial-Overview.md)
<br>Getting set up.
- Part 1: [What we have](../Part1/Beginner-Tutorial-Part1-Intro.md)
- Part 1: [What we have](../Part1/Beginner-Tutorial-Part1-Overview.md)
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- Part 2: [What we want](../Part2/Beginner-Tutorial-Part2-Intro.md)
- Part 2: [What we want](../Part2/Beginner-Tutorial-Part2-Overview.md)
<br>Planning our tutorial game and what to think about when planning your own in the future.
- **Part 3: [How we get there](./Beginner-Tutorial-Part3-Intro.md)**
- **Part 3: [How we get there](./Beginner-Tutorial-Part3-Overview.md)**
<br>Getting down to the meat of extending Evennia to make our game
- Part 4: [Using what we created](../Part4/Beginner-Tutorial-Part4-Intro.md)
- Part 4: [Using what we created](../Part4/Beginner-Tutorial-Part4-Overview.md)
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Intro.md)
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Overview.md)
<br>Taking our new game online and let players try it out
```

34
docs/source/Howtos/Beginner-Tutorial/Part4/Beginner-Tutorial-Part4-Intro.md
View file

@ -1,34 +0,0 @@
# Part 4: Using what we created
```{sidebar} Beginner Tutorial Parts
- [Introduction](../Beginner-Tutorial-Intro.md)
<br>Getting set up.
- Part 1: [What we have](../Part1/Beginner-Tutorial-Part1-Intro.md)
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- Part 2: [What we want](../Part2/Beginner-Tutorial-Part2-Intro.md)
<br>Planning our tutorial game and what to think about when planning your own in the future.
- Part 3: [How we get there](../Part3/Beginner-Tutorial-Part3-Intro.md)
<br>Getting down to the meat of extending Evennia to make our game
- **Part 4: [Using what we created](./Beginner-Tutorial-Part4-Intro.md)**
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Intro.md)
<br>Taking our new game online and let players try it out
```
We now have the code underpinnings of everything we need. We have also tested the various components
and has a simple tech-demo to show it all works together. But there is no real coherence to it at this
point - we need to actually make a world.
In part four we will expand our tech demo into a more full-fledged (if small) game by use of batchcommand
and batchcode processors.
## Lessons
_TODO_
```{toctree}
:numbered:
:maxdepth: 2
../../../Unimplemented.md
```

30
docs/source/Howtos/Beginner-Tutorial/Part4/Beginner-Tutorial-Part4-Overview.md Normal file
View file

@ -0,0 +1,30 @@
# Part 4: Using what we created
```{sidebar} Beginner Tutorial Parts
- [Introduction](../Beginner-Tutorial-Overview.md)
<br>Getting set up.
- Part 1: [What we have](../Part1/Beginner-Tutorial-Part1-Overview.md)
<br>A tour of Evennia and how to use the tools, including an introduction to Python.
- Part 2: [What we want](../Part2/Beginner-Tutorial-Part2-Overview.md)
<br>Planning our tutorial game and what to think about when planning your own in the future.
- Part 3: [How we get there](../Part3/Beginner-Tutorial-Part3-Overview.md)
<br>Getting down to the meat of extending Evennia to make our game
- **Part 4: [Using what we created](./Beginner-Tutorial-Part4-Overview.md)**
<br>Building a tech-demo and world content to go with our code
- Part 5: [Showing the world](../Part5/Beginner-Tutorial-Part5-Overview.md)
<br>Taking our new game online and let players try it out
```
We now have the code underpinnings of everything we need. We have also tested the various components and has a simple tech-demo to show it all works together. But there is no real coherence to it at this point - we need to actually make a world. In part four we will expand our tech demo into a more full-fledged (if small) game by use of batchcommand and batchcode processors.
## Lessons
_TODO_
```{toctree}
:numbered:
:maxdepth: 2
../../../Unimplemented.md
```

1
docs/source/Howtos/Beginner-Tutorial/Part5/Beginner-Tutorial-Part5-Intro.md → docs/source/Howtos/Beginner-Tutorial/Part5/Beginner-Tutorial-Part5-Overview.md
View file

@ -27,5 +27,4 @@ _TODO_
:numbered:
:maxdepth: 2
Add-a-simple-new-web-page.md
Web-Tutorial.md
```

126
docs/source/Howtos/Beginner-Tutorial/Part5/Web-Tutorial.md
View file

@ -1,126 +0,0 @@
# Web Tutorial
Evennia uses the [Django](https://www.djangoproject.com/) web framework as the basis of both its
database configuration and the website it provides. While a full understanding of Django requires
reading the Django documentation, we have provided this tutorial to get you running with the basics
and how they pertain to Evennia. This text details getting everything set up. The
[Web-based Character view Tutorial](../../Web-Character-View-Tutorial.md) gives a more explicit example of making a
custom web page connected to your game, and you may want to read that after finishing this guide.
## A Basic Overview
Django is a web framework. It gives you a set of development tools for building a website quickly
and easily.
Django projects are split up into *apps* and these apps all contribute to one project. For instance,
you might have an app for conducting polls, or an app for showing news posts or, like us, one for
creating a web client.
Each of these applications has a `urls.py` file, which specifies what
[URL](https://en.wikipedia.org/wiki/Uniform_resource_locator)s are used by the app, a `views.py` file
for the code that the URLs activate, a `templates` directory for displaying the results of that code
in [HTML](https://en.wikipedia.org/wiki/Html) for the user, and a `static` folder that holds assets
like [CSS](https://en.wikipedia.org/wiki/CSS), [Javascript](https://en.wikipedia.org/wiki/Javascript),
and Image files (You may note your mygame/web folder does not have a `static` or `template` folder.
This is intended and explained further below). Django applications may also have a `models.py` file
for storing information in the database. We will not change any models here, take a look at the
[New Models](../../../Concepts/New-Models.md) page (as well as the [Django docs](https://docs.djangoproject.com/en/1.7/topics/db/models/) on models) if you are interested.
There is also a root `urls.py` that determines the URL structure for the entire project. A starter
`urls.py` is included in the default game template, and automatically imports all of Evennia's
default URLs for you. This is located in `web/urls.py`.
## Changing the logo on the front page
Evennia's default logo is a fun little googly-eyed snake wrapped around a gear globe. As cute as it
is, it probably doesn't represent your game. So one of the first things you may wish to do is
replace it with a logo of your own.
Django web apps all have _static assets_: CSS files, Javascript files, and Image files. In order to
make sure the final project has all the static files it needs, the system collects the files from
every app's `static` folder and places it in the `STATIC_ROOT` defined in `settings.py`. By default,
the Evennia `STATIC_ROOT` is in `web/static`.
Because Django pulls files from all of those separate places and puts them in one folder, it's
possible for one file to overwrite another. We will use this to plug in our own files without having
to change anything in the Evennia itself.
By default, Evennia is configured to pull files you put in the `web/static_overrides` *after* all
other static files. That means that files in `static_overrides` folder will overwrite any previously
loaded files *having the same path under its static folder*. This last part is important to repeat:
To overload the static resource from a standard `static` folder you need to replicate the path of
folders and file names from that `static` folder in exactly the same way inside `static_overrides`.
Let's see how this works for our logo. The default web application is in the Evennia library itself,
in `evennia/web/`. We can see that there is a `static` folder here. If we browse down, we'll
eventually find the full path to the Evennia logo file:
`evennia/web/static/evennia_general/images/evennia_logo.png`.
Inside our `static_overrides` we must replicate the part of the path inside the `static` folder, in
other words, we must replicate `evennia_general/images/evennia_logo.png`.
So, to change the logo, we need to create the folder path `evennia_general/images/` in
`static_overrides`. We then rename our own logo file to `evennia_logo.png` and copy it there. The
final path for this file would thus be:
`web/static_overrides/evennia_general/images/evennia_logo.png` in your local game folder.
To get this file pulled in, just change to your own game directory and reload the server:
```
evennia reload
```
This will reload the configuration and bring in the new static file(s). If you didn't want to reload
the server you could instead use
```
evennia collectstatic
```
to only update the static files without any other changes.
> **Note**: Evennia will collect static files automatically during startup. So if `evennia
collectstatic` reports finding 0 files to collect, make sure you didn't start the engine at some
point - if so the collector has already done its work! To make sure, connect to the website and
check so the logo has actually changed to your own version.
> **Note**: Sometimes the static asset collector can get confused. If no matter what you do, your
overridden files aren't getting copied over the defaults, try removing the target file (or
everything) in the `web/static` directory, and re-running `collectstatic` to gather everything from
scratch.
## Changing the Front Page's Text
The default front page for Evennia contains information about the Evennia project. You'll probably
want to replace this information with information about your own project. Changing the page template
is done in a similar way to changing static resources.
Like static files, Django looks through a series of template folders to find the file it wants. The
difference is that Django does not copy all of the template files into one place, it just searches
through the template folders until it finds a template that matches what it's looking for. This
means that when you edit a template, the changes are instant. You don't have to reload the server or
run any extra commands to see these changes - reloading the web page in your browser is enough.
To replace the index page's text, we'll need to find the template for it. We'll go into more detail
about how to determine which template is used for rendering a page in the
[Web-based Character view Tutorial](../../Web-Character-View-Tutorial.md). For now, you should know that the template we want to change
is stored in `evennia/web/website/templates/website/index.html`.
To replace this template file, you will put your changed template inside the
`web/template_overrides/website` directory in your game folder. In the same way as with static
resources you must replicate the path inside the default `template` directory exactly. So we must
copy our replacement template named `index.html` there (or create the `website` directory in
web/template_overrides` if it does not exist, first). The final path to the file should thus be:
`web/template_overrides/website/index.html` within your game directory.
Note that it is usually easier to just copy the original template over and edit it in place. The
original file already has all the markup and tags, ready for editing.
## Further reading
For further hints on working with the web presence, you could now continue to the
[Web-based Character view Tutorial](../../Web-Character-View-Tutorial.md) where you learn to make a web page that
displays in-game character stats. You can also look at [Django's own
tutorial](https://docs.djangoproject.com/en/1.7/intro/tutorial01/) to get more insight in how Django
works and what possibilities exist.