From 2c35c2db910ede199eec0df678c5e0a9da724688 Mon Sep 17 00:00:00 2001 From: Griatch Date: Fri, 19 May 2023 21:24:10 +0200 Subject: [PATCH] Add reference to npc.py example from NPC tutorial --- docs/source/Coding/Changelog.md | 11 ++++ docs/source/Contribs/Contrib-Containers.md | 60 +++++++++++++++++++ docs/source/Contribs/Contribs-Overview.md | 29 ++++++--- .../Part3/Beginner-Tutorial-NPCs.md | 3 + 4 files changed, 94 insertions(+), 9 deletions(-) create mode 100644 docs/source/Contribs/Contrib-Containers.md diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index 8bf926bd253..962c25b7f8f 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -1,5 +1,16 @@ # Changelog +## Main branch + +- Feature: Attribute-support for saving/loading `deques` with `maxlen=` set. +- Contrib: Container typeclass with new commands for storing and retrieving + things inside them (InspectorCaracal) +- Fix: The `AttributeHandler.all()` now actually accepts `category=` as + keyword arg, like our docs already claimed it should (Volund) +- Docs: New Beginner-Tutorial lessons for NPCs, Base-Combat Twitch-Combat and + Turnbased-combat (note that the Beginner tutorial is still WIP). + + ## Evennia 1.3.0 Apr 29, 2023 diff --git a/docs/source/Contribs/Contrib-Containers.md b/docs/source/Contribs/Contrib-Containers.md new file mode 100644 index 00000000000..06497c8b5d6 --- /dev/null +++ b/docs/source/Contribs/Contrib-Containers.md @@ -0,0 +1,60 @@ +# Containers +Contribution by InspectorCaracal (2023) + +Adds the ability to put objects into other container objects by providing a container typeclass and extending certain base commands. + +## Installation + +To install, import and add the `ContainerCmdSet` to `CharacterCmdSet` in your `default_cmdsets.py` file: + +```python +from evennia.contrib.game_systems.containers import ContainerCmdSet + +class CharacterCmdSet(default_cmds.CharacterCmdSet): + # ... + + def at_cmdset_creation(self): + # ... + self.add(ContainerCmdSet) +``` + +This will replace the default `look` and `get` commands with the container-friendly versions provided by the contrib as well as add a new `put` command. + +## Usage + +The contrib includes a `ContribContainer` typeclass which has all of the set-up necessary to be used as a container. To use, all you need to do is create an object in-game with that typeclass - it will automatically inherit anything you implemented in your base Object typeclass as well. + + create bag:game_systems.containers.ContribContainer + +The contrib's `ContribContainer` comes with a capacity limit of a maximum number of items it can hold. This can be changed per individual object. + +In code: +```py +obj.capacity = 5 +``` +In game: + + set box/capacity = 5 + +You can also make any other objects usable as containers by setting the `get_from` lock type on it. + + lock mysterious box = get_from:true() + +## Extending + +The `ContribContainer` class is intended to be usable as-is, but you can also inherit from it for your own container classes to extend its functionality. Aside from having the container lock pre-set on object creation, it comes with three main additions: + +### `capacity` property + +`ContribContainer.capacity` is an `AttributeProperty` - meaning you can access it in code with `obj.capacity` and also set it in game with `set obj/capacity = 5` - which represents the capacity of the container as an integer. You can override this with a more complex representation of capacity on your own container classes. + +### `at_pre_get_from` and `at_pre_put_in` methods + +These two methods on `ContribContainer` are called as extra checks when attempting to either get an object from, or put an object in, a container. The contrib's `ContribContainer.at_pre_get_from` doesn't do any additional validation by default, while `ContribContainer.at_pre_put_in` does a simple capacity check. + +You can override these methods on your own child class to do any additional capacity or access checks. + +---- + +This document page is generated from `evennia/contrib/game_systems/containers/README.md`. Changes to this +file will be overwritten, so edit that file rather than this one. diff --git a/docs/source/Contribs/Contribs-Overview.md b/docs/source/Contribs/Contribs-Overview.md index 8a6ea765505..c297c9f15c9 100644 --- a/docs/source/Contribs/Contribs-Overview.md +++ b/docs/source/Contribs/Contribs-Overview.md @@ -7,7 +7,7 @@ in the [Community Contribs & Snippets][forum] forum. _Contribs_ are optional code snippets and systems contributed by the Evennia community. They vary in size and complexity and may be more specific about game types and styles than 'core' Evennia. -This page is auto-generated and summarizes all **47** contribs currently included +This page is auto-generated and summarizes all **48** contribs currently included with the Evennia distribution. All contrib categories are imported from `evennia.contrib`, such as @@ -31,14 +31,14 @@ If you want to add a contrib, see [the contrib guidelines](./Contribs-Guidelines |---|---|---|---|---| | [auditing](#auditing) | [awsstorage](#awsstorage) | [barter](#barter) | [batchprocessor](#batchprocessor) | [bodyfunctions](#bodyfunctions) | | [buffs](#buffs) | [building_menu](#building_menu) | [character_creator](#character_creator) | [clothing](#clothing) | [color_markups](#color_markups) | -| [components](#components) | [cooldowns](#cooldowns) | [crafting](#crafting) | [custom_gametime](#custom_gametime) | [dice](#dice) | -| [email_login](#email_login) | [evadventure](#evadventure) | [evscaperoom](#evscaperoom) | [extended_room](#extended_room) | [fieldfill](#fieldfill) | -| [gendersub](#gendersub) | [git_integration](#git_integration) | [godotwebsocket](#godotwebsocket) | [health_bar](#health_bar) | [ingame_map_display](#ingame_map_display) | -| [ingame_python](#ingame_python) | [mail](#mail) | [mapbuilder](#mapbuilder) | [menu_login](#menu_login) | [mirror](#mirror) | -| [multidescer](#multidescer) | [mux_comms_cmds](#mux_comms_cmds) | [name_generator](#name_generator) | [puzzles](#puzzles) | [random_string_generator](#random_string_generator) | -| [red_button](#red_button) | [rpsystem](#rpsystem) | [simpledoor](#simpledoor) | [slow_exit](#slow_exit) | [talking_npc](#talking_npc) | -| [traits](#traits) | [tree_select](#tree_select) | [turnbattle](#turnbattle) | [tutorial_world](#tutorial_world) | [unixcommand](#unixcommand) | -| [wilderness](#wilderness) | [xyzgrid](#xyzgrid) | +| [components](#components) | [containers](#containers) | [cooldowns](#cooldowns) | [crafting](#crafting) | [custom_gametime](#custom_gametime) | +| [dice](#dice) | [email_login](#email_login) | [evadventure](#evadventure) | [evscaperoom](#evscaperoom) | [extended_room](#extended_room) | +| [fieldfill](#fieldfill) | [gendersub](#gendersub) | [git_integration](#git_integration) | [godotwebsocket](#godotwebsocket) | [health_bar](#health_bar) | +| [ingame_map_display](#ingame_map_display) | [ingame_python](#ingame_python) | [mail](#mail) | [mapbuilder](#mapbuilder) | [menu_login](#menu_login) | +| [mirror](#mirror) | [multidescer](#multidescer) | [mux_comms_cmds](#mux_comms_cmds) | [name_generator](#name_generator) | [puzzles](#puzzles) | +| [random_string_generator](#random_string_generator) | [red_button](#red_button) | [rpsystem](#rpsystem) | [simpledoor](#simpledoor) | [slow_exit](#slow_exit) | +| [talking_npc](#talking_npc) | [traits](#traits) | [tree_select](#tree_select) | [turnbattle](#turnbattle) | [tutorial_world](#tutorial_world) | +| [unixcommand](#unixcommand) | [wilderness](#wilderness) | [xyzgrid](#xyzgrid) | @@ -268,6 +268,7 @@ Contribs-Guidelines.md Contrib-Barter.md Contrib-Clothing.md +Contrib-Containers.md Contrib-Cooldowns.md Contrib-Crafting.md Contrib-Gendersub.md @@ -305,6 +306,16 @@ look of these clothes are appended to the character's description when worn. +### `containers` + +_Adds the ability to put objects into other container objects by providing a container typeclass and extending certain base commands._ + +## Installation + +[Read the documentation](./Contrib-Containers.md) - [Browse the Code](evennia.contrib.game_systems.containers) + + + ### `cooldowns` _Contribution by owllex, 2021_ diff --git a/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-NPCs.md b/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-NPCs.md index fa595c15b00..612a74022cb 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-NPCs.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-NPCs.md @@ -12,6 +12,9 @@ In this lesson we will create the base class of _EvAdventure_ NPCs based on the ## The NPC base class +```{sidebar} +See [evennia/contrib/tutorials/evadventure/npcs.py](evennia.contrib.tutorials.evadventure.npcs) for a ready-made example of an npc module. +``` > Create a new module `evadventure/npcs.py`. ```{code-block} python