From 696f904d63a9e3bd21a350abcae8343ae26f5fa4 Mon Sep 17 00:00:00 2001 From: Griatch Date: Mon, 3 Oct 2022 19:42:51 +0200 Subject: [PATCH] Update docs --- .../Contribs/Contrib-Character-Creator.md | 125 ++++++++++++++++++ docs/source/Contribs/Contrib-Crafting.md | 2 +- .../Contribs/Contrib-Ingame-Map-Display.md | 57 ++++++++ ...d.ingame_map_display.ingame_map_display.md | 10 ++ ...evennia.contrib.grid.ingame_map_display.md | 18 +++ ...a.contrib.grid.ingame_map_display.tests.md | 10 ++ docs/source/api/evennia.contrib.grid.md | 1 + ...nia.contrib.tutorials.evadventure.tests.md | 1 + ...utorials.evadventure.tests.test_chargen.md | 10 ++ 9 files changed, 233 insertions(+), 1 deletion(-) create mode 100644 docs/source/Contribs/Contrib-Character-Creator.md create mode 100644 docs/source/Contribs/Contrib-Ingame-Map-Display.md create mode 100644 docs/source/api/evennia.contrib.grid.ingame_map_display.ingame_map_display.md create mode 100644 docs/source/api/evennia.contrib.grid.ingame_map_display.md create mode 100644 docs/source/api/evennia.contrib.grid.ingame_map_display.tests.md create mode 100644 docs/source/api/evennia.contrib.tutorials.evadventure.tests.test_chargen.md diff --git a/docs/source/Contribs/Contrib-Character-Creator.md b/docs/source/Contribs/Contrib-Character-Creator.md new file mode 100644 index 0000000000..d93eb8768c --- /dev/null +++ b/docs/source/Contribs/Contrib-Character-Creator.md @@ -0,0 +1,125 @@ +# Character Creator contrib + +Commands for managing and initiating an in-game character-creation menu. + +Contribution by InspectorCaracal, 2022 + +## Installation + +In your game folder `commands/default_cmdsets.py`, import and add +`ContribCmdCharCreate` to your `AccountCmdSet`. + +Example: +```python +from evennia.contrib.rpg.character_creator.character_creator import ContribCmdCharCreate + +class AccountCmdSet(default_cmds.AccountCmdSet): + + def at_cmdset_creation(self): + super().at_cmdset_creation() + self.add(ContribCmdCharCreate) +``` + +In your game folder `typeclasses/accounts.py`, import and inherit from `ContribChargenAccount` +on your Account class. + +(Alternatively, you can copy the `at_look` method directly into your own class.) + +### Example: + +```python +from evennia.contrib.rpg.character_creator.character_creator import ContribChargenAccount + +class Account(ContribChargenAccount): + # your Account class code +``` + +In your settings file `server/conf/settings.py`, add the following settings: + +```python +AUTO_CREATE_CHARACTER_WITH_ACCOUNT = False +AUTO_PUPPET_ON_LOGIN = False +``` + +(If you want to allow players to create more than one character, you can +customize that with the setting `MAX_NR_CHARACTERS`.) + +By default, the new `charcreate` command will reference the example menu +provided by the contrib, so you can test it out before building your own menu. +You can reference +[the example menu here](github:develop/evennia/contrib/rpg/character_creator/example_menu.py) for +ideas on how to build your own. + +Once you have your own menu, just add it to your settings to use it. e.g. if your menu is in +`mygame/word/chargen_menu.py`, you'd add the following to your settings file: + +```python +CHARGEN_MENU = "world.chargen_menu" +``` + +## Usage + +### The EvMenu + +In order to use the contrib, you will need to create your own chargen EvMenu. +The included `example_menu.py` gives a number of useful menu node techniques +with basic attribute examples for you to reference. It can be run as-is as a +tutorial for yourself/your devs, or used as base for your own menu. + +The example menu includes code, tips, and instructions for the following types +of decision nodes: + +#### Informational Pages + +A small set of nodes that let you page through information on different choices before committing to one. + +#### Option Categories + +A pair of nodes which let you divide an arbitrary number of options into separate categories. + +The base node has a list of categories as the options, and the child node displays the actual character choices. + +#### Multiple Choice + +Allows players to select and deselect options from the list in order to choose more than one. + +#### Starting Objects + +Allows players to choose from a selection of starting objects, which are then created on chargen completion. + +#### Choosing a Name + +The contrib assumes the player will choose their name during character creation, +so the necessary code for doing so is of course included! + + +### `charcreate` command + +The contrib overrides the character creation command - `charcreate` - to use a +character creator menu, as well as supporting exiting/resuming the process. In +addition, unlike the core command, it's designed for the character name to be +chosen later on via the menu, so it won't parse any arguments passed to it. + +### Changes to `Account.at_look` + +The contrib version works mostly the same as core evennia, but adds an +additional check to recognize an in-progress character. If you've modified your +own `at_look` hook, it's an easy addition to make: just add this section to the +playable character list loop. + +```python + for char in characters: + # contrib code starts here + if char.db.chargen_step: + # currently in-progress character; don't display placeholder names + result.append("\n - |Yin progress|n (|wcharcreate|n to continue)") + continue + # the rest of your code continues here +``` + + + +---- + +This document page is generated from `evennia/contrib/rpg/character_creator/README.md`. Changes to this +file will be overwritten, so edit that file rather than this one. diff --git a/docs/source/Contribs/Contrib-Crafting.md b/docs/source/Contribs/Contrib-Crafting.md index 95e9dadcb4..d7754b8093 100644 --- a/docs/source/Contribs/Contrib-Crafting.md +++ b/docs/source/Contribs/Contrib-Crafting.md @@ -200,7 +200,7 @@ in-game command: In code we would do ```python -from evennia.contrub.crafting.crafting import craft +from evennia.contrib.crafting.crafting import craft puppet = craft(crafter, "wooden puppet", knife, wood) ``` diff --git a/docs/source/Contribs/Contrib-Ingame-Map-Display.md b/docs/source/Contribs/Contrib-Ingame-Map-Display.md new file mode 100644 index 0000000000..905203c864 --- /dev/null +++ b/docs/source/Contribs/Contrib-Ingame-Map-Display.md @@ -0,0 +1,57 @@ +# Basic Map + +Contribution - helpme 2022 + +This adds an ascii `map` to a given room which can be viewed with the `map` command. +You can easily alter it to add special characters, room colors etc. The map shown is +dynamically generated on use, and supports all compass directions and up/down. Other +directions are ignored. + +If you don't expect the map to be updated frequently, you could choose to save the +calculated map as a .ndb value on the room and render that instead of running mapping +calculations anew each time. + +## Installation: + +Adding the `MapDisplayCmdSet` to the default character cmdset will add the `map` command. + +Specifically, in `mygame/commands/default_cmdsets.py`: + +```python +... +from evennia.contrib.grid.ingame_map_display import MapDisplayCmdSet # <--- + +class CharacterCmdset(default_cmds.Character_CmdSet): + ... + def at_cmdset_creation(self): + ... + self.add(MapDisplayCmdSet) # <--- + +``` + +Then `reload` to make the new commands available. + +## Settings: + +In order to change your default map size, you can add to `mygame/server/settings.py`: + +```python +BASIC_MAP_SIZE = 5 # This changes the default map width/height. + +``` + +## Features: + +### ASCII map (and evennia supports UTF-8 characters and even emojis) + +This produces an ASCII map for players of configurable size. + +### New command + +- `CmdMap` - view the map + + +---- + +This document page is generated from `evennia/contrib/grid/ingame_map_display/README.md`. Changes to this +file will be overwritten, so edit that file rather than this one. diff --git a/docs/source/api/evennia.contrib.grid.ingame_map_display.ingame_map_display.md b/docs/source/api/evennia.contrib.grid.ingame_map_display.ingame_map_display.md new file mode 100644 index 0000000000..24af76bca2 --- /dev/null +++ b/docs/source/api/evennia.contrib.grid.ingame_map_display.ingame_map_display.md @@ -0,0 +1,10 @@ +```{eval-rst} +evennia.contrib.grid.ingame\_map\_display.ingame\_map\_display +===================================================================== + +.. automodule:: evennia.contrib.grid.ingame_map_display.ingame_map_display + :members: + :undoc-members: + :show-inheritance: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.grid.ingame_map_display.md b/docs/source/api/evennia.contrib.grid.ingame_map_display.md new file mode 100644 index 0000000000..d90d389c2c --- /dev/null +++ b/docs/source/api/evennia.contrib.grid.ingame_map_display.md @@ -0,0 +1,18 @@ +```{eval-rst} +evennia.contrib.grid.ingame\_map\_display +================================================= + +.. automodule:: evennia.contrib.grid.ingame_map_display + :members: + :undoc-members: + :show-inheritance: + + + +.. toctree:: + :maxdepth: 6 + + evennia.contrib.grid.ingame_map_display.ingame_map_display + evennia.contrib.grid.ingame_map_display.tests + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.grid.ingame_map_display.tests.md b/docs/source/api/evennia.contrib.grid.ingame_map_display.tests.md new file mode 100644 index 0000000000..f301581fc4 --- /dev/null +++ b/docs/source/api/evennia.contrib.grid.ingame_map_display.tests.md @@ -0,0 +1,10 @@ +```{eval-rst} +evennia.contrib.grid.ingame\_map\_display.tests +====================================================== + +.. automodule:: evennia.contrib.grid.ingame_map_display.tests + :members: + :undoc-members: + :show-inheritance: + +``` \ No newline at end of file diff --git a/docs/source/api/evennia.contrib.grid.md b/docs/source/api/evennia.contrib.grid.md index 2000a6de80..a0bab4c7fc 100644 --- a/docs/source/api/evennia.contrib.grid.md +++ b/docs/source/api/evennia.contrib.grid.md @@ -12,6 +12,7 @@ evennia.contrib.grid :maxdepth: 6 evennia.contrib.grid.extended_room + evennia.contrib.grid.ingame_map_display evennia.contrib.grid.mapbuilder evennia.contrib.grid.simpledoor evennia.contrib.grid.slow_exit diff --git a/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md b/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md index 7521957b62..3507cac214 100644 --- a/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md +++ b/docs/source/api/evennia.contrib.tutorials.evadventure.tests.md @@ -14,6 +14,7 @@ evennia.contrib.tutorials.evadventure.tests evennia.contrib.tutorials.evadventure.tests.mixins evennia.contrib.tutorials.evadventure.tests.test_characters + evennia.contrib.tutorials.evadventure.tests.test_chargen evennia.contrib.tutorials.evadventure.tests.test_combat evennia.contrib.tutorials.evadventure.tests.test_commands evennia.contrib.tutorials.evadventure.tests.test_dungeon diff --git a/docs/source/api/evennia.contrib.tutorials.evadventure.tests.test_chargen.md b/docs/source/api/evennia.contrib.tutorials.evadventure.tests.test_chargen.md new file mode 100644 index 0000000000..c7f7b274db --- /dev/null +++ b/docs/source/api/evennia.contrib.tutorials.evadventure.tests.test_chargen.md @@ -0,0 +1,10 @@ +```{eval-rst} +evennia.contrib.tutorials.evadventure.tests.test\_chargen +================================================================ + +.. automodule:: evennia.contrib.tutorials.evadventure.tests.test_chargen + :members: + :undoc-members: + :show-inheritance: + +``` \ No newline at end of file