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)

Bases: evennia.scripts.scripts.ScriptBase

This is the base TypeClass for all Scripts. Scripts describe events, timers and states in game, they can have a time component or describe a state that changes under certain conditions.

classmethod create(key, **kwargs)

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

Only called once, when script is first created.

time_until_next_repeat()

Get time until the script fires it at_repeat hook again.

Returns

next (int) –

Time in seconds until the script runs again.

If not a timed script, return None.

Notes

This hook is not used in any way by the script’s stepping system; it’s only here for the user to be able to check in on their scripts and when they will next be run.

remaining_repeats()

Get the number of returning repeats for limited Scripts.

Returns

remaining (int or None) –

The number of repeats

remaining until the Script stops. Returns None if it has unlimited repeats.

at_idmapper_flush()

If we’re flushing this object, make sure the LoopingCall is gone too

start(force_restart=False)

Called every time the script is started (for persistent scripts, this is usually once every server start)

Parameters

force_restart (bool, optional) – Normally an already started script will not be started again. if force_restart=True, the script will always restart the script, regardless of if it has started before.

Returns

result (int) –

0 or 1 depending on if the script successfully

started or not. Used in counting.

stop(kill=False)

Called to stop the script from running. This also deletes the script.

Parameters

kill (bool, optional) –

• Stop the script without

calling any relevant script hooks.

Returns

result (int) –

0 if the script failed to stop, 1 otherwise.

Used in counting.

pause(manual_pause=True)

This stops a running script and stores its active state. It WILL NOT call the at_stop() hook.

unpause(manual_unpause=True)

Restart a paused script. This WILL call the at_start() hook.

Parameters

manual_unpause (bool, optional) – This is False if unpause is called by the server reload/reset mechanism.

Returns

result (bool) – True if unpause was triggered, False otherwise.

Raises

RuntimeError – If trying to automatically resart this script (usually after a reset/reload), but it was manually paused, and so should not the auto-unpaused.

restart(interval=None, repeats=None, start_delay=None)

Restarts an already existing/running Script from the beginning, optionally using different settings. This will first call the stop hooks, and then the start hooks again. :param interval: Allows for changing the interval

of the Script. Given in seconds. if None, will use the already stored interval.

Parameters

• repeats (int, optional) – The number of repeats. If unset, will use the previous setting.

• start_delay (bool, optional) – If we should wait interval seconds before starting or not. If None, re-use the previous setting.

reset_callcount(value=0)

Reset the count of the number of calls done.

Parameters

value (int, optional) – The repeat value to reset to. Default is to set it all the way back to 0.

Notes

This is only useful if repeats != 0.

force_repeat()

Fire a premature triggering of the script callback. This will reset the timer and count down repeats as if the script had fired normally.

is_valid()

Is called to check if the script is valid to run at this time. Should return a boolean. The method is assumed to collect all needed information from its related self.obj.

at_start(**kwargs)

Called whenever the script is started, which for persistent scripts is at least once every server start. It will also be called when starting again after a pause (such as after a server reload)

Parameters

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

at_repeat(**kwargs)

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_stop(**kwargs)

Called whenever when it’s time for this script to stop (either because is_valid returned False or it runs out of iterations)

Args

**kwargs (dict): Arbitrary, optional arguments for users

overriding the call (unused by default).

at_server_reload()

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

This hook is called whenever the server is shutting down fully (i.e. not for a restart).

exception DoesNotExist

Bases: evennia.scripts.scripts.ScriptBase.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.ScriptBase.MultipleObjectsReturned

path = 'evennia.scripts.scripts.DefaultScript'

typename = 'DefaultScript'

class evennia.scripts.scripts.DoNothing(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

A script that does nothing. Used as default fallback.

at_script_creation()

Setup the script

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.scripts.scripts.DoNothing'

typename = 'DoNothing'

class evennia.scripts.scripts.Store(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

Simple storage script

at_script_creation()

Setup the script

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.scripts.scripts.Store'

typename = 'Store'