From 2f9786ae048bc68d35f891efe8f202657dac3c43 Mon Sep 17 00:00:00 2001 From: Tegiminis Date: Tue, 9 Aug 2022 11:49:33 -0700 Subject: [PATCH] i can't stop updating my readme!!! --- evennia/contrib/rpg/buffs/README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/evennia/contrib/rpg/buffs/README.md b/evennia/contrib/rpg/buffs/README.md index 62c76d1143..8e082cede5 100644 --- a/evennia/contrib/rpg/buffs/README.md +++ b/evennia/contrib/rpg/buffs/README.md @@ -81,6 +81,8 @@ buffs after application, they are very useful. The handler's `check`/`trigger` m `get(key)` is the most basic getter. It returns a single buff instance, or `None` if the buff doesn't exist on the handler. It is also the only getter that returns a single buff instance, rather than a dictionary. +> **Note**: The handler method `has(buff)` allows you to check if a matching key (if a string) or buff class (if a class) is present on the handler cache, without actually instantiating the buff. You should use this method for basic "is this buff present?" checks. + Group getters, listed below, return a dictionary of values in the format `{buffkey: instance}`. If you want to iterate over all of these buffs, you should do so via the `dict.values()` method. @@ -292,24 +294,28 @@ Buffs also have a few useful properties: #### Buff Cache (Advanced) -Buffs always store some useful mutable information about themselves in the cache (what is stored on the owning object's database attribute). A buff's cache corresponds to `{buffkey: buffcache}`, where `buffcache` is a dictionary containing __at least__ the mutable information below.: +Buffs always store some useful mutable information about themselves in the cache (what is stored on the owning object's database attribute). A buff's cache corresponds to `{buffkey: buffcache}`, where `buffcache` is a dictionary containing __at least__ the information below: - `ref` (class): The buff class path we use to construct the buff. - `start` (float): The timestamp of when the buff was applied. - `source` (Object): If specified; this allows you to track who or what applied the buff. - `prevtick` (float): The timestamp of the previous tick. - `duration` (float): The cached duration. This can vary from the class duration, depending on if the duration has been modified (paused, extended, shortened, etc). -- `tickrate` (float): The buff's tick rate. Cannot go below 0. Altering the tickrate on an applied buff will not cause it to start ticking if it wasn't ticking before. (pause and unpause to start/stop ticking on existing buffs) +- `tickrate` (float): The buff's tick rate. Cannot go below 0. Altering the tickrate on an applied buff will not cause it to start ticking if it wasn't ticking before. (`pause` and `unpause` to start/stop ticking on existing buffs) - `stacks` (int): How many stacks they have. - `paused` (bool): Paused buffs do not clean up, modify values, tick, or fire any hook methods. Sometimes you will want to dynamically update a buff's cache at runtime, such as changing a tickrate in a hook method, or altering a buff's duration. -You can do so by using the interface `buff.cachekey`. As long as the attribute name matches a key in the cache dictionary, -it will update the stored cache with the new value. +You can do so by using the interface `buff.cachekey`. As long as the attribute name matches a key in the cache dictionary, it will update the stored +cache with the new value. + +If there is no matching key, it will do nothing. If you wish to add a new key to the cache, you must use the `buff.update_cache(dict)` method, +which will properly update the cache (including adding new keys) using the dictionary provided. > **Example**: You want to increase a buff's duration by 30 seconds. You use `buff.duration += 30`. This new duration is now reflected on both the instance and the cache. -All of the above mutable information can be found in this cache, as well as any arbitrary information you pass through the handler `add` method (via `to_cache`). +The buff cache can also store arbitrary information. To do so, pass a dictionary through the handler `add` method (`handler.add(BuffClass, to_cache=dict)`), +set the `cache` dictionary attribute on your buff class, or use the aforementioned `buff.update_cache(dict)` method. > **Example**: You store `damage` as a value in the buff cache and use it for your poison buff. You want to increase it over time, so you use `buff.damage += 1` in the tick method. @@ -323,7 +329,7 @@ Mod objects consist of only four values, assigned by the constructor in this ord - `stat`: The stat you want to modify. When `check` is called, this string is used to find all the mods that are to be collected. - `mod`: The modifier. Defaults are `add` (addition/subtraction), `mult` (multiply), and `div` (divide). Modifiers are calculated additively (see `_calculate_mods` for more) - `value`: How much value the modifier gives regardless of stacks -- `perstack`: How much value the modifier grants per stack, INCLUDING the first. (default: 0) +- `perstack`: How much value the modifier grants per stack, **INCLUDING** the first. (default: 0) The most basic way to add a Mod to a buff is to do so in the buff class definition, like this: @@ -345,8 +351,7 @@ An advanced way to do mods is to generate them when the buff is initialized. Thi ```python class GeneratedStatBuff(BaseBuff): ... - def __init__(self, handler, buffkey, cache={}) -> None: - super().__init__(handler, buffkey, cache) + def at_init(self, *args, **kwargs) -> None: # Finds our "modgen" cache value, and generates a mod from it modgen = list(self.cache.get("modgen")) if modgen: @@ -403,7 +408,7 @@ example, if you want a buff that makes the player take more damage when they are class FireSick(BaseBuff): ... def conditional(self, *args, **kwargs): - if self.owner.buffs.get_by_type(FireBuff): + if self.owner.buffs.has(FireBuff): return True return False ```