evennia.scripts.scripts¶

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.

class evennia.scripts.scripts.DefaultScript(*args, **kwargs)[source]¶

Bases: evennia.scripts.scripts.ScriptBase

This is the base TypeClass for all Scripts. Scripts describe all entities/systems without a physical existence in the game world that require database storage (like an economic system or combat tracker). They can also have a timer/ticker component.

A script type is customized by redefining some or all of its hook methods and variables.

available properties (check docs for full listing, this could be outdated).

key (string) - name of object name (string)- same as key aliases (list of strings) - aliases to the object. Will be saved

to database as AliasDB entries but returned as strings.

dbref (int, read-only) - unique #id-number. Also “id” can be used. date_created (string) - time stamp of object creation permissions (list of strings) - list of permission strings

desc (string) - optional description of script, shown in listings obj (Object) - optional object that this script is connected to

and acts on (set automatically by obj.scripts.add())

interval (int) - how often script should run, in seconds. <0 turns
off ticker

start_delay (bool) - if the script should start repeating right away or
wait self.interval seconds

repeats (int) - how many times the script should repeat before
stopping. 0 means infinite repeats

persistent (bool) - if script should survive a server shutdown or not is_active (bool) - if script is currently running

Handlers

locks - lock-handler: use locks.add() to add new lock strings db - attribute-handler: store/retrieve database attributes on this

self.db.myattr=val, val=self.db.myattr

ndb - non-persistent attribute handler: same as db but does not
create a database entry when storing data

Helper methods

create(key, **kwargs) start() - start script (this usually happens automatically at creation

and obj.script.add() etc)

stop() - stop script, and delete it pause() - put the script on hold, until unpause() is called. If script

is persistent, the pause state will survive a shutdown.

unpause() - restart a previously paused script. The script will continue
from the paused timer (but at_start() will be called).

time_until_next_repeat() - if a timed script (interval>0), returns time
until next tick

Hook methods (should also include self as the first argument):

at_script_creation() - called only once, when an object of this
class is first created.

is_valid() - is called to check if the script is valid to be running

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).

at_start() - Called every time the script is started, which for persistent
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().

at_repeat() - Called every self.interval seconds. It will be called
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.

at_pause() at_stop() - Called as the script object is stopped and is about to be

removed from the game, e.g. because is_valid() returned False.

at_script_delete() at_server_reload() - Called when server reloads. Can be used to

save temporary variables you want should survive a reload.

at_server_shutdown() - called at a full server shutdown. at_server_start()

classmethod create(key, **kwargs)[source]¶

Provides a passthrough interface to the utils.create_script() function.

Parameters: key (str) – Name of the new object.
Returns: object (Object) – A newly created object of the given typeclass. errors (list): A list of errors in string form, if any.

at_script_creation()[source]¶: Only called once, when script is first created.

is_valid()[source]¶: 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.

at_start(**kwargs)[source]¶

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).

Parameters: **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_repeat(**kwargs)[source]¶

Called repeatedly if this Script is set to repeat regularly.

Parameters: **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_pause(manual_pause=True, **kwargs)[source]¶

Called when this script’s timer pauses.

Parameters: manual_pause (bool) – If set, pausing was done by a direct call. The non-manual pause indicates the script was paused as part of the server reload.

at_stop(**kwargs)[source]¶

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.

Parameters: **kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_script_delete()[source]¶

Called when the Script is deleted, before stopping the timer.

Returns: bool – If False, the deletion is aborted.

at_server_reload()[source]¶: 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 to do it.

at_server_shutdown()[source]¶: This hook is called whenever the server is shutting down fully (i.e. not for a restart).

at_server_start()[source]¶: 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 could be used).