evennia.contrib.base_systems.ingame_python.scripts

Scripts for the in-game Python system.

class evennia.contrib.base_systems.ingame_python.scripts.EventHandler(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

The event handler that contains all events in a global script.

This script shouldn’t be created more than once. It contains event (in a non-persistent attribute) and callbacks (in a persistent attribute). The script method would help adding, editing and deleting these events and callbacks.

at_script_creation()

Hook called when the script is created.

at_server_start()

Set up the event system when starting.

Note that this hook is called every time the server restarts (including when it’s reloaded). This hook performs the following tasks:

• Create temporarily stored events.

• Generate locals (individual events’ namespace).

• Load eventfuncs, including user-defined ones.

• Re-schedule tasks that aren’t set to fire anymore.

• Effectively connect the handler to the main script.

get_events(obj)

Return a dictionary of events on this object.

Parameters

obj (Object or typeclass) – the connected object or a general typeclass.

Returns

A dictionary of the object’s events.

Notes

Events would define what the object can have as callbacks. Note, however, that chained callbacks will not appear in events and are handled separately.

You can also request the events of a typeclass, not a connected object. This is useful to get the global list of events for a typeclass that has no object yet.

get_variable(variable_name)

Return the variable defined in the locals.

This can be very useful to check the value of a variable that can be modified in an event, and whose value will be used in code. This system allows additional customization.

Parameters

variable_name (str) – the name of the variable to return.

Returns

The variable if found in the locals. None if not found in the locals.

Note

This will return the variable from the current locals. Keep in mind that locals are shared between events. As every event is called one by one, this doesn’t pose additional problems if you get the variable right after an event has been executed. If, however, you differ, there’s no guarantee the variable will be here or will mean the same thing.

get_callbacks(obj)

Return a dictionary of the object’s callbacks.

Parameters

obj (Object) – the connected objects.

Returns

A dictionary of the object’s callbacks.

Note

This method can be useful to override in some contexts, when several objects would share callbacks.

add_callback(obj, callback_name, code, author=None, valid=False, parameters='')

Add the specified callback.

Parameters

• obj (Object) – the Evennia typeclassed object to be extended.

• callback_name (str) – the name of the callback to add.

• code (str) – the Python code associated with this callback.

• author (Character or Account, optional) – the author of the callback.

• valid (bool, optional) – should the callback be connected?

• parameters (str, optional) – optional parameters.

Note

This method doesn’t check that the callback type exists.

edit_callback(obj, callback_name, number, code, author=None, valid=False)

Edit the specified callback.

Parameters

• obj (Object) – the Evennia typeclassed object to be edited.

• callback_name (str) – the name of the callback to edit.

• number (int) – the callback number to be changed.

• code (str) – the Python code associated with this callback.

• author (Character or Account, optional) – the author of the callback.

• valid (bool, optional) – should the callback be connected?

Raises

RuntimeError if the callback is locked. –

Note

This method doesn’t check that the callback type exists.

del_callback(obj, callback_name, number)

Delete the specified callback.

Parameters

• obj (Object) – the typeclassed object containing the callback.

• callback_name (str) – the name of the callback to delete.

• number (int) – the number of the callback to delete.

Raises

RuntimeError if the callback is locked. –

accept_callback(obj, callback_name, number)

Valid a callback.

Parameters

• obj (Object) – the object containing the callback.

• callback_name (str) – the name of the callback.

• number (int) – the number of the callback.

call(obj, callback_name, *args, **kwargs)

Call the connected callbacks.

Parameters

• obj (Object) – the Evennia typeclassed object.

• callback_name (str) – the callback name to call.

• *args – additional variables for this callback.

Keyword Arguments

• number (int, optional) – call just a specific callback.

• parameters (str, optional) – call a callback with parameters.

• locals (dict, optional) – a locals replacement.

Returns

True to report the callback was called without interruption, False otherwise.

handle_error(callback, trace)

Handle an error in a callback.

Parameters

• callback (dict) – the callback representation.

• trace (list) – the traceback containing the exception.

Notes

This method can be useful to override to change the default handling of errors. By default, the error message is sent to the character who last updated the callback, if connected. If not, display to the everror channel.

add_event(typeclass, name, variables, help_text, custom_call, custom_add)

Add a new event for a defined typeclass.

Parameters

• typeclass (str) – the path leading to the typeclass.

• name (str) – the name of the event to add.

• variables (list of str) – list of variable names for this event.

• help_text (str) – the long help text of the event.

• custom_call (callable or None) – the function to be called when the event fires.

• custom_add (callable or None) – the function to be called when a callback is added.

set_task(seconds, obj, callback_name)

Set and schedule a task to run.

Parameters

• seconds (int, float) – the delay in seconds from now.

• obj (Object) – the typecalssed object connected to the event.

• callback_name (str) – the callback’s name.

Notes

This method allows to schedule a “persistent” task. ‘utils.delay’ is called, but a copy of the task is kept in the event handler, and when the script restarts (after reload), the differed delay is called again. The dictionary of locals is frozen and will be available again when the task runs. This feature, however, is limited by the database: all data cannot be saved. Lambda functions, class methods, objects inside an instance and so on will not be kept in the locals dictionary.

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.contrib.base_systems.ingame_python.scripts.EventHandler'

typename = 'EventHandler'

class evennia.contrib.base_systems.ingame_python.scripts.TimeEventScript(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

Gametime-sensitive script.

at_script_creation()

The script is created.

at_repeat()

Call the event and reset interval.

It is necessary to restart the script to reset its interval only twice after a reload. When the script has undergone down time, there’s usually a slight shift in game time. Once the script restarts once, it will set the average time it needs for all its future intervals and should not need to be restarted. In short, a script that is created shouldn’t need to restart more than once, and a script that is reloaded should restart only twice.

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.contrib.base_systems.ingame_python.scripts.TimeEventScript'

typename = 'TimeEventScript'

evennia.contrib.base_systems.ingame_python.scripts.complete_task(task_id)

Mark the task in the event handler as complete.

Parameters

task_id (int) – the task ID.

Note

This function should be called automatically for individual tasks.