diff --git a/docs/source/Contributing-Docs.md b/docs/source/Contributing-Docs.md index bcaa5ace95..a43b33317c 100644 --- a/docs/source/Contributing-Docs.md +++ b/docs/source/Contributing-Docs.md @@ -36,12 +36,13 @@ primarily be accessed as link refs (e.g. `Component/Account`) - `source/Howtos/` holds docs that describe how to achieve a specific goal, effect or result in Evennia. This is often on a tutorial or FAQ form and will refer to the rest of the documentation for further reading. - - `source/Howtos/StartingTutorial/` holds all documents part of the initial tutorial sequence. + - `source/Howtos/Starting/` holds all documents part of the initial tutorial sequence. Other files and folders: - `source/api/` contains the auto-generated API documentation as `.rst` files. Don't edit these - files manually, your changes will be lost. + files manually, your changes will be lost. To refer to these files, use `api:` followed by + the Python path, for example `[rpsystem contrib](api:evennia.contrib.rpsystem)`. - `source/_templates` and `source/_static` should not be modified unless adding a new doc-page feature or changing the look of the HTML documentation. - `conf.py` holds the Sphinx configuration. It should usually not be modified except to update @@ -62,7 +63,7 @@ not hard and is very readable on its raw text-form. You can furthermore get a good feel for how things will look using a Markdown-viewer like [Grip][grip]. Editors like [ReText][retext] or IDE's like -[PyCharm][pycharm] also have Markdown previews. Building the docs locally is +[PyCharm][pycharm] also have native Markdown previews. Building the docs locally is however the only way to make sure the outcome is exactly as you expect. The process will also find any mistakes you made, like making a typo in a link. @@ -98,13 +99,17 @@ done in your terminal/console. The full documentation includes both the doc pages and the API documentation generated from the Evennia source. For this you must install Evennia and -initialize a new game with a default database (you don't need to have it +initialize a new game with a default database (you don't need to have any server running) -- Follow the normal [Evennia Getting-Started instructions][getting-started] - to install Evennia into a virtualenv. Get back here once everything is installed but - before creating a new game. -- Make sure you `cd` to the folder _containing_ your `evennia/` repo (so two levels +- It's recommended that you use a virtualenv. Install your cloned version of Evennia into +by pointing to the repo folder (the one containing `/docs`): + + ``` + pip install -e evennia + ``` + +- Make sure you are in the parent folder _containing_ your `evennia/` repo (so _two_ levels up from `evennia/docs/`). - Create a new game folder called exactly `gamedir` at the same level as your `evennia` repo with @@ -113,8 +118,8 @@ repo with evennia --init gamedir ``` -- Then `cd` into it and create a new, empty database. You don't need to start the game - or do any further changes. +- Then `cd` into it and create a new, empty database. You don't need to start the +game or do any further changes after this. ``` evennia migrate @@ -130,11 +135,10 @@ repo with ----- gamedir/ ``` -If you are already working on a game, you may of course have your 'real' game folder there as -well. We won't touch that. +(If you are already working on a game, you may of course have your 'real' game folder there as +well. We won't touch that.) -- Make sure you are still in your virtualenv, then go to `evennia/docs/` and - install the doc-building requirements: +- Go to `evennia/docs/` and install the doc-building requirements (you only need to do this once): ``` make install @@ -180,8 +184,8 @@ docs are built by looking at the git tree. make mv-local ``` -This is as close to the 'real' version as you can get locally. The different versions -will be found under `evennia/docs/build`. During deploy a symlink `latest` will point +This is as close to the 'real' version of the docs as you can get locally. The different versions +will be found under `evennia/docs/build/versions/`. During deploy a symlink `latest` will point to the latest version of the docs. #### Release @@ -221,16 +225,16 @@ We generally use underscores for italics and double-asterisks for bold: ### Headings We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get -smaller -and smaller font). +smaller and smaller font). - `# Heading` - `## SubHeading` -- `## SubSubHeading` +- `### SubSubHeading` +- `#### SubSubSubHeading` -> Don't reuse the same heading/subheading name over and over in the same document. While Markdown -does not prevent -it, it makes it impossible to link to those duplicates properly (see next section). +> Don't use the same heading/subheading name more than once in one page. While Markdown +does not prevent it, it will make it impossible to refer to that heading uniquely. +The Evennia documentation preparser will detect this and give you an error. ### Lists @@ -283,13 +287,13 @@ full `http://` linking unless really referring to an external resource. You can point to sub-sections (headings) in a document by using a single `#` and the name of the heading, replacing spaces with dashes. So to refer to a heading `## Cool Stuff` inside `My-Document` -would be a link `[cool stuff](My-Document#Cool-Stuff)`. +would be a link `[cool stuff](My-Document#Cool-Stuff)`. This is why headings must be uniquely named +within on document. - `[linktext][linkref]` - refer to a reference defined later in the document. Urls can get long and if you are using the same url in many places it can get a little cluttered. So -you can also put -the url as a 'footnote' at the end of your document +you can also put the url as a 'footnote' at the end of your document and refer to it by putting your reference within square brackets `[ ]`. Here's an example: ``` @@ -298,7 +302,7 @@ This is a [clickable link][mylink]. This is [another link][1]. ... -[mylink](http://...) +[mylink]: http://... [1]: My-Document ``` @@ -309,8 +313,8 @@ The Evennia documentation supports some special reference shortcuts in links: ##### Github online repository -- `github:` - a shortcut for the full path to the Evennia repository on github. This will refer to - the `master` branch by default: +- `github:` - a shortcut for the full path to the Evennia repository on github. This must be given +with forward-slashes and include the `.py` file ending. It will refer to the `master` branch by default: [link to objects.py](github:evennia/objects/objects.py) @@ -328,21 +332,18 @@ The Evennia documentation supports some special reference shortcuts in links: This will create a link to the auto-generated `evennia/source/api/evennia.objects.rst` document. Since api-docs are generated alongside the documentation, this will always be the api docs for -the - current version/branch of the docs. + the current version/branch of the docs. ##### Bug reports/feature request -- `issue`, `bug-report`, `feature-request` - links to the same github issue select page. +- `github:issue` - links to the github issue selection page, where the user can choose which type of + issue to create. If you find a problem, make a [bug report](github:issue)! This will generate a link to https://github.com/evennia/evennia/issues/new/choose. - > For some reason these particular shortcuts gives a warning during documentation compilation. This - > can be ignored. - ### Verbatim text It's common to want to mark something to be displayed verbatim - just as written - without any @@ -396,13 +397,13 @@ def a_python_func(x): Markdown is easy to read and use. But while it does most of what we need, there are some things it's not quite as expressive as it needs to be. For this we need to fall back to the [ReST][ReST] markup language which the documentation system uses under the hood. This is done by specifying `eval_rst` -as -the name of the `language` of a literal block: +as the name of the `language` of a literal block: ```` ```eval_rst - This will be evaluated as ReST. + This will be evaluated as ReST. + All content must be indented. ``` ```` @@ -413,13 +414,23 @@ There is also a short-hand form for starting a [ReST directive][ReST-directives] ```` ```directive:: possible-option - Content that *must* be indented for it to be included in the directive. + Content *must* be indented for it to be included in the directive. - New lines are ignored except if separated by an empty line. + New lines are ignored, empty lines starts a new paragraph. ``` ```` -See below for examples of this. +Within a ReST block, one must use Restructured Text syntax, which is not the same as Markdown. + +- Single backticks around text makes it _italic_. +- Double backticks around text makes it `verbatim`. +- A link is written within back-ticks, with an underscore at the end: + + `python `_ + +[Here is a ReST formatting cheat sheet](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html). + +Below are examples of ReST-block structures. #### Note @@ -598,9 +609,9 @@ or the more flexible but verbose #### A more flexible code block -The regular Markdown codeblock is usually enough but for more direct control over the style, one -can also specify the code block explicitly in `ReST`. -for more flexibility. It also provides a link to the code block, identified by its name. +The regular Markdown Python codeblock is usually enough but for more direct control over the style, one +can also specify the code block explicitly in `ReST` for more flexibility. +It also provides a link to the code block, identified by its name. ```` @@ -642,11 +653,21 @@ this block through the link that will appear (so it should be unique for a give document). > The default markdown syntax will actually generate a code-block ReST instruction like this -> automatically for us behind the scenes. The automatic generation can't know things like emphasize- -lines -> or caption since that's not a part of the Markdown specification. +> automatically for us behind the scenes. But the automatic generation can't know things like emphasize- +lines or captions since that's not a part of the Markdown specification. -# Technical +## Code documentation + +The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting, +including header levels down to 4th level (`#### SubSubSubHeader`). After the module documentation it's +a good idea to end with four dashes `----`. This will create a visible line between the documentation and the +class/function docs to follow. See for example [the Traits docs](api:evennia.contrib.traits). + +All non-private classes, methods and functions must have a Google-style docstring, as per the +[Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted +into pretty api docs. + +## Technical Evennia leverages [Sphinx][sphinx] with the [recommonmark][recommonmark] extension, which allows us to write our diff --git a/docs/source/Howto/Starting/Part2/Game-Planning.md b/docs/source/Howto/Starting/Part2/Game-Planning.md index 678f597f73..c8f144ec8d 100644 --- a/docs/source/Howto/Starting/Part2/Game-Planning.md +++ b/docs/source/Howto/Starting/Part2/Game-Planning.md @@ -48,12 +48,12 @@ world is "about": The theme, the world concept, cool monsters and so on. Such th unfortunately, they are not enough to make your game. You need to figure out how to accomplish your ideas in Evennia. -Below are some questions to get you going. Depending on your game, there are many more possible questions you -could ask yourself. +Below are some questions to get you going. In the next lesson we will try to answer them for our particular +tutorial game. There are of course many more questions you could be asking yourself. ### Administration -- Should your game rules be enforced by coded systems by human game masters? +- Should your game rules be enforced by coded systems or by human game masters? - What is the staff hierarchy in your game? Is vanilla Evennia roles enough or do you need something else? - Should players be able to post out-of-characters on channels and via other means like bulletin-boards? diff --git a/docs/source/Howto/Starting/Part2/Planning-Some-Useful-Contribs.md b/docs/source/Howto/Starting/Part2/Planning-Some-Useful-Contribs.md new file mode 100644 index 0000000000..f09a9b8dfc --- /dev/null +++ b/docs/source/Howto/Starting/Part2/Planning-Some-Useful-Contribs.md @@ -0,0 +1,255 @@ +[prev lesson](./Planning-The-Tutorial-Game) | [next lesson](../Starting-Part3) + +# Planning the use of some useful contribs + +Evennia is deliberately bare-bones out of the box. The idea is that you should be as unrestricted as possible +in designing your game. This is why you can easily replace the few defaults we have and why we don't try to +prescribe any major game systems on you. + +That said, Evennia _does_ offer some more game-opinionated _optional_ stuff. These are referred to as _Contribs_ +and is an ever-growing treasure trove of code snippets, concepts and even full systems you can pick and choose +from to use, tweak or take inspiration from when you make your game. + +The [Contrib overview](../../../Contribs/Contrib-Overview) page gives the full list of the current roster of contributions. On +this page we will review a few contribs we will make use of for our game. We will do the actual installation +of them when we start coding in the next part of this tutorial series. While we will introduce them here, you +are wise to read their doc-strings yourself for the details. + +This is the things we know we need: + +- A barter system +- Character generation +- Some concept of wearing armor +- The ability to roll dice +- Rooms with awareness of day, night and season +- Roleplaying with short-descs, poses and emotes +- Quests +- Combat (with players and against monsters) + +## Barter contrib + +[source](api:evennia.contrib.barter) + +Reviewing this contrib suggests that it allows for safe trading between two parties. The basic principle +is that the parties puts up the stuff they want to sell and the system will guarantee that these systems are +exactly what is being offered. Both sides can modify their offers (bartering) until both mark themselves happy +with the deal. Only then the deal is sealed and the objects are exchanged automatically. Interestingly, this +works just fine for money too - just put coin objects on one side of the transaction. + + Sue > trade Tom: Hi, I have a necklace to sell; wanna trade for a healing potion? + Tom > trade Sue: Hm, I could use a necklace ... + + Sue > offer necklace: This necklace is really worth it. + Tom > evaluate necklace: + + Tom > offer ration: I don't have a healing potion, but I'll trade you an iron ration! + Sue > Hey, this is a nice necklace, I need more than a ration for it... + Tom > offer ration, 10gold: Ok, a ration and 10 gold as well. + Sue > accept: Ok, that sounds fair! + Tom > accept: Good! Nice doing business with you. + + +Arguably, in a small game you are just fine to just talk to people and use `give` to do the exchange. The +barter system guarantees trading safety if you don't trust your counterpart to try to give you the wrong thing or +to run away with your money. + +We will use the barter contrib as an optional feature for player-player bartering. More importantly we can +add it for NPC shopkeepers and expand it with a little AI, which allows them to potentially trade in other +things than boring gold coin. + +## Character generation contrib + +[source](api:evennia.contrib.chargen) + +This contrib is an example module for creating characters. Since we will be using `MULTISESSION_MODE=3` we will +get a selection screen like this automatically. We also plan to use a proper menu to build our character, so +we will _not_ be using this contrib. + +## Clothing contrib + +[source](api:evennia.contrib.clothing) + +This contrib provides a full system primarily aimed at wearing clothes, but it could also work for armor. You wear +an object in a particular location and this will then be reflected in your character's description. You can +also add roleplaying flavor: + + > wear helmet slightly askew on her head + look self + Username is wearing a helmet slightly askew on her head. + +By default there are no 'body locations' in this contrib, we will need to expand on it a little to make it useful +for things like armor. It's a good contrib to build from though, so that's what we'll do. + +## Dice contrib + +[source](api:evennia.contrib.dice) + +The dice contrib presents a general dice roller to use in game. + + > roll 2d6 + Roll(s): 2 and 5. Total result is 7. + > roll 1d100 + 2 + Roll(s): 43. Total result is 47 + > roll 1d20 > 12 + Roll(s): 7. Total result is 7. This is a failure (by 5) + > roll/hidden 1d20 > 12 + Roll(s): 18. Total result is 17. This is a success (by 6). (not echoed) + +The contrib also has a python function for producing these results in-code. However, while +we will emulate rolls for our rule system, we'll do this as simply as possible with Python's `random` +module. + +So while this contrib is fun to have around for GMs or for players who want to get a random result +or play a game, we will not need it for the core of our game. + +## Extended room contrib + +[source](api:evennia.contrib.extended_room) + +This is a custom Room typeclass that changes its description based on time of day and season. + +For example, at night, in wintertime you could show the room as being dark and frost-covered while in daylight +at summer it could describe a flowering meadow. The description can also contain special markers, so +` ... ` would include text only visible at morning. + +The extended room also supports _details_, which are things to "look at" in the room without there having +to be a separate database object created for it. For example, a player in a church may do `look window` and +get a description of the windows without there needing to be an actual `window` object in the room. + +Adding all those extra descriptions can be a lot of work, so they are optional; if not given the room works +like a normal room. + +The contrib is simple to add and provides a lot of optional flexibility, so we'll add it to our +game, why not! + +## RP-System contrib + +[source](api:evennia.contrib.rpsystem) + +This contrib adds a full roleplaying subsystem to your game. It gives every character a "short-description" +(sdesc) that is what people will see when first meeting them. Let's say Tom has an sdesc "A tall man" and +Sue has the sdesc "A muscular, blonde woman" + + Tom > look + Tom: ... You see: A muscular, blonde woman + Tom > emote /me smiles to /muscular. + Tom: Tom smiles to A muscular, blonde woman. + Sue: A tall man smiles to Sue. + Tom > emote Leaning forward, /me says, "Well hello, what's yer name?" + Tom: Leaning forward, Tom says, "Well hello..." + Sue: Leaning forward, A tall man says, "Well hello, what's yer name?" + Sue > emote /me grins. "I'm Angelica", she says. + Sue: Sue grins. "I'm Angelica", she says. + Tom: A muscular, blonde woman grins. "I'm Angelica", she says. + Tom > recog muscular Angelica + Tom > emote /me nods to /angelica: "I have a message for you ..." + Tom: Tom nods to Angelica: "I have a message for you ..." + Sue: A tall man nods to Sue: "I have a message for you ..." + +Above, Sue introduces herself as "Angelica" and Tom uses this info to `recoc` her as "Angelica" hereafter. He +could have `recoc`-ed her with whatever name he liked - it's only for his own benefit. There is no separate +`say`, the spoken words are embedded in the emotes in quotes `"..."`. + +The RPSystem module also includes options for `poses`, which help to establish your position in the room +when others look at you. + + Tom > pose stands by the bar, looking bored. + Sue > look + Sue: ... A tall man stands by the bar, looking bored. + +You can also wear a mask to hide your identity; your sdesc will then be changed to the sdesc of the mask, +like `a person with a mask`. + +The RPSystem gives a lot of roleplaying power out of the box, so we will add it. There is also a separate +[rplanguage](api:evennia.contrib.rplanguage) module that integrates with the spoken words in your emotes and garbles them if you don't understand +the language spoken. In order to restrict the scope we will not include languages for the tutorial game. + + +## Talking NPC contrib + +[source](api:evennia.contrib.talking_npc) + +This exemplifies an NPC with a menu-driven dialogue tree. We will not use this contrib explicitly, but it's +good as inspiration for how we'll do quest-givers later. + +## Traits contrib + +[source](api:evennia.contrib.traits) + +An issue with dealing with roleplaying attributes like strength, dexterity, or skills like hunting, sword etc +is how to keep track of the values in the moment. Your strength may temporarily be buffed by a strength-potion. +Your swordmanship may be worse because you are encumbered. And when you drink your health potion you must make +sure that those +20 health does not bring your health higher than its maximum. All this adds complexity. + +The _Traits_ contrib consists of several types of objects to help track and manage values like this. When +installed, the traits are accessed on a new handler `.traits`, for example + + > py self.traits.hp.value + 100 + > py self.traits.hp -= 20 # getting hurt + > py self.traits.hp.value + 80 + > py self.traits.hp.reset() # drink a potion + > py self.traits.hp.value + 100 + +A Trait is persistent (it uses an Attribute under the hood) and tracks changes, min/max and other things +automatically. They can also be added together in various mathematical operations. + +The contrib introduces three main Trait-classes + +- _Static_ traits for single values like str, dex, things that at most gets a modifier. +- _Counters_ is a value that never moves outside a given range, even with modifiers. For example a skill + that can at most get a maximum amount of buff. Counters can also easily be _timed_ so that they decrease + or increase with a certain rate per second. This could be good for a time-limited curse for example. +- _Gauge_ is like a fuel-gauge; it starts at a max value and then empties gradually. This is perfect for +things like health, stamina and the like. Gauges can also change with a rate, which works well for the +effects of slow poisons and healing both. + +``` +> py self.traits.hp.value +100 +> py self.traits.hp.rate = -1 # poisoned! +> py self.traits.hp.ratetarget = 50 # stop at 50 hp +# Wait 30s +> py self.traits.hp.value +70 +# Wait another 30s +> py self.traits.hp.value +50 # stopped at 50 +> py self.traits.hp.rate = 0 # no more poison +> py self.traits.hp.rate = 5 # healing magic! +# wait 5s +> pyself.traits.hp.value +75 +``` + +Traits will be very practical to use for our character sheets. + +## Turnbattle contrib + +[source](api:evennia.contrib.turnbattle) + +This contrib consists of several implementations of a turn-based combat system, divivided into complexity: + +- basic - initiative and turn order, attacks against defense values, damage. +- equip - considers weapons and armor, wielding and weapon accuracy. +- items - adds usable items with conditions and status effects +- magic - adds spellcasting system using MP. +- range - adds abstract positioning and 1D movement to differentiate between melee and ranged attacks. + +The turnbattle system is comprehensive, but it's meant as a base to start from rather than offer +a complete system. It's also not built with _Traits_ in mind, so we will need to adjust it for that. + +## Conclusions + +With some contribs selected, we have pieces to build from and don't have to write everything from scratch. +We will need Quests and will likely need to do a bunch of work on Combat to adapt the combat contrib +to our needs. + +We will now move into actually starting to implement our tutorial game +in the next part of this tutorial series. When doing this for yourself, remember to refer +back to your planning and adjust it as you learn what works and what does not. + + +[prev lesson](./Planning-The-Tutorial-Game) | [next lesson](../Starting-Part3) diff --git a/docs/source/Howto/Starting/Part2/Planning-The-Tutorial-Game.md b/docs/source/Howto/Starting/Part2/Planning-The-Tutorial-Game.md index cccfaa1717..0438a64a4c 100644 --- a/docs/source/Howto/Starting/Part2/Planning-The-Tutorial-Game.md +++ b/docs/source/Howto/Starting/Part2/Planning-The-Tutorial-Game.md @@ -1,4 +1,4 @@ -[prev lesson](Game-Planningd) | [next lesson](../../../Unimplemented) +[prev lesson](./Game-Planning) | [next lesson](./Planning-Some-Useful-Contribs) # Planning our tutorial game @@ -411,4 +411,4 @@ Before starting to code in earnest a good coder should always do an inventory of to code themselves. So in the next lesson we will check out what help we have from Evennia's _contribs_. -[prev lesson](Game-Planningd) | [next lesson](../../../Unimplemented) +[prev lesson](./Game-Planning) | [next lesson](./Planning-Some-Useful-Contribs) \ No newline at end of file diff --git a/docs/source/Howto/Starting/Part2/Some-Useful-Contribs.md b/docs/source/Howto/Starting/Part2/Some-Useful-Contribs.md deleted file mode 100644 index 70b574a6ef..0000000000 --- a/docs/source/Howto/Starting/Part2/Some-Useful-Contribs.md +++ /dev/null @@ -1,3 +0,0 @@ -# Some useful contribs - -TODO \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 3de7270eb6..9fb62849d5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -276,7 +276,7 @@ def autodoc_post_process_docstring(app, what, name, obj, options, lines): doc = re.sub(r"```", "", doc, flags=re.MULTILINE) doc = re.sub(r"`{1}", "**", doc, flags=re.MULTILINE) doc = re.sub( - r"^(?P#{1,2})\s*?(?P.*?)$", _sub_header, doc, flags=re.MULTILINE + r"^(?P<hashes>#{1,4})\s*?(?P<title>.*?)$", _sub_header, doc, flags=re.MULTILINE ) newlines = doc.split("\n") diff --git a/docs/source/toc.md b/docs/source/toc.md index b5b67899ca..f27032e3ac 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -99,8 +99,8 @@ - [Howto/NPC shop Tutorial](Howto/NPC-shop-Tutorial) - [Howto/Parsing commands tutorial](Howto/Parsing-commands-tutorial) - [Howto/Starting/Part2/Game Planning](Howto/Starting/Part2/Game-Planning) +- [Howto/Starting/Part2/Planning Some Useful Contribs](Howto/Starting/Part2/Planning-Some-Useful-Contribs) - [Howto/Starting/Part2/Planning The Tutorial Game](Howto/Starting/Part2/Planning-The-Tutorial-Game) -- [Howto/Starting/Part2/Some Useful Contribs](Howto/Starting/Part2/Some-Useful-Contribs) - [Howto/Starting/Part3/A Sittable Object](Howto/Starting/Part3/A-Sittable-Object) - [Howto/Starting/Part3/Implementing a game rule system](Howto/Starting/Part3/Implementing-a-game-rule-system) - [Howto/Starting/Part3/Turn based Combat System](Howto/Starting/Part3/Turn-based-Combat-System) diff --git a/evennia/contrib/traits.py b/evennia/contrib/traits.py index 73393c8966..f3bd25ad3b 100644 --- a/evennia/contrib/traits.py +++ b/evennia/contrib/traits.py @@ -328,6 +328,8 @@ Reload the server and you should now be able to use your trait: ``` +---- + """