<h1>MonitorHandler<aclass="headerlink"href="#monitorhandler"title="Permalink to this headline">¶</a></h1>
<p>The <em>MonitorHandler</em> 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.</p>
<p>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 the Characer’s <codeclass="docutils literal notranslate"><spanclass="pre">health</span></code> attribute and report whenever it changes. This way the client could for example update its health bar graphic as needed.</p>
<divclass="section"id="using-the-monitorhandler">
<h2>Using the MonitorHandler<aclass="headerlink"href="#using-the-monitorhandler"title="Permalink to this headline">¶</a></h2>
<p>The MontorHandler is accessed from the singleton <codeclass="docutils literal notranslate"><spanclass="pre">evennia.MONITOR_HANDLER</span></code>. The code for the handler is in <codeclass="docutils literal notranslate"><spanclass="pre">evennia.scripts.monitorhandler</span></code>.</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> (<aclass="reference internal"href="Typeclasses.html"><spanclass="doc">Typeclassed</span></a> entity) - the object to monitor. Since this must be typeclassed, it means you can’t monitor changes on <aclass="reference internal"href="Sessions.html"><spanclass="doc">Sessions</span></a> with the monitorhandler, for example.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">fieldname</span></code> (str) - the name of a field or <aclass="reference internal"href="Attributes.html"><spanclass="doc">Attribute</span></a> on <codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code>. If you want to monitor a database field you must specify its full name, including the starting <codeclass="docutils literal notranslate"><spanclass="pre">db_</span></code> (like <codeclass="docutils literal notranslate"><spanclass="pre">db_key</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">db_location</span></code> etc). Any names not starting with <codeclass="docutils literal notranslate"><spanclass="pre">db_</span></code> are instead assumed to be the names of Attributes. This difference matters, since the MonitorHandler will automatically know to watch the <codeclass="docutils literal notranslate"><spanclass="pre">db_value</span></code> field of the Attribute.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">callback</span></code>(callable) - This will be called as <codeclass="docutils literal notranslate"><spanclass="pre">callback(fieldname=fieldname,</span><spanclass="pre">obj=obj,</span><spanclass="pre">**kwargs)</span></code> when the field updates.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code> (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.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> (bool) - if True, the monitor will survive a server reboot.</p></li>
<spanclass="n">obj</span><spanclass="o">.</span><spanclass="n">msg</span><spanclass="p">(</span><spanclass="s2">"</span><spanclass="si">%s</span><spanclass="s2">.</span><spanclass="si">%s</span><spanclass="s2"> changed to '</span><spanclass="si">%s</span><spanclass="s2">'."</span><spanclass="o">%</span> \
<p>A monitor is uniquely identified by the combination of the <em>object instance</em> it is monitoring, the <em>name</em> of the field/attribute to monitor on that object and its <codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code> (<codeclass="docutils literal notranslate"><spanclass="pre">obj</span></code> + <codeclass="docutils literal notranslate"><spanclass="pre">fieldname</span></code> + <codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code>). The <codeclass="docutils literal notranslate"><spanclass="pre">idstring</span></code> will be the empty string unless given explicitly.</p>
<p>So to “un-monitor” the above you need to supply enough information for the system to uniquely find the monitor to remove:</p>
