Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-04-05 23:47:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs

Browse source
This commit is contained in:
Griatch 2021-10-26 21:41:11 +02:00
parent 66d0ad0bc9
commit 7900aad365
2073 changed files with 32986 additions and 41197 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/1.0-dev/_sources/Contribs/A-voice-operated-elevator-using-events.md.txt
View file

@ -1,7 +1,7 @@
# A voice operated elevator using events
- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events)
- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events.md)
This tutorial will walk you through the steps to create a voice-operated elevator, using the [in-
game Python
@ -97,7 +97,7 @@ things to decorate it a bit.
But what we want now is to be able to say "1", "2" or "3" and have the elevator move in that
direction.
If you have read [the previous tutorial about adding dialogues in events](./Dialogues-in-events), you
If you have read [the previous tutorial about adding dialogues in events](./Dialogues-in-events.md), you
may remember what we need to do. If not, here's a summary: we need to run some code when somebody
speaks in the room. So we need to create a callback (the callback will contain our lines of code).
We just need to know on which event this should be set. You can enter `call here` to see the
@ -433,4 +433,4 @@ to consider adding the code in the source itself. Another possibility is to cal
with the expected behavior, which makes porting code very easy. This side of chained events will be
shown in the next tutorial.
- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events)
- Previous tutorial: [Adding dialogues in events](./Dialogues-in-events.md)

76
docs/1.0-dev/_sources/Contribs/Arxcode-installing-help.md.txt
View file

@ -1,6 +1,6 @@
# Arxcode installing help
## Introduction
## Introduction
[Arx - After the Reckoning](https://play.arxmush.org/) is a big and very popular
[Evennia](https://www.evennia.com)-based game. Arx is heavily roleplaying-centric, relying on game
@ -10,20 +10,20 @@ Arx on github](https://github.com/Arx-Game/arxcode). This is a treasure-trove fo
to pick ideas or even get a starting game to build on. These instructions are based on the Arx-code
released as of *Aug 12, 2018*.
If you are not familiar with what Evennia is, you can read
[an introduction here](../Evennia-Introduction).
If you are not familiar with what Evennia is, you can read
[an introduction here](../Evennia-Introduction.md).
It's not too hard to run Arx from the sources (of course you'll start with an empty database) but
since part of Arx has grown organically, it doesn't follow standard Evennia paradigms everywhere.
This page covers one take on installing and setting things up while making your new Arx-based game
better match with the vanilla Evennia install.
better match with the vanilla Evennia install.
## Installing Evennia
Firstly, set aside a folder/directory on your drive for everything to follow.
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) for your OS. The difference is that you need to `git clone
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
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,10 +31,10 @@ 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](./Getting-Started#troubleshooting) for your
read the [Troubleshooting instructions](../Setup/Extended-Installation.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).
or chat from the linked [Discord Server](https://discord.gg/NecFePw).
After installing you should have a `virtualenv` running and you should have the following file
structure in your set-aside folder:
@ -49,35 +49,35 @@ mygame/
Here `mygame` is the empty game you created during the Evennia install, with `evennia --init`. Go to
that and run `evennia stop` to make sure your empty game is not running. We'll instead let Evenna
run Arx, so in principle you could erase `mygame` - but it could also be good to have a clean game
to compare to.
to compare to.
## Installing Arxcode
### Clone the arxcode repo
Cd to the root of your directory and clone the released source code from github:
Cd to the root of your directory and clone the released source code from github:
git clone https://github.com/Arx-Game/arxcode.git myarx
git clone https://github.com/Arx-Game/arxcode.git myarx
A new folder `myarx` should appear next to the ones you already had. You could rename this to
something else if you want.
something else if you want.
Cd into `myarx`. If you wonder about the structure of the game dir, you can
[read more about it here](../Howto/Starting/Part1/Gamedir-Overview).
Cd into `myarx`. If you wonder about the structure of the game dir, you can
[read more about it here](../Howto/Starting/Part1/Gamedir-Overview.md).
### Clean up settings
Arx has split evennia's normal settings into `base_settings.py` and `production_settings.py`. It
also has its own solution for managing 'secret' parts of the settings file. We'll keep most of Arx
way but remove the secret-handling and replace it with the normal Evennia method.
way but remove the secret-handling and replace it with the normal Evennia method.
Cd into `myarx/server/conf/` and open the file `settings.py` in a text editor. The top part (within
`"""..."""`) is just help text. Wipe everything underneath that and make it look like this instead
(don't forget to save):
(don't forget to save):
```
from base_settings import *
TELNET_PORTS = [4000]
SERVERNAME = "MyArx"
GAME_SLOGAN = "The cool game"
@ -97,7 +97,7 @@ the game a name. The slogan changes the sub-text shown under the name of your ga
header. You can tweak these to your own liking later.
Next, create a new, empty file `secret_settings.py` in the same location as the `settings.py` file.
This can just contain the following:
This can just contain the following:
```python
SECRET_KEY = "sefsefiwwj3 jnwidufhjw4545_oifej whewiu hwejfpoiwjrpw09&4er43233fwefwfw"
@ -105,35 +105,35 @@ SECRET_KEY = "sefsefiwwj3 jnwidufhjw4545_oifej whewiu hwejfpoiwjrpw09&4er43233fw
```
Replace the long random string with random ASCII characters of your own. The secret key should not
be shared.
be shared.
Next, open `myarx/server/conf/base_settings.py` in your text editor. We want to remove/comment out
all mentions of the `decouple` package, which Evennia doesn't use (we use `private_settings.py` to
hide away settings that should not be shared).
hide away settings that should not be shared).
Comment out `from decouple import config` by adding a `#` to the start of the line: `# from decouple
import config`. Then search for `config(` in the file and comment out all lines where this is used.
Many of these are specific to the server environment where the original Arx runs, so is not that
relevant to us.
relevant to us.
### Install Arx dependencies
### Install Arx dependencies
Arx has some further dependencies beyond vanilla Evennia. Start by `cd`:ing to the root of your
`myarx` folder.
`myarx` folder.
> If you run *Linux* or *Mac*: Edit `myarx/requirements.txt` and comment out the line
> `pypiwin32==219` - it's only needed on Windows and will give an error on other platforms.
> `pypiwin32==219` - it's only needed on Windows and will give an error on other platforms.
Make sure your `virtualenv` is active, then run
pip install -r requirements.txt
The needed Python packages will be installed for you.
The needed Python packages will be installed for you.
### Adding logs/ folder
The Arx repo does not contain the `myarx/server/logs/` folder Evennia expects for storing server
logs. This is simple to add:
logs. This is simple to add:
# linux/mac
mkdir server/logs
@ -142,7 +142,7 @@ logs. This is simple to add:
### Setting up the database and starting
From the `myarx` folder, run
From the `myarx` folder, run
evennia migrate
@ -153,7 +153,7 @@ This creates the database and will step through all database migrations needed.
If all goes well Evennia will now start up, running Arx! You can connect to it on `localhost` (or
`127.0.0.1` if your platform doesn't alias `localhost`), port `4000` using a Telnet client.
Alternatively, you can use your web browser to browse to `http://localhost:4001` to see the game's
website and get to the web client.
website and get to the web client.
When you log in you'll get the standard Evennia greeting (since the database is empty), but you can
try `help` to see that it's indeed Arx that is running.
@ -164,7 +164,7 @@ The first time you start Evennia after creating the database with the `evennia m
it should create a few starting objects for you - your superuser account, which it will prompt you
to enter, a starting room (Limbo), and a character object for you. If for some reason this does not
occur, you may have to follow the steps below. For the first time Superuser login you may have to
run steps 7-8 and 10 to create and connect to your in-came Character.
run steps 7-8 and 10 to create and connect to your in-came Character.
1. Login to the game website with your Superuser account.
2. Press the `Admin` button to get into the (Django-) Admin Interface.
@ -172,17 +172,17 @@ run steps 7-8 and 10 to create and connect to your in-came Character.
4. Add a new Account named for the new staffer. Use a place holder password and dummy e-mail
address.
5. Flag account as `Staff` and apply the `Admin` permission group (This assumes you have already set
up an Admin Group in Django).
6. Add Tags named `player` and `developer`.
up an Admin Group in Django).
6. Add Tags named `player` and `developer`.
7. Log into the game using the web client (or a third-party telnet client) using your superuser
account. Move to where you want the new staffer character to appear.
account. Move to where you want the new staffer character to appear.
8. In the game client, run `@create/drop <staffername>:typeclasses.characters.Character`, where
`<staffername>` is usually the same name you used for the Staffer account you created in the
Admin earlier (if you are creating a Character for your superuser, use your superuser account
name).
This creates a new in-game Character and places it in your current location.
9. Have the new Admin player log into the game.
10. Have the new Admin puppet the character with `@ic StafferName`.
10. Have the new Admin puppet the character with `@ic StafferName`.
11. Have the new Admin change their password - `@password <old password> = <new password>`.
Now that you have a Character and an Account object, there's a few additional things you may need to
@ -225,14 +225,14 @@ cd Source
mkdir Arx
cd Arx
Replace the SSH git clone links below with your own github forks.
If you don't plan to change Evennia at all, you can use the
Replace the SSH git clone links below with your own github forks.
If you don't plan to change Evennia at all, you can use the
evennia/evennia.git repo instead of a forked one.
git clone git@github.com:<youruser>/evennia.git
git clone git@github.com:<youruser>/arxcode.git
Evennia is a package itself, so we want to install it and all of its
Evennia is a package itself, so we want to install it and all of its
prerequisites, after switching to the appropriately-tagged branch for
Arxcode.
@ -247,7 +247,7 @@ cd ../arxcode
pip install -r requirements.txt
The git repo doesn't include the empty log directory and Evennia is unhappy if you
don't have it, so while still in the arxcode directory...
don't have it, so while still in the arxcode directory...
mkdir server/logs

48
docs/1.0-dev/_sources/Contribs/Contrib-Overview.md.txt
View file

@ -1,6 +1,6 @@
# Contrib modules
Contribs are found in [evennia/contrib/](api:evennia.contrib) and are optional game-specific code-snippets
Contribs are found in [evennia/contrib/](evennia.contrib) and are optional game-specific code-snippets
or even full systems you can use for your game. They are contributed by the Evennia community and
released under the same license as Evennia itself. Each contrib has its own installation instructions.
Bugs are reported to the Evennia [issue tracker](github:issue) as usual.
@ -46,7 +46,7 @@ Contribs modifying locations, movement or helping to creating rooms.
Adds an XYZgrid to Evennia, with map-display and pathfinding. Created via map
strings and maintained outside of the game via Evennia launch commands.
- [XYZGrid documentation](./XYZGrid)
- [XYZGrid documentation](./XYZGrid.md)
### Extended Room
@ -60,7 +60,7 @@ An expanded Room typeclass with multiple descriptions for time and season as wel
Build a game area based on a 2D "graphical" unicode map. Supports asymmetric exits.
- [Static in-game map](./Static-In-Game-Map)
- [Static in-game map](./Static-In-Game-Map.md)
### Simple Door
@ -80,7 +80,7 @@ Custom Exit class that takes different time to pass depending on if you are walk
Make infinitely large wilderness areas with dynamically created locations.
- [Dynamic in-game map](./Dynamic-In-Game-Map)
- [Dynamic in-game map](./Dynamic-In-Game-Map.md)
----
@ -100,9 +100,9 @@ A safe and effective barter-system for any game. Allows safe trading of any good
A full, extendable crafting system.
- [Crafting overview](./Crafting)
- [Crafting API documentation](api:evennia.contrib.crafting.crafting)
- [Example of a sword crafting tree](api:evennia.contrib.crafting.example_recipes)
- [Crafting overview](./Crafting.md)
- [Crafting API documentation](evennia.contrib.crafting.crafting)
- [Example of a sword crafting tree](evennia.contrib.crafting.example_recipes)
### Dice
@ -174,15 +174,15 @@ A simple system for creating an EvMenu that presents a player with a highly cust
Allow Builders to add Python-scripted events to their objects (OBS-not for untrusted users!)
- [A voice-operated elevator using events](./A-voice-operated-elevator-using-events)
- [Dialogues using events](./Dialogues-in-events)
- [A voice-operated elevator using events](./A-voice-operated-elevator-using-events.md)
- [Dialogues using events](./Dialogues-in-events.md)
### Menu-builder
A tool for building using an in-game menu instead of the normal build commands. Meant to
be expanded for the needs of your game.
- [Building Menus](./Building-menus)
- [Building Menus](./Building-menus.md)
### Security/Auditing
@ -271,7 +271,7 @@ A folder of basic example objects, commands and scripts.
The Evennia single-player sole quest. Made to be analyzed to learn.
- [The tutorial world introduction](../Howto/Starting/Part1/Tutorial-World-Introduction)
- [The tutorial world introduction](../Howto/Starting/Part1/Tutorial-World-Introduction.md)
----
@ -300,7 +300,7 @@ is maintained by Tehom in its own repository so bug reports should be directed t
- [Arxcode repository on github](https://github.com/Arx-Game/arxcode)
- [Arxcode issue tracker](https://github.com/Arx-Game/arxcode/issues)
- [Arxcode installation help](./Arxcode-installing-help) - this may not always be fully up-to-date with
- [Arxcode installation help](./Arxcode-installing-help.md) - this may not always be fully up-to-date with
latest Evennia. Report your findings!
### Evscaperoom
@ -310,7 +310,7 @@ is maintained by Tehom in its own repository so bug reports should be directed t
A full engine for making multiplayer 'escape-rooms' completely in code.
This is based on the 2019 MUD Game jam winner *Evscaperoom*.
- [contrib/evscaperoom](api:evennia.contrib.evscaperoom) - game engine to make your own escape rooms.
- [contrib/evscaperoom](evennia.contrib.evscaperoom) - game engine to make your own escape rooms.
- [https://demo.evennia.com](https://demo.evennia.com) - a full installation of the original game can
be played by entering the *evscaperoom* exit in the first Limbo room.
- https://github.com/Griatch/evscaperoom - the original game's source code (warning for spoilers if you
@ -319,17 +319,17 @@ This is based on the 2019 MUD Game jam winner *Evscaperoom*.
```toctree::
:hidden:
```{toctree}
:hidden:
./Crafting
../api/evennia.contrib.crafting.crafting
../api/evennia.contrib.crafting.example_recipes
./A-voice-operated-elevator-using-events
./Dialogues-in-events
./Dynamic-In-Game-Map
./Static-In-Game-Map
../Howto/Starting/Part1/Tutorial-World-Introduction
./Building-menus
./Crafting
../api/evennia.contrib.crafting.crafting
../api/evennia.contrib.crafting.example_recipes
./A-voice-operated-elevator-using-events
./Dialogues-in-events
./Dynamic-In-Game-Map
./Static-In-Game-Map
../Howto/Starting/Part1/Tutorial-World-Introduction
./Building-menus
```

16
docs/1.0-dev/_sources/Contribs/Crafting.md.txt
View file

@ -1,14 +1,14 @@
# Crafting system contrib
_Contrib by Griatch 2020_
```versionadded:: 1.0
```{versionadded} 1.0
```
This contrib implements a full Crafting system that can be expanded and modified to fit your game.
- See the [evennia/contrib/crafting/crafting.py API](api:evennia.contrib.crafting.crafting) for installation
- See the [evennia/contrib/crafting/crafting.py API](evennia.contrib.crafting.crafting) for installation
instructrions.
- See the [sword example](api:evennia.contrib.crafting.example_recipes) for an example of how to design
- See the [sword example](evennia.contrib.crafting.example_recipes) for an example of how to design
a crafting tree for crafting a sword from base elements.
From in-game it uses the new `craft` command:
@ -45,7 +45,7 @@ result = craft(caller, "recipename", *inputs)
```
Here, `caller` is the one doing the crafting and `*inputs` is any combination of consumables and/or tool
Objects. The system will identify which is which by the [Tags](../Components/Tags) on them (see below)
Objects. The system will identify which is which by the [Tags](../Components/Tags.md) on them (see below)
The `result` is always a list.
## Adding new recipes
@ -84,7 +84,7 @@ class WoodenPuppetRecipe(CraftingRecipe):
```
This specifies which tags to look for in the inputs. It defines a [Prototype](../Components/Prototypes)
This specifies which tags to look for in the inputs. It defines a [Prototype](../Components/Prototypes.md)
for the recipe to use to spawn the result on the fly (a recipe could spawn more than one result if needed).
Instead of specifying the full prototype-dict, you could also just provide a list of `prototype_key`s to
existing prototypes you have.
@ -93,7 +93,7 @@ After reloading the server, this recipe would now be available to use. To try it
create materials and tools to insert into the recipe.
The recipe analyzes inputs, looking for [Tags](../Components/Tags) with specific tag-categories.
The recipe analyzes inputs, looking for [Tags](../Components/Tags.md) with specific tag-categories.
The tag-category used can be set per-recipe using the (`.consumable_tag_category` and
`.tool_tag_category` respectively). The defaults are `crafting_material` and `crafting_tool`. For
the puppet we need one object with the `wood` tag and another with the `knife` tag:
@ -152,7 +152,7 @@ in `settings.CRAFTING_RECIPE_MODULES`.
Even without modifying more than the class properties, there are a lot of options to set on
the `CraftingRecipe` class. Easiest is to refer to the
[CraftingRecipe api documentation](evennia.contrib.crafting.crafting.html#evennia.contrib.crafting.crafting.CraftingRecipe).
[CraftingRecipe api documentation](evennia.contrib.crafting.crafting.CraftingRecipe).
For example, you can customize the validation-error messages, decide if the ingredients have
to be exactly right, if a failure still consumes the ingredients or not, and much more.
@ -211,7 +211,7 @@ if we succed. We would of course make this a lot more immersive and detailed in
principle you could customize each recipe just the way you want it, but you could also inherit from
a central parent like this to cut down on work.
The [sword recipe example module](api:evennia.contrib.crafting.example_recipes) also shows an example
The [sword recipe example module](evennia.contrib.crafting.example_recipes) also shows an example
of a random skill-check being implemented in a parent and then inherited for multiple use.
## Even more customization

8
docs/1.0-dev/_sources/Contribs/Dynamic-In-Game-Map.md.txt
View file

@ -4,7 +4,7 @@
## Introduction
An often desired feature in a MUD is to show an in-game map to help navigation. The [Static in-game
map](Static-In-Game-Map) tutorial solves this by creating a *static* map, meaning the map is pre-
map](./Static-In-Game-Map.md) tutorial solves this by creating a *static* map, meaning the map is pre-
drawn once and for all - the rooms are then created to match that map. When walking around, parts of
the static map is then cut out and displayed next to the room description.
@ -20,9 +20,9 @@ world to be 'logically' impossible with rooms looping to themselves or exits lea
side of the map. Exits can also be named anything, from "jumping out the window" to "into the fifth
dimension". This tutorial assumes you can only move in the cardinal directions (N, E, S and W).
2. Rooms must be connected and linked together for the map to be generated correctly. Vanilla
Evennia comes with a admin command [@tunnel](../Components/Default-Command-Help#tunnel-cmdtunnel) that allows a
Evennia comes with a admin command [tunnel](evennia.commands.default.building.CmdTunnel) that allows a
user to create rooms in the cardinal directions, but additional work is needed to assure that rooms
are connected. For example, if you `@tunnel east` and then immediately do `@tunnel west` you'll find
are connected. For example, if you `tunnel east` and then immediately do `tunnel west` you'll find
that you have created two completely stand-alone rooms. So care is needed if you want to create a
"logical" layout. In this tutorial we assume you have such a grid of rooms that we can generate the
map from.
@ -361,7 +361,7 @@ looping rooms that will show on your in-game map.
The above example will display the map above the room description. You could also use an
[EvTable](github:evennia.utils.evtable) to place description and map next to each other. Some other
things you can do is to have a [Command](../Components/Commands) that displays with a larger radius, maybe with a
things you can do is to have a [Command](../Components/Commands.md) that displays with a larger radius, maybe with a
legend and other features.
Below is the whole `map.py` for your reference. You need to update your `Room` typeclass (see above)

22
docs/1.0-dev/_sources/Contribs/Static-In-Game-Map.md.txt
View file

@ -4,8 +4,8 @@
## Introduction
This tutorial describes the creation of an in-game map display based on a pre-drawn map. It also
details how to use the [Batch code processor](../Components/Batch-Code-Processor) for advanced building. There is
also the [Dynamic in-game map tutorial](./Dynamic-In-Game-Map) that works in the opposite direction,
details how to use the [Batch code processor](../Components/Batch-Code-Processor.md) for advanced building. There is
also the [Dynamic in-game map tutorial](./Dynamic-In-Game-Map.md) that works in the opposite direction,
by generating a map from an existing grid of rooms.
Evennia does not require its rooms to be positioned in a "logical" way. Your exits could be named
@ -41,7 +41,7 @@ map we designed before.
```
We will henceforth assume your game folder is name named `mygame` and that you haven't modified the
default commands. We will also not be using [Colors](../Concepts/TextTags#colored-text) for our map since they
default commands. We will also not be using [Colors](../Concepts/Colors.md) for our map since they
don't show in the documentation wiki.
## Planning the Map
@ -83,23 +83,23 @@ planning at this stage can solve many problems before they happen.
In this section we will try to create an actual "map" object that an account can pick up and look
at.
Evennia offers a range of [default commands](api:evennia.commands.default#modules) for
[creating objects and rooms in-game](../Howto/Starting/Part1/Building-Quickstart). While readily accessible, these commands are made to do very
Evennia offers a range of [default commands](../Components/Default-Commands.md) for
[creating objects and rooms in-game](../Howto/Starting/Part1/Building-Quickstart.md). While readily accessible, these commands are made to do very
specific, restricted things and will thus not offer as much flexibility to experiment (for an
advanced exception see [in-line functions](../Concepts/TextTags#new-inlinefuncs)). Additionally, entering long
advanced exception see [the FuncParser](../Components/FuncParser.md)). Additionally, entering long
descriptions and properties over and over in the game client can become tedious; especially when
testing and you may want to delete and recreate things over and over.
To overcome this, Evennia offers [batch processors](../Components/Batch-Processors) that work as input-files
To overcome this, Evennia offers [batch processors](../Components/Batch-Processors.md) that work as input-files
created out-of-game. In this tutorial we'll be using the more powerful of the two available batch
processors, the [Batch Code Processor ](../Components/Batch-Code-Processor), called with the `@batchcode` command.
processors, the [Batch Code Processor ](../Components/Batch-Code-Processor.md), called with the `@batchcode` command.
This is a very powerful tool. It allows you to craft Python files to act as blueprints of your
entire game world. These files have access to use Evennia's Python API directly. Batchcode allows
for easy editing and creation in whatever text editor you prefer, avoiding having to manually build
the world line-by-line inside the game.
> Important warning: `@batchcode`'s power is only rivaled by the `@py` command. Batchcode is so
powerful it should be reserved only for the [superuser](../Concepts/Building-Permissions). Think carefully
powerful it should be reserved only for the [superuser](../Concepts/Building-Permissions.md). Think carefully
before you let others (such as `Developer`- level staff) run `@batchcode` on their own - make sure
you are okay with them running *arbitrary Python code* on your server.
@ -412,5 +412,5 @@ easily new game defining features can be added to Evennia.
You can easily build from this tutorial by expanding the map and creating more rooms to explore. Why
not add more features to your game by trying other tutorials: [Add weather to your world](Weather-
Tutorial), [fill your world with NPC's](../Howto/Tutorial-Aggressive-NPCs) or
[implement a combat system](../Howto/Starting/Part3/Turn-based-Combat-System).
Tutorial), [fill your world with NPC's](../Howto/Tutorial-Aggressive-NPCs.md) or
[implement a combat system](../Howto/Starting/Part3/Turn-based-Combat-System.md).

40
docs/1.0-dev/_sources/Contribs/XYZGrid.md.txt
View file

@ -1,6 +1,6 @@
# XYZGrid contrib
```versionadded:: 1.0
```{versionadded} 1.0
```
This optional contrib adds a 'coordinate grid' to Evennia. It allows for
@ -66,7 +66,7 @@ Exits: northeast and east
available for use as prototype-parents when spawning the grid.
4. Run `evennia xyzgrid help` for available options.
5. (Optional): By default, the xyzgrid will only spawn module-based
[prototypes](../Components/Prototypes). This is an optimization and usually makes sense
[prototypes](../Components/Prototypes.md). This is an optimization and usually makes sense
since the grid is entirely defined outside the game anyway. If you want to
also make use of in-game (db-) created prototypes, add
`XYZGRID_USE_DB_PROTOTYPES = True` to settings.
@ -79,11 +79,11 @@ The grid contrib consists of multiple components.
1. The `XYMap` - This class parses modules with special _Map strings_
and _Map legends_ into one Python object. It has helpers for pathfinding and
visual-range handling.
2. The `XYZGrid` - This is a singleton [Script](../Components/Scripts) that
2. The `XYZGrid` - This is a singleton [Script](../Components/Scripts.md) that
stores all `XYMaps` in the game. It is the central point for managing the 'grid'
of the game.
3. `XYZRoom` and `XYZExit`are custom typeclasses that use
[Tags](../Components/Tags)
[Tags](../Components/Tags.md)
to know which X,Y,Z coordinate they are located at. The `XYZGrid` is
abstract until it is used to _spawn_ these database entities into
something you can actually interract with in the game. The `XYZRoom`
@ -102,7 +102,7 @@ After installation, do the following from your command line (where the
$ evennia xyzgrid init
use `evennia xyzgrid help` to see all options)
This will create a new `XYZGrid` [Script](../Components/Scripts) if one didn't already exist.
This will create a new `XYZGrid` [Script](../Components/Scripts.md) if one didn't already exist.
The `evennia xyzgrid` is a custom launch option added only for this contrib.
The xyzgrid-contrib comes with a full grid example. Let's add it:
@ -120,7 +120,7 @@ about each map with the `show` subcommand:
$ evennia xyzgrid show "the small cave"
If you want to peek at how the grid's code, open
[evennia/contrib/xyzgrid/example.py](api:evennia.contrib.xyzgrid.example).
[evennia/contrib/xyzgrid/example.py](evennia.contrib.xyzgrid.example).
(We'll explain the details in later sections).
So far the grid is 'abstract' and has no actual in-game presence. Let's
@ -430,9 +430,9 @@ LEGEND = {
The legend is optional, and any symbol not explicitly given in your legend will
fall back to its value in the default legend [outlined below](#default-legend).
- [MapNode](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapNode)
- [MapNode](evennia.contrib.xyzgrid.xymap_legend.MapNode)
is the base class for all nodes.
- [MapLink](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapLink)
- [MapLink](evennia.contrib.xyzgrid.xymap_legend.MapLink)
is the base class for all links.
As the _Map String_ is parsed, each found symbol is looked up in the legend and
@ -445,7 +445,7 @@ with a full set of map elements that use these properties in various ways
(described in the next section).
Some useful properties of the
[MapNode](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapNode)
[MapNode](evennia.contrib.xyzgrid.xymap_legend.MapNode)
class (see class doc for hook methods):
- `symbol` (str) - The character to parse from the map into this node. By default this
@ -473,7 +473,7 @@ class (see class doc for hook methods):
useful for various reasons, mostly map-transitions).
Some useful properties of the
[MapLink](api:evennia.contrib.xyzgrid.xymap_legend#evennia.contrib.xyzgrid.xymap_legend.MapLink)
[MapLink](evennia.contrib.xyzgrid.xymap_legend.MapLink)
class (see class doc for hook methods):
- `symbol` (str) - The character to parse from the map into this node. This must
@ -551,7 +551,7 @@ actually visualized when displaying the map to players in-game. This could have
colors etc. All classes are found in `evennia.contrib.xyzgrid.xymap_legend` and
their names are included to make it easy to know what to override.
```eval_rst
```{eval-rst}
============= ============== ==== =================== =========================================
symbol display-symbol type class description
============= ============== ==== =================== =========================================
@ -921,11 +921,11 @@ across the map boundary.
### Prototypes
[Prototypes](../Components/Prototypes) are dicts that describe how to _spawn_ a new instance
[Prototypes](../Components/Prototypes.md) are dicts that describe how to _spawn_ a new instance
of an object. Each of the _nodes_ and _links_ above have a default prototype
that allows the `evennia xyzgrid spawn` command to convert them to
a [XYZRoom](api:evennia.contrib.xyzgrid.xyzroom#XYZRoom)
or an [XYZExit](api:evennia.contrib.xyzgrid.xyzroom#XYZExit) respectively.
a [XYZRoom](evennia.contrib.xyzgrid.xyzroom.XYZRoom)
or an [XYZExit](evennia.contrib.xyzgrid.xyzroom.XYZRoom) respectively.
The default prototypes are found in `evennia.contrib.xyzgrid.prototypes` (added
during installation of this contrib), with `prototype_key`s `"xyz_room"` and
@ -1167,7 +1167,7 @@ a location if they know that location's name. Here are some details about
## XYZGrid
The `XYZGrid` is a [Global Script](../Components/Scripts) that holds all `XYMap` objects on
The `XYZGrid` is a [Global Script](../Components/Scripts.md) that holds all `XYMap` objects on
the grid. There should be only one XYZGrid created at any time.
To access the grid in-code, there are several ways:
@ -1216,17 +1216,17 @@ know how to call find the pathfinder though:
- `xymap.get_shortest_path(start_xy, end_xy)`
- `xymap.get_visual_range(xy, dist=2, **kwargs)`
See the [XYMap](api:evennia.contrib.xyzgrid.xymap#XYMap) documentation for
See the [XYMap](xymap) documentation for
details.
## XYZRoom and XYZExit
These are new custom [Typeclasses](../Components/Typeclasses) located in
These are new custom [Typeclasses](../Components/Typeclasses.md) located in
`evennia.contrib.xyzgrid.xyzroom`. They extend the base `DefaultRoom` and
`DefaultExit` to be aware of their `X`, `Y` and `Z` coordinates.
```warning::
```{warning}
You should usually **not** create XYZRooms/Exits manually. They are intended
to be created/deleted based on the layout of the grid. So to add a new room, add
@ -1253,7 +1253,7 @@ Useful (extra) properties on `XYZRoom`, `XYZExit`:
- `xyz_destination` (only for `XYZExits`) - this gives the xyz-coordinate of
the exit's destination.
The coordinates are stored as [Tags](../Components/Tags) where both rooms and exits tag
The coordinates are stored as [Tags](../Components/Tags.md) where both rooms and exits tag
categories `room_x_coordinate`, `room_y_coordinate` and `room_z_coordinate`
while exits use the same in addition to tags for their destination, with tag
categories `exit_dest_x_coordinate`, `exit_dest_y_coordinate` and
@ -1293,7 +1293,7 @@ exit = XYZExit.objects.get_xyz_exit(xyz=(0, 12, 'foo'), xyz_destination=(5, 2, '
You can customize the XYZRoom/Exit by having the grid spawn your own subclasses
of them. To do this you need to override the prototype used to spawn rooms on
the grid. Easiest is to modify the base prototype-parents in settings (see the
[Extending the base prototypes](#extending-the-base-prototypes) section above).
[XYZRoom and XYZExit](#xyzroom-and-xyzexit) section above).
## Working with the grid