Fix issue in NPC-reaction tutorial. Resolve #3591

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Main branch
+
+[Docs][issue3591]: Fix of NPC reaction tutorial code (Griatch)
+
+[issue3592]: https://github.com/evennia/evennia/issues/3591
+
 ## Evennia 4.3.0
 
 Aug 11, 2024

docs/source/Howtos/Tutorial-NPC-Reacting.md

@@ -27,7 +27,7 @@ class NPC(Character):
     """
     A NPC typeclass which extends the character class.
     """
-    def at_char_entered(self, character):
+    def at_char_entered(self, character, **kwargs):
         """
         A simple is_aggressive check.
         Can be expanded upon later.
@@ -38,7 +38,13 @@ class NPC(Character):
             self.execute_cmd(f"say Greetings, {character}!")
 ```
 
-Here we make a simple method on the `NPC`˙. We expect it to be called when a (player-)character enters the room. We don't actually set the `is_aggressive` [Attribute](../Components/Attributes.md) beforehand; if it's not set, the NPC is simply non-hostile. 
+```{sidebar} Passing extra information
+Note that we don't use the `**kwargs` property here. This can be used to pass extra information into hooks in your game and would be used when you make custom move commands. For example, if you `run` into the room, you could inform all hooks by doing `obj.move_to(..., running=True)`. Maybe your librarian NPC should have a separate reaction for people running into their library!
+
+We make sure to pass the `**kwargs` from the standard `at_object_receive` hook below.
+```
+
+Here we make a simple method on the `NPC`˙ called `at_char_entered`. We expect it to be called when a (player-)character enters the room. We don't actually set the `is_aggressive` [Attribute](../Components/Attributes.md) beforehand; we leave this up for the admin to activate in-game. if it's not set, the NPC is simply non-hostile. 
 
 Whenever _something_ enters the `Room`, its [at_object_receive](DefaultObject.at_object_receive) hook will be called. So we should override it.
 
@@ -54,18 +60,18 @@ class Room(ObjectParent, DefaultRoom):
 
     # ... 
     
-    def at_object_receive(self, arriving_obj, source_location):
+    def at_object_receive(self, arriving_obj, source_location, **kwargs):
         if arriving_obj.account: 
             # this has an active acccount - a player character
             for item in self.contents:
                 # get all npcs in the room and inform them
-                if  utils.inherits_from(item, "typeclasses.npcs.NPC"):
-                    self.at_char_entered(arriving_obj)
+                if utils.inherits_from(item, "typeclasses.npcs.NPC"):
+                    item.at_char_entered(arriving_obj, **kwargs)
 
 ```
 
 ```{sidebar} Universal Object methods
-Remember that Rooms are `Objects`. So the same `at_object_receive` hook will fire for you when you pick something up (making you 'receive' it). Or for a box when putting something inside it.
+Remember that Rooms are `Objects`, and other Objects have these same hooks. So an `at_object_receive` hook will fire for you when you pick something up (making you 'receive' it). Or for a box when putting something inside it, for example.
 ```
 A currently puppeted Character will have an `.account` attached to it. We use that to know that the thing arriving is a Character. We then use Evennia's [utils.inherits_from](evennia.utils.utils.inherits_from) helper utility to get every NPC in the room can each of their newly created `at_char_entered` method.
 

evennia/objects/objects.py

@@ -1189,8 +1189,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase):
                 the text message generated by announce_move_to and announce_move_from by defining
                 their {"type": move_type} for outgoing text. This can be used for altering
                 messages and/or overloaded hook behaviors.
-            **kwargs: Passed on to announce_move_to and announce_move_from hooks. Exits will set
-                the "exit_obj" kwarg to themselves.
+            **kwargs: Passed on to all movement- and announcement hooks. Use in your game to let
+                hooks know about any special condition of the move (such as running or sneaking).
+                Exits will pass an "exit_obj" kwarg.
 
         Returns:
             bool: True/False depending on if there were problems with the move. This method may also