From b819bff5567aef55b6158545e7bf1111b529d9f6 Mon Sep 17 00:00:00 2001
From: Griatch <griatch@gmail.com>
Date: Sun, 20 Aug 2023 18:48:16 +0200
Subject: [PATCH] Append character fix to evadventure tutorial. Resolve #3559

---
 CHANGELOG.md                                  |  2 +
 docs/source/Coding/Changelog.md               |  7 +++
 .../Part3/Beginner-Tutorial-Equipment.md      | 54 ++++++++++++++++++-
 3 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c02b0302cf..2e37e291f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 - Feat: EvMenu tooltips for multiple help categories in a node (Seannio)
 - Fix: Typo in evadventure twitch combat's call of `create_combathandler`.
+- Docs: Fix bug in evadventure equipmenthandler blocking creation of npcs
+  in-game.
 
 ## Evennia 2.2.0
 
diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md
index c63bc4c52a..2e37e291f5 100644
--- a/docs/source/Coding/Changelog.md
+++ b/docs/source/Coding/Changelog.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## Main branch
+
+- Feat: EvMenu tooltips for multiple help categories in a node (Seannio)
+- Fix: Typo in evadventure twitch combat's call of `create_combathandler`.
+- Docs: Fix bug in evadventure equipmenthandler blocking creation of npcs
+  in-game.
+
 ## Evennia 2.2.0
 
 Aug 6, 2023
diff --git a/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Equipment.md b/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Equipment.md
index 07373e8b2f..56576e1c5d 100644
--- a/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Equipment.md
+++ b/docs/source/Howtos/Beginner-Tutorial/Part3/Beginner-Tutorial-Equipment.md
@@ -168,6 +168,8 @@ class EvAdventureCharacter(LivingMixin, DefaultCharacter):
 
 Above we have assumed the `EquipmentHandler` (`.equipment`) has methods `.validate_slot_usage`,  `.add` and `.remove`. But we haven't actually added them yet - we just put some reasonable names! Before we can use this, we need to go actually adding those methods. 
 
+When you do things like `create/drop monster:NPC`, the npc will briefly be in your inventory before being dropped on the ground. Since an NPC is not a valid thing to equip, the EquipmentHandler will complain with an `EquipmentError` (we define this see below). So we need to 
+
 ## Expanding the Equipmenthandler
 
 ## `.validate_slot_usage`
@@ -338,8 +340,7 @@ class EquipmentHandler:
                 if objslot is obj_or_slot:
                     slots[slot] = None
                     ret.append(objslot)
-        elif obj_or_slot in slots[WieldLocation.BACKPACK]:
-            # obj in backpack slot
+        elif obj_or_slot in slots[WieldLocation.BACKPACK]:             # obj in backpack slot
             try:
                 slots[WieldLocation.BACKPACK].remove(obj_or_slot)
                 ret.append(obj_or_slot)
@@ -498,6 +499,55 @@ In the `.armor()` method we get the item (if any) out of each relevant wield-slo
 
 In `.weapon()`, we simply check which of the possible weapon slots (weapon-hand or two-hands) have  something in them. If not we fall back to the 'Bare Hands' object we created in the [Object tutorial lesson](./Beginner-Tutorial-Objects.md#your-bare-hands) earlier.
 
+### Fixing the Character class
+
+So we have added our equipment handler which validate what we put in it. This will however lead to a problem when we create things like NPCs in game, e.g. with 
+
+    create/drop monster:evadventure.npcs.EvAdventureNPC
+
+The problem is that when the monster is created it will briefly appear in your inventory before being dropped, so this code will fire on you when you do that (assuming you are an `EvAdventureCharacter`):
+
+```python
+# mygame/evadventure/characters.py
+# ... 
+
+class EvAdventureCharacter(LivingMixin, DefaultCharacter): 
+
+    # ... 
+
+    def at_object_receive(self, moved_object, source_location, **kwargs): 
+        """ 
+        Called by Evennia when an object arrives 'in' the character.
+        
+        """
+        self.equipment.add(moved_object)
+```
+
+At this means that the equipmenthandler will check the NPC, and since it's not a equippable thing, an `EquipmentError` will be raised, failing the creation. Since we want to be able to create npcs etc easily, we will handle this error with a `try...except` statement like so:
+
+```python
+# mygame/evadventure/characters.py
+# ... 
+from evennia import logger 
+from .equipment import EquipmentError
+
+class EvAdventureCharacter(LivingMixin, DefaultCharacter): 
+
+    # ... 
+
+    def at_object_receive(self, moved_object, source_location, **kwargs): 
+        """ 
+        Called by Evennia when an object arrives 'in' the character.
+        
+        """
+        try:
+            self.equipment.add(moved_object)
+        except EquipmentError:
+            logger.log_trace()
+            
+```
+
+Using Evennia's `logger.log_trace()` we catch the error and direct it to the server log. This allows you to see if there are real errors here as well, but once things work and these errors are spammy, you can also just replace the `logger.log_trace()` line with a `pass` to hide these errors. 
 
 ## Extra credits