The MonitorHandler is a system for watching changes in properties or Attributes on objects. A monitor can be thought of as a sort of trigger that responds to change.
The main use for the MonitorHandler is to report changes to the client;
for example the client Session may ask Evennia to monitor the value of
health attribute and report whenever it changes. This
way the client could for example update its health bar graphic as
Using the MonitorHandler¶
The MontorHandler is accessed from the singleton
evennia.MONITOR_HANDLER. The code for the handler is in
Here’s how to add a new monitor:
from evennia import MONITOR_HANDLER MONITOR_HANDLER.add(obj, fieldname, callback, idstring="", persistent=False, **kwargs)
obj(Typeclassed entity) - the object to monitor. Since this must be typeclassed, it means you can’t monitor changes on Sessions with the monitorhandler, for example.
fieldname(str) - the name of a field or Attribute on
obj. If you want to monitor a database field you must specify its full name, including the starting
db_locationetc). Any names not starting with
db_are instead assumed to be the names of Attributes. This difference matters, since the MonitorHandler will automatically know to watch the
db_valuefield of the Attribute.
callback(callable) - This will be called as
callback(fieldname=fieldname, obj=obj, **kwargs)when the field updates.
idstring(str) - this is used to separate multiple monitors on the same object and fieldname. This is required in order to properly identify and remove the monitor later. It’s also used for saving it.
persistent(bool) - if True, the monitor will survive a server reboot.
from evennia import MONITOR_HANDLER as monitorhandler def _monitor_callback(fieldname="", obj=None, **kwargs): # reporting callback that works both # for db-fields and Attributes if fieldname.startswith("db_"): new_value = getattr(obj, fieldname) else: # an attribute new_value = obj.attributes.get(fieldname) obj.msg("%s.%s changed to '%s'." % \ (obj.key, fieldname, new_value)) # (we could add _some_other_monitor_callback here too) # monitor Attribute (assume we have obj from before) monitorhandler.add(obj, "desc", _monitor_callback) # monitor same db-field with two different callbacks (must separate by id_string) monitorhandler.add(obj, "db_key", _monitor_callback, id_string="foo") monitorhandler.add(obj, "db_key", _some_other_monitor_callback, id_string="bar")
A monitor is uniquely identified by the combination of the object
instance it is monitoring, the name of the field/attribute to monitor
on that object and its
idstring will be the empty string unless given
So to “un-monitor” the above you need to supply enough information for the system to uniquely find the monitor to remove:
monitorhandler.remove(obj, "desc") monitorhandler.remove(obj, "db_key", idstring="foo") monitorhandler.remove(obj, "db_key", idstring="bar")