Cleaned up Coding and style guides, improved contribs

docs/source/Contribs/Contrib-Clothing.md

@@ -36,19 +36,21 @@ And then add `ClothedCharacterCmdSet` in your character set in
 
 ```python
 
-from evennia.contrib.game_systems.clothing import ClothedCharacterCmdSet <--
+from evennia.contrib.game_systems.clothing import ClothedCharacterCmdSet # <--
 
 class CharacterCmdSet(default_cmds.CharacterCmdSet):
      # ...
      at_cmdset_creation(self):
 
          super().at_cmdset_creation()
-         ...
+         # ...
          self.add(ClothedCharacterCmdSet)    # <--
 
 ```
 
-From here, you can use the default builder commands to create clothes
+## Usage
+
+Once installed, you can use the default builder commands to create clothes
 with which to test the system:
 
     create a pretty shirt : evennia.contrib.game_systems.clothing.Clothing
@@ -87,6 +89,51 @@ can cover any garment with almost any other, for example - but it
 can easily be made more restrictive, and can even be tied into a
 system for armor or other equipment.
 
+## Configuration
+
+The contrib has several optional configurations which you can define in your `settings.py`
+Here are the settings and their default values.
+
+```python
+# Maximum character length of 'wear style' strings, or None for unlimited.
+CLOTHING_WEARSTYLE_MAXLENGTH = 50
+
+# The order in which clothing types appear on the description.
+# Untyped clothing or clothing with a type not in this list goes last.
+CLOTHING_TYPE_ORDERED = [
+        "hat",
+        "jewelry",
+        "top",
+        "undershirt",
+        "gloves",
+        "fullbody",
+        "bottom",
+        "underpants",
+        "socks",
+        "shoes",
+        "accessory",
+    ]
+
+# The maximum number of clothing items that can be worn, or None for unlimited.
+CLOTHING_OVERALL_LIMIT = 20
+
+# The maximum number for specific clothing types that can be worn.
+# If the clothing item has no type or is not specified here, the only maximum is the overall limit.
+CLOTHING_TYPE_LIMIT = {"hat": 1, "gloves": 1, "socks": 1, "shoes": 1}
+
+# What types of clothes will automatically cover what other types of clothes when worn.
+# Note that clothing only gets auto-covered if it's already being worn. It's perfectly possible
+# to have your underpants showing if you put them on after your pants!
+CLOTHING_TYPE_AUTOCOVER = {
+        "top": ["undershirt"],
+        "bottom": ["underpants"],
+        "fullbody": ["undershirt", "underpants"],
+        "shoes": ["socks"],
+    }
+
+# Any types of clothes that can't be used to cover other clothes at all.
+CLOTHING_TYPE_CANT_COVER_WITH = ["jewelry"]
+```
 
 
 ----

docs/source/Contribs/Contrib-Wilderness.md

@@ -5,7 +5,7 @@ Contribution by titeuf87, 2017
 This contrib provides a wilderness map without actually creating a large number
 of rooms - as you move, you instead end up back in the same room but its description 
 changes. This means you can make huge areas with little database use as
-long as the rooms are relatively similar (name/desc changing).
+long as the rooms are relatively similar (e.g. only the names/descs changing).
 
 ## Installation
 
@@ -29,6 +29,9 @@ All coordinates used by the wilderness map are in the format of `(x, y)`
 tuples. x goes from left to right and y goes from bottom to top. So `(0, 0)`
 is the bottom left corner of the map.
 
+> You can also add a wilderness by defining a WildernessScript in your GLOBAL_SCRIPT
+> settings. If you do, make sure define the map provider.
+
 ## Customisation
 
 The defaults, while useable, are meant to be customised. When creating a
@@ -37,9 +40,14 @@ python object that is smart enough to create the map.
 
 The default provider, `WildernessMapProvider`, just creates a grid area that
 is unlimited in size.
-This `WildernessMapProvider` can be subclassed to create more interesting
+
+`WildernessMapProvider` can be subclassed to create more interesting
 maps and also to customize the room/exit typeclass used.
 
+The `WildernessScript` also has an optional `preserve_items` property, which
+when set to `True` will not recycle rooms that contain any objects. By default,
+a wilderness room is recycled whenever there are no players left in it.
+
 There is also no command that allows players to enter the wilderness. This
 still needs to be added: it can be a command or an exit, depending on your
 needs.
@@ -94,7 +102,7 @@ class PyramidMapProvider(wilderness.WildernessMapProvider):
         desc = "This is a room in the pyramid."
         if y == 3 :
             desc = "You can see far and wide from the top of the pyramid."
-        room.db.desc = desc
+        room.ndb.desc = desc
 ```
 
 Now we can use our new pyramid-shaped wilderness map. From inside Evennia we
@@ -105,12 +113,16 @@ create a new wilderness (with the name "default") but using our new map provider
 
 ## Implementation details
 
-When a character moves into the wilderness, they get their own room. If they
-move, instead of moving the character, the room changes to match the new
-coordinates.  If a character meets another character in the wilderness, then
-their room merges. When one of the character leaves again, they each get their
-own separate rooms.  Rooms are created as needed. Unneeded rooms are stored away
-to avoid the overhead cost of creating new rooms again in the future.
+When a character moves into the wilderness, they get their own room. If
+they move, instead of moving the character, the room changes to match the
+new coordinates.
+
+If a character meets another character in the wilderness, then their room
+merges. When one of the character leaves again, they each get their own
+separate rooms.
+
+Rooms are created as needed. Unneeded rooms are stored away to avoid the
+overhead cost of creating new rooms again in the future.
 
 
 ----

docs/source/Contribs/Contribs-Guidelines.md

@@ -0,0 +1,84 @@
+# Guidelines for Evennia contribs
+
+Evennia has a [contrib](./Contribs-Overview.md) directory which contains optional, community-shared code organized by category. Anyone is welcome to contribute.
+
+## What is suitable for a contrib?
+
+- In general, you can contribute anything that you think may be useful to another developer. Unlike the 'core' Evennia, contribs can also be highly game-type-specific.
+- Very small or incomplete snippets of code (e.g. meant to paste into some other code) are better shared as a post in the [Community Contribs & Snippets](https://github.com/evennia/evennia/discussions/2488) discussion forum category.
+- If your code is intended *primarily* as an example or to show a concept/principle rather than a working system, consider if it may be better to instead [contribute to the documentation](../Contributing-Docs.md) by writing a new tutorial or howto.
+- If possible, try to make your contribution as genre-agnostic as possible and assume
+  your code will be applied to a very different game than you had in mind when creating it.
+- The contribution should preferably work in isolation from other contribs (only make use of core Evennia) so it can easily be dropped into use. If it does depend on other contribs or third-party modules, these must be clearly documented and part of the installation instructions.
+- If you are unsure about if your contrib idea is suitable or sound, *ask in discussions or chat before putting any work into it*. We are, for example, unlikely to accept contribs that require large modifications of the game directory structure.
+
+## Layout of a contrib
+
+- The contrib must be contained only within a single folder under one of the contrib categories below.  Ask if you are unsure which category fits best for your contrib.
+
+|  |  | 
+| --- | --- | 
+| `base_systems/` | _Systems that are not necessarily tied to a specific in-game mechanic but which are useful for the game as a whole. Examples include login systems, new command syntaxes, and build helpers._ |
+| `full_systems/` | _‘Complete’ game engines that can be used directly to start creating content without no further additions (unless you want to)._ |
+| `game_systems/` | _In-game gameplay systems like crafting, mail, combat and more. Each system is meant to be adopted piecemeal and adopted for your game. This does not include roleplaying-specific systems, those are found in the `rpg` category._ |
+| `grid/` | _Systems related to the game world’s topology and structure. Contribs related to rooms, exits and map building._ |
+| `rpg/` | _Systems specifically related to roleplaying and rule implementation like character traits, dice rolling and emoting._ | 
+| `tutorials/` | _Helper resources specifically meant to teach a development concept or to exemplify an Evennia system. Any extra resources tied to documentation tutorials are found here. Also the home of the Tutorial-World and Evadventure demo codes._ | 
+| `tools/` | _Miscellaneous tools for manipulating text, security auditing, and more._|
+
+
+- The folder (package) should be on the following form:
+
+    ```
+    evennia/
+       contrib/ 
+           category/    # rpg/, game_systems/ etc
+               mycontribname/
+                   __init__.py
+                   README.md
+                   module1.py
+                   module2.py
+                   ...
+                   tests.py
+    ```
+
+    It's often a good idea to import useful resources in `__init__.py` to make it easier to import them.
+- Your code should abide by the [Evennia Style Guide](../Coding/Evennia-Code-Style.md). Write it to be easy to read.
+- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically.
+-  The `README.md` file will be parsed and converted into a document linked from [the contrib overview page](./Contribs-Overview.md). It needs to be on the following form:
+
+    ```markdown
+    # MyContribName
+
+    Contribution by <yourname>, <year>
+
+    A paragraph (can be multi-line)
+    summarizing the contrib (required)
+
+    Optional other text
+
+    ## Installation
+
+    Detailed installation instructions for using the contrib (required)
+
+    ## Usage
+
+    ## Examples
+
+    etc.
+
+    ```
+
+> The credit and first paragraph-summary will be automatically included on the Contrib overview page index for each contribution, so it needs to be just on this form.
+
+
+## Submitting a contrib
+
+```{sidebar} Not all PRs can be accepted
+While most PRs get merged, this is not guaranteed: Merging a contrib means the Evennia project takes on the responsibility of maintaining and supporting the new code. For various reasons this may be deemed unfeasible. 
+
+If your code were to *not* be accepted for some reason, we can still link it from our links page; it can also be posted in our discussion forum.
+```
+- A contrib must always be presented [as a pull request](../Coding/Version-Control.md#contributing-to-evennia) (PR).
+- PRs are reviewed so don't be surprised (or disheartened) if you are asked to modify or change your code before it can be merged. Your code can end up going through several iterations before it is accepted.
+- To make the licensing situation clear we assume all contributions are released with the same [license as Evennia](../Licensing.md). If this is not possible for some reason, talk to us and we'll handle it on a case-by-case basis. 

docs/source/Contribs/Contribs-Overview.md

@@ -18,7 +18,7 @@ Each contrib contains installation instructions for how to integrate it
 with your other code. If you want to tweak the code of a contrib, just
 copy its entire folder to your game directory and modify/use it from there.
 
-If you want to contribute yourself, see [here](../Contributing.md)!
+If you want to add a contrib, see [the contrib guidelines](./Contribs-Guidelines.md)!
 
 [forum]: https://github.com/evennia/evennia/discussions/categories/community-contribs-snippets
 
@@ -48,6 +48,11 @@ _Systems that are not necessarily tied to a specific
 in-game mechanic but which are useful for the game as a whole. Examples include
 login systems, new command syntaxes, and build helpers._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1
 
@@ -204,6 +209,11 @@ library under the hood.
 _'Complete' game engines that can be used directly to start creating content
 without no further additions (unless you want to)._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1
 
@@ -235,6 +245,11 @@ Each system is meant to be adopted piecemeal and adopted for your game.
 This does not include roleplaying-specific systems, those are found in
 the `rpg` category._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1
 
@@ -382,6 +397,11 @@ the participants until the fight ends.
 _Systems related to the game world's topology and structure. Contribs related
 to rooms, exits and map building._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1
 
@@ -463,7 +483,7 @@ _Contribution by titeuf87, 2017_
 This contrib provides a wilderness map without actually creating a large number
 of rooms - as you move, you instead end up back in the same room but its description 
 changes. This means you can make huge areas with little database use as
-long as the rooms are relatively similar (name/desc changing).
+long as the rooms are relatively similar (e.g. only the names/descs changing).
 
 [Read the documentation](./Contrib-Wilderness.md) - [Browse the Code](evennia.contrib.grid.wilderness)
 
@@ -492,6 +512,11 @@ current location (useful for displaying the grid as an in-game, updating map).
 _Systems specifically related to roleplaying
 and rule implementation like character traits, dice rolling and emoting._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1
 
@@ -593,6 +618,11 @@ to exemplify an Evennia system. Any extra resources tied to documentation
 tutorials are found here. Also the home of the Tutorial-World and Evadventure
 demo codes._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1
 
@@ -699,6 +729,11 @@ is a great way to start learning the system.
 
 _Miscellaneous, tools for manipulating text, security auditing, and more._
 
+
+```{toctree}
+:hidden:
+Contribs-Guidelines.md
+```
 ```{toctree}
 :maxdepth: 1