From 5df73d5045a291b4f1549754000afe6b6f46ca13 Mon Sep 17 00:00:00 2001 From: Griatch Date: Fri, 23 Jul 2021 00:19:28 +0200 Subject: [PATCH] Add XYZgrid contrib api files, prepare for merge --- CHANGELOG.md | 2 + docs/source/Contribs/Contrib-Overview.md | 97 ++++++++++--------- docs/source/Contribs/XYZGrid.md | 67 ++++++++++--- docs/source/api/evennia.contrib.rst | 1 + .../api/evennia.contrib.xyzgrid.commands.rst | 7 ++ .../api/evennia.contrib.xyzgrid.example.rst | 7 ++ .../api/evennia.contrib.xyzgrid.launchcmd.rst | 7 ++ .../evennia.contrib.xyzgrid.prototypes.rst | 7 ++ docs/source/api/evennia.contrib.xyzgrid.rst | 23 +++++ .../api/evennia.contrib.xyzgrid.tests.rst | 7 ++ .../api/evennia.contrib.xyzgrid.utils.rst | 7 ++ .../api/evennia.contrib.xyzgrid.xymap.rst | 7 ++ .../evennia.contrib.xyzgrid.xymap_legend.rst | 7 ++ .../api/evennia.contrib.xyzgrid.xyzgrid.rst | 7 ++ .../api/evennia.contrib.xyzgrid.xyzroom.rst | 7 ++ docs/source/toc.md | 2 +- evennia/contrib/xyzgrid/launchcmd.py | 72 +++++++------- evennia/contrib/xyzgrid/xymap_legend.py | 4 +- evennia/contrib/xyzgrid/xyzgrid.py | 6 -- evennia/contrib/xyzgrid/xyzroom.py | 8 +- evennia/server/serversession.py | 1 + 21 files changed, 247 insertions(+), 106 deletions(-) create mode 100644 docs/source/api/evennia.contrib.xyzgrid.commands.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.example.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.launchcmd.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.prototypes.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.tests.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.utils.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.xymap.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.xymap_legend.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.xyzgrid.rst create mode 100644 docs/source/api/evennia.contrib.xyzgrid.xyzroom.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d44d97ff2..670de30345 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,8 @@ Up requirements to Django 3.2+ - 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. ### Evennia 0.9.5 (2019-2020) diff --git a/docs/source/Contribs/Contrib-Overview.md b/docs/source/Contribs/Contrib-Overview.md index 77a78fcf29..bd3ec16b3b 100644 --- a/docs/source/Contribs/Contrib-Overview.md +++ b/docs/source/Contribs/Contrib-Overview.md @@ -1,33 +1,33 @@ # Contrib modules -Contribs are found in [evennia/contrib/](api: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. +Contribs are found in [evennia/contrib/](api: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. -## Character-related +## Character-related Contribs related to characters and character displays. -### CharGen +### CharGen *Griatch 2011* A simple Character creator for OOC mode. Meant as a starting point for a more fleshed-out system. -### Clothing +### Clothing *FlutterSprite 2017* A layered clothing system with slots for different types of garments auto-showing in description. -### Health Bar +### Health Bar *Tim Ashley Jenkins 2017* Tool to create colorful bars/meters. -### Multidescer +### Multidescer *Griatch 2016* @@ -39,13 +39,22 @@ Advanced descriptions combined from many separate description components, inspir Contribs modifying locations, movement or helping to creating rooms. -### Extended Room +### XYZGrid + +*Griatch 2021* + +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) + +### Extended Room *Griatch 2012* An expanded Room typeclass with multiple descriptions for time and season as well as details. -### Map Builder +### Map Builder *CloudKeeper 2016* @@ -53,19 +62,19 @@ Build a game area based on a 2D "graphical" unicode map. Supports asymmetric exi - [Static in-game map](./Static-In-Game-Map) -### Simple Door +### Simple Door *Griatch 2014* Example of an exit that can be opened and closed from both sides. -### Slow exit +### Slow exit *Griatch 2014* Custom Exit class that takes different time to pass depending on if you are walking/running etc. -### Wilderness +### Wilderness *titeuf87 2017* @@ -79,7 +88,7 @@ Make infinitely large wilderness areas with dynamically created locations. Contribs supporting roleplay and in-game roleplaying actions. -### Barter system +### Barter system *Griatch 2012* @@ -95,25 +104,25 @@ A full, extendable crafting system. - [Crafting API documentation](api:evennia.contrib.crafting.crafting) - [Example of a sword crafting tree](api:evennia.contrib.crafting.example_recipes) -### Dice +### Dice *Griatch 2012* A fully featured dice rolling system. -### Mail +### Mail *grungies1138 2016* An in-game mail system for communication. -### Puzzles +### Puzzles *Hendher 2019* Combine objects to create new items, adventure-game style -### RP System +### RP System *Griatch 2015* @@ -125,7 +134,7 @@ Full director-style emoting system replacing names with sdescs/recogs. Supports Dynamic obfuscation of emotes when speaking unfamiliar languages. Also obfuscates whispers. -### Turnbattle +### Turnbattle *FlutterSprite 2017* @@ -142,7 +151,7 @@ and includes optional expansions for equipment and combat movement, magic and ra An `@edit` command for modifying objects using a generated menu. Customizable for different games. -### Field Fill +### Field Fill *FlutterSprite 2018* @@ -159,18 +168,18 @@ Allow Builders to add Python-scripted events to their objects (OBS-not for untru ### Menu-builder -A tool for building using an in-game menu instead of the normal build commands. Meant to +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) -### Security/Auditing +### Security/Auditing *Johhny 2018* Log server input/output for debug/security. -### Tree Select +### Tree Select *FlutterSprite 2017* @@ -183,13 +192,13 @@ multi-line string. Contribs meant to be used as part of other code, or as replacements for default settings. -### Color-markups +### Color-markups *Griatch, 2017* Alternative in-game color markups. -### Custom gametime +### Custom gametime *Griatch, vlgeoff 2017* @@ -203,19 +212,19 @@ Implements Evennia's gametime module but for custom game world-specific calendar A variant of the standard login system that requires an email to login rather then just name+password. -#### Menu login +#### Menu login *Griatch 2011, 2019, Vincent-lg 2016* A login system using menus asking for name/password rather than giving them as one command. -### Random String Generator +### Random String Generator *Vincent Le Goff 2017* Simple pseudo-random generator of strings with rules, avoiding repetitions. -### UnixCommand +### UnixCommand *Vincent Le Geoff 2017* @@ -227,19 +236,19 @@ Add commands with UNIX-style syntax. Contribs not meant to be used as-is, but just as examples to learn from. -### GenderSub +### GenderSub *Griatch 2015* Simple example (only) of storing gender on a character and access it in an emote with a custom marker. -### Talking NPC +### Talking NPC *Griatch 2011* A talking NPC object that offers a menu-driven conversation tree. -### Tutorial examples +### Tutorial examples *Griatch 2011, 2015* @@ -259,12 +268,12 @@ The Evennia single-player sole quest. Made to be analyzed to learn. Full game-dir replacement systems. -### Ainneve +### Ainneve *Evennia community 2015-?* -This is a community attempt to make an Evennia 'example game' using good practices. It is also a good -place to jump in if you want to help in another project rather than run it alone. Development of this +This is a community attempt to make an Evennia 'example game' using good practices. It is also a good +place to jump in if you want to help in another project rather than run it alone. Development of this has stalled a bit so we are looking for enthusiastic people to lead the charge. - [evennia/ainneve repository](https://github.com/evennia/ainneve) @@ -274,26 +283,26 @@ has stalled a bit so we are looking for enthusiastic people to lead the charge. *Tehom 2019* -Open source code release of the popular Evennia-based [Arx, after the reckoning](https://play.arxgame.org/). -This is a fantasy game with a focus on roleplay and code-supported political intrigue. This code-release +Open source code release of the popular Evennia-based [Arx, after the reckoning](https://play.arxgame.org/). +This is a fantasy game with a focus on roleplay and code-supported political intrigue. This code-release is maintained by Tehom in its own repository so bug reports should be directed there. - [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) - this may not always be fully up-to-date with latest Evennia. Report your findings! - -### Evscaperoom + +### Evscaperoom *Griatch 2019* -A full engine for making multiplayer 'escape-rooms' completely in code. -This is based on the 2019 MUD Game jam winner *Evscaperoom*. +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. -- [https://demo.evennia.com](https://demo.evennia.com) - a full installation of the original game can +- [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 +- https://github.com/Griatch/evscaperoom - the original game's source code (warning for spoilers if you want to solve the puzzles and mystery yourself). @@ -303,7 +312,7 @@ This is based on the 2019 MUD Game jam winner *Evscaperoom*. :hidden: ./Crafting - ../api/evennia.contrib.crafting.crafting + ../api/evennia.contrib.crafting.crafting ../api/evennia.contrib.crafting.example_recipes ./A-voice-operated-elevator-using-events ./Dialogues-in-events diff --git a/docs/source/Contribs/XYZGrid.md b/docs/source/Contribs/XYZGrid.md index c1b4bc73f0..2f907d571b 100644 --- a/docs/source/Contribs/XYZGrid.md +++ b/docs/source/Contribs/XYZGrid.md @@ -1,4 +1,4 @@ -# XYZGrid contribution +# XYZGrid contrib ```versionadded:: 1.0 ``` @@ -7,8 +7,10 @@ This optional contrib adds a 'coordinate grid' to Evennia. It allows for defining the grid as simple ascii maps that are then spawned into rooms that are aware of their X, Y, Z coordinates. The system includes shortest-path pathfinding, auto-stepping and in-game map visualization (with visibility -range). +range). Grid-management is done outside of the game using a new evennia-launcher +option. + ``` #-#-#-# # @@ -36,8 +38,6 @@ Exits: northeast and east ``` - - ## Installation 1. Import and add the `evennia.contrib.commands.XYZGridCmdSet` to the @@ -406,10 +406,10 @@ optional, and any symbol not explicitly given in your legend will fall back to its value in the default legend found in `evennia.contrib.xyzgrid.xymap_legend`). -- [MapNode](api:evennia.contrib.xyzgrid.xymap_legend#MapNode) is the base - class for all nodes. -- [MapLink](api:evennia.contrib.xyzgrid.xymap_legend#MapLink) is the base - class for all links. +- [MapNode](api:evennia.contrib.xyzgrid.xymap_legend#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) + is the base class for all links. As the _Map String_ is parsed, each found symbol is looked up in the legend and initialized into the corresponding MapNode/Link instance. @@ -421,7 +421,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#MapNode) +[MapNode](api:evennia.contrib.xyzgrid.xymap_legend#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 @@ -449,7 +449,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#MapLink) +[MapLink](api:evennia.contrib.xyzgrid.xymap_legend#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 @@ -1207,11 +1207,50 @@ Useful (extra) properties on `XYZRoom`, `XYZExit`: `XYZRoom`, to display the map. The `options` given in `XYMAP_DATA` will appear as `**kwargs` to this method and if you override this you can customize the map display in depth. +- `xyz_destination` (only for `XYZExits`) - this gives the xyz-coordinate of + the exit's destination. -To use your own overridden version of `XYZRoom/Exit`, you need to override -the prototype used to spawn rooms on the grid. You can modify the base prototype -parents in settings (see the [Extending the base prototypes](#extending-the-base-prototypes) -section above). +The coordinates are stored as [Tags](../Components/Tags) 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 +`exit_dest_z_coordinate`. + +The make it easier to query the database by coordinates, each typeclass offers +custom manager methods. The filter methods allow for `'*'` as a wildcard. + +```python + +# find a list of all rooms in map foo +rooms = XYZRoom.objects.filter_xyz(('*', '*', 'foo')) + +# find list of all rooms with name "Tunnel" on map foo +rooms = XYZRoom.objects.filter_xyz(('*', '*', 'foo'), db_key="Tunnel") + +# find all rooms in the first column of map footer +rooms = XYZRoom.objects.filter_xyz((0, '*', 'foo')) + +# find exactly one room at given coordinate (no wildcards allowed) +room = XYZRoom.objects.get_xyz((13, 2, foo)) + +# find all exits in a given room +exits = XYZExit.objects.filter_xyz((10, 4, foo)) + +# find all exits pointing to a specific destination (from all maps) +exits = XYZExit.objects.filter_xyz_exit(xyz_destination=(13,5,'bar')) + +# find exits from a room to anywhere on another map +exits = XYZExit.objects.filter_xyz_exit(xyz=(1, 5, 'foo'), xyz_destination=('*', '*', 'bar')) + +# find exactly one exit to specific destination (no wildcards allowed) +exit = XYZExit.objects.get_xyz_exit(xyz=(0, 12, 'foo'), xyz_destination=(5, 2, 'foo')) + +``` + +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). ## Working with the grid diff --git a/docs/source/api/evennia.contrib.rst b/docs/source/api/evennia.contrib.rst index 86d18b1f21..1fe1ccd29f 100644 --- a/docs/source/api/evennia.contrib.rst +++ b/docs/source/api/evennia.contrib.rst @@ -52,3 +52,4 @@ evennia.contrib evennia.contrib.turnbattle evennia.contrib.tutorial_examples evennia.contrib.tutorial_world + evennia.contrib.xyzgrid diff --git a/docs/source/api/evennia.contrib.xyzgrid.commands.rst b/docs/source/api/evennia.contrib.xyzgrid.commands.rst new file mode 100644 index 0000000000..57b7674a68 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.commands.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.commands +======================================= + +.. automodule:: evennia.contrib.xyzgrid.commands + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.example.rst b/docs/source/api/evennia.contrib.xyzgrid.example.rst new file mode 100644 index 0000000000..10747ba83d --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.example.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.example +====================================== + +.. automodule:: evennia.contrib.xyzgrid.example + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.launchcmd.rst b/docs/source/api/evennia.contrib.xyzgrid.launchcmd.rst new file mode 100644 index 0000000000..fc973d6919 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.launchcmd.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.launchcmd +======================================== + +.. automodule:: evennia.contrib.xyzgrid.launchcmd + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.prototypes.rst b/docs/source/api/evennia.contrib.xyzgrid.prototypes.rst new file mode 100644 index 0000000000..ab7a51e9e5 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.prototypes.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.prototypes +========================================= + +.. automodule:: evennia.contrib.xyzgrid.prototypes + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.rst b/docs/source/api/evennia.contrib.xyzgrid.rst new file mode 100644 index 0000000000..d70ed6bac5 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.rst @@ -0,0 +1,23 @@ +evennia.contrib.xyzgrid +=============================== + +.. automodule:: evennia.contrib.xyzgrid + :members: + :undoc-members: + :show-inheritance: + + + +.. toctree:: + :maxdepth: 6 + + evennia.contrib.xyzgrid.commands + evennia.contrib.xyzgrid.example + evennia.contrib.xyzgrid.launchcmd + evennia.contrib.xyzgrid.prototypes + evennia.contrib.xyzgrid.tests + evennia.contrib.xyzgrid.utils + evennia.contrib.xyzgrid.xymap + evennia.contrib.xyzgrid.xymap_legend + evennia.contrib.xyzgrid.xyzgrid + evennia.contrib.xyzgrid.xyzroom diff --git a/docs/source/api/evennia.contrib.xyzgrid.tests.rst b/docs/source/api/evennia.contrib.xyzgrid.tests.rst new file mode 100644 index 0000000000..59a50fae20 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.tests.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.tests +==================================== + +.. automodule:: evennia.contrib.xyzgrid.tests + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.utils.rst b/docs/source/api/evennia.contrib.xyzgrid.utils.rst new file mode 100644 index 0000000000..433210f782 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.utils.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.utils +==================================== + +.. automodule:: evennia.contrib.xyzgrid.utils + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.xymap.rst b/docs/source/api/evennia.contrib.xyzgrid.xymap.rst new file mode 100644 index 0000000000..ecb16f40f8 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.xymap.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.xymap +==================================== + +.. automodule:: evennia.contrib.xyzgrid.xymap + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.xymap_legend.rst b/docs/source/api/evennia.contrib.xyzgrid.xymap_legend.rst new file mode 100644 index 0000000000..0ace0ff162 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.xymap_legend.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.xymap\_legend +============================================ + +.. automodule:: evennia.contrib.xyzgrid.xymap_legend + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.xyzgrid.rst b/docs/source/api/evennia.contrib.xyzgrid.xyzgrid.rst new file mode 100644 index 0000000000..cfdfc8c5f4 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.xyzgrid.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.xyzgrid +====================================== + +.. automodule:: evennia.contrib.xyzgrid.xyzgrid + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/evennia.contrib.xyzgrid.xyzroom.rst b/docs/source/api/evennia.contrib.xyzgrid.xyzroom.rst new file mode 100644 index 0000000000..a74e882393 --- /dev/null +++ b/docs/source/api/evennia.contrib.xyzgrid.xyzroom.rst @@ -0,0 +1,7 @@ +evennia.contrib.xyzgrid.xyzroom +====================================== + +.. automodule:: evennia.contrib.xyzgrid.xyzroom + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/toc.md b/docs/source/toc.md index 8ed4fb7346..51f74ca686 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -1,5 +1,5 @@ # Toc - +- [API root](api/evennia-api.rst) - [Coding/Coding Introduction](Coding/Coding-Introduction) - [Coding/Coding Overview](Coding/Coding-Overview) - [Coding/Continuous Integration](Coding/Continuous-Integration) diff --git a/evennia/contrib/xyzgrid/launchcmd.py b/evennia/contrib/xyzgrid/launchcmd.py index e55e4875f6..6d35da3ed6 100644 --- a/evennia/contrib/xyzgrid/launchcmd.py +++ b/evennia/contrib/xyzgrid/launchcmd.py @@ -22,8 +22,8 @@ from evennia.utils import ansi from evennia.contrib.xyzgrid.xyzgrid import get_xyzgrid _HELP_SHORT = """ -evennia xyzgrid help|list|init|add|spawn|initpath|delete [] -Manages the XYZ grid. Use 'xyzgrid help