<spanid="evennia-scripts-scripts"></span><h1>evennia.scripts.scripts<aclass="headerlink"href="#module-evennia.scripts.scripts"title="Permalink to this headline">¶</a></h1>
<p>This module defines Scripts, out-of-character entities that can store
data both on themselves and on other objects while also having the
ability to run timers.</p>
<dlclass="py class">
<dtid="evennia.scripts.scripts.DefaultScript">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.scripts.scripts.</code><codeclass="sig-name descname">DefaultScript</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript"title="Permalink to this definition">¶</a></dt>
start() - start script (this usually happens automatically at creation</p>
<blockquote>
<div><p>and obj.script.add() etc)</p>
</div></blockquote>
<p>stop() - stop script, and delete it
pause() - put the script on hold, until unpause() is called. If script</p>
<blockquote>
<div><p>is persistent, the pause state will survive a shutdown.</p>
</div></blockquote>
<dlclass="simple">
<dt>unpause() - restart a previously paused script. The script will continue</dt><dd><p>from the paused timer (but at_start() will be called).</p>
</dd>
<dt>time_until_next_repeat() - if a timed script (interval>0), returns time</dt><dd><p>until next tick</p>
</dd>
</dl>
</div></blockquote>
<ulclass="simple">
<li><p>Hook methods (should also include self as the first argument):</p></li>
</ul>
<blockquote>
<div><dl>
<dt>at_script_creation() - called only once, when an object of this</dt><dd><p>class is first created.</p>
</dd>
<dt>is_valid() - is called to check if the script is valid to be running</dt><dd><blockquote>
<div><p>at the current time. If is_valid() returns False, the running
script is stopped and removed from the game. You can use this
to check state changes (i.e. an script tracking some combat
stats at regular intervals is only valid to run while there is
actual combat going on).</p>
</div></blockquote>
<dlclass="simple">
<dt>at_start() - Called every time the script is started, which for persistent</dt><dd><p>scripts is at least once every server start. Note that this is
unaffected by self.delay_start, which only delays the first
call to at_repeat().</p>
</dd>
<dt>at_repeat() - Called every self.interval seconds. It will be called</dt><dd><p>immediately upon launch unless self.delay_start is True, which
will delay the first call of this method by self.interval
seconds. If self.interval==0, this method will never
be called.</p>
</dd>
</dl>
<p>at_pause()
at_stop() - Called as the script object is stopped and is about to be</p>
<blockquote>
<div><p>removed from the game, e.g. because is_valid() returned False.</p>
</div></blockquote>
<p>at_script_delete()
at_server_reload() - Called when server reloads. Can be used to</p>
<blockquote>
<div><p>save temporary variables you want should survive a reload.</p>
</div></blockquote>
<p>at_server_shutdown() - called at a full server shutdown.
<emclass="property">classmethod </em><codeclass="sig-name descname">create</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">key</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.create"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.create"title="Permalink to this definition">¶</a></dt>
<dd><p>Provides a passthrough interface to the utils.create_script() function.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>key</strong> (<em>str</em>) – Name of the new object.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>object (Object)</em>– A newly created object of the given typeclass.
errors (list): A list of errors in string form, if any.</p>
<codeclass="sig-name descname">at_script_creation</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_script_creation"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_script_creation"title="Permalink to this definition">¶</a></dt>
<dd><p>Only called once, when script is first created.</p>
<codeclass="sig-name descname">is_valid</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.is_valid"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.is_valid"title="Permalink to this definition">¶</a></dt>
<dd><p>Is called to check if the script’s timer is valid to run at this time.
Should return a boolean. If False, the timer will be stopped.</p>
<codeclass="sig-name descname">at_start</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_start"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_start"title="Permalink to this definition">¶</a></dt>
<dd><p>Called whenever the script timer is started, which for persistent
timed scripts is at least once every server start. It will also be
called when starting again after a pause (including after a
server reload).</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>**kwargs</strong> (<em>dict</em>) – Arbitrary, optional arguments for users
<codeclass="sig-name descname">at_repeat</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_repeat"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_repeat"title="Permalink to this definition">¶</a></dt>
<dd><p>Called repeatedly if this Script is set to repeat regularly.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>**kwargs</strong> (<em>dict</em>) – Arbitrary, optional arguments for users
<codeclass="sig-name descname">at_pause</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">manual_pause</span><spanclass="o">=</span><spanclass="default_value">True</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_pause"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_pause"title="Permalink to this definition">¶</a></dt>
<dd><p>Called when this script’s timer pauses.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>manual_pause</strong> (<em>bool</em>) – If set, pausing was done by a direct call. The
non-manual pause indicates the script was paused as part of
<codeclass="sig-name descname">at_stop</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_stop"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_stop"title="Permalink to this definition">¶</a></dt>
<dd><p>Called whenever when it’s time for this script’s timer to stop (either
because is_valid returned False, it ran out of iterations or it was manuallys
stopped.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>**kwargs</strong> (<em>dict</em>) – Arbitrary, optional arguments for users
<codeclass="sig-name descname">at_script_delete</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_script_delete"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_script_delete"title="Permalink to this definition">¶</a></dt>
<dd><p>Called when the Script is deleted, before stopping the timer.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>bool</em>– If False, the deletion is aborted.</p>
<codeclass="sig-name descname">at_server_reload</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_server_reload"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_server_reload"title="Permalink to this definition">¶</a></dt>
<dd><p>This hook is called whenever the server is shutting down for
restart/reboot. If you want to, for example, save
non-persistent properties across a restart, this is the place
<codeclass="sig-name descname">at_server_shutdown</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_server_shutdown"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_server_shutdown"title="Permalink to this definition">¶</a></dt>
<dd><p>This hook is called whenever the server is shutting down fully
<codeclass="sig-name descname">at_server_start</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DefaultScript.at_server_start"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.at_server_start"title="Permalink to this definition">¶</a></dt>
<dd><p>This hook is called after the server has started. It can be used to add
post-startup setup for Scripts without a timer component (for which at_start
<emclass="property">exception </em><codeclass="sig-name descname">DoesNotExist</code><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.DoesNotExist"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">MultipleObjectsReturned</code><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">path</code><emclass="property"> = 'evennia.scripts.scripts.DefaultScript'</em><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.path"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">typename</code><emclass="property"> = 'DefaultScript'</em><aclass="headerlink"href="#evennia.scripts.scripts.DefaultScript.typename"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="evennia.scripts.scripts.DoNothing">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.scripts.scripts.</code><codeclass="sig-name descname">DoNothing</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DoNothing"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DoNothing"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">at_script_creation</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#DoNothing.at_script_creation"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.DoNothing.at_script_creation"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">DoesNotExist</code><aclass="headerlink"href="#evennia.scripts.scripts.DoNothing.DoesNotExist"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">MultipleObjectsReturned</code><aclass="headerlink"href="#evennia.scripts.scripts.DoNothing.MultipleObjectsReturned"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">path</code><emclass="property"> = 'evennia.scripts.scripts.DoNothing'</em><aclass="headerlink"href="#evennia.scripts.scripts.DoNothing.path"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">typename</code><emclass="property"> = 'DoNothing'</em><aclass="headerlink"href="#evennia.scripts.scripts.DoNothing.typename"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="evennia.scripts.scripts.Store">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.scripts.scripts.</code><codeclass="sig-name descname">Store</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#Store"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.Store"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">at_script_creation</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/scripts/scripts.html#Store.at_script_creation"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.scripts.scripts.Store.at_script_creation"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">DoesNotExist</code><aclass="headerlink"href="#evennia.scripts.scripts.Store.DoesNotExist"title="Permalink to this definition">¶</a></dt>
<emclass="property">exception </em><codeclass="sig-name descname">MultipleObjectsReturned</code><aclass="headerlink"href="#evennia.scripts.scripts.Store.MultipleObjectsReturned"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">path</code><emclass="property"> = 'evennia.scripts.scripts.Store'</em><aclass="headerlink"href="#evennia.scripts.scripts.Store.path"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py attribute">
<dtid="evennia.scripts.scripts.Store.typename">
<codeclass="sig-name descname">typename</code><emclass="property"> = 'Store'</em><aclass="headerlink"href="#evennia.scripts.scripts.Store.typename"title="Permalink to this definition">¶</a></dt>
