evennia.contrib.ingame_python package

Submodules

evennia.contrib.ingame_python.callbackhandler module

Module containing the CallbackHandler for individual objects.

class evennia.contrib.ingame_python.callbackhandler.Callback(obj, name, number, code, author, valid, parameters, created_on, updated_by, updated_on)

Bases: tuple

_asdict()

Return a new OrderedDict which maps field names to their values.

_field_defaults = {}

_fields = ('obj', 'name', 'number', 'code', 'author', 'valid', 'parameters', 'created_on', 'updated_by', 'updated_on')

_fields_defaults = {}

classmethod _make(iterable)

Make a new Callback object from a sequence or iterable

_replace(**kwds)

Return a new Callback object replacing specified fields with new values

property author

Alias for field number 4

property code

Alias for field number 3

property created_on

Alias for field number 7

property name

Alias for field number 1

property number

Alias for field number 2

property obj

Alias for field number 0

property parameters

Alias for field number 6

property updated_by

Alias for field number 8

property updated_on

Alias for field number 9

property valid

Alias for field number 5

class evennia.contrib.ingame_python.callbackhandler.CallbackHandler(obj)

Bases: object

The callback handler for a specific object.

The script that contains all callbacks will be reached through this handler. This handler is therefore a shortcut to be used by developers. This handler (accessible through obj.callbacks) is a shortcut to manipulating callbacks within this object, getting, adding, editing, deleting and calling them.

__init__(obj)

Initialize self. See help(type(self)) for accurate signature.

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

Add a new callback for this object.

Parameters

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

Returns

The callback definition that was added or None.

all()

Return all callbacks linked to this object.

Returns

callback}. The callback is returned as a namedtuple to simplify manipulation.

Return type

All callbacks in a dictionary callback_name

call(callback_name, *args, **kwargs)

Call the specified callback(s) bound to this object.

Parameters

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

• *args – additional variables for this callback.

Kwargs:

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. If the callbackHandler isn’t found, return None.

edit(callback_name, number, code, author=None, valid=False)

Edit an existing callback bound to this object.

Parameters

• 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?

Returns

The callback definition that was edited or None.

Raises

RuntimeError if the callback is locked. –

static format_callback(callback)

Return the callback namedtuple to represent the specified callback.

Parameters

callback (dict) – the callback definition.

The callback given in argument should be a dictionary containing the expected fields for a callback (code, author, valid…).

get(callback_name)

Return the callbacks associated with this name.

Parameters

callback_name (str) – the name of the callback.

Returns

A list of callbacks associated with this object and of this name.

Note

This method returns a list of callback objects (namedtuple representations). If the callback name cannot be found in the object’s callbacks, return an empty list.

get_variable(variable_name)

Return the variable value or None.

Parameters

variable_name (str) – the name of the variable.

Returns

Either the variable’s value or None.

remove(callback_name, number)

Delete the specified callback bound to this object.

Parameters

• 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. –

script = None

evennia.contrib.ingame_python.commands module

Module containing the commands of the in-game Python system.

class evennia.contrib.ingame_python.commands.CmdCallback(**kwargs)

Bases: evennia.commands.default.muxcommand.MuxCommand

Command to edit callbacks.

_keyaliases = ('@calls', '@callbacks', '@call', '@callback')

_matchset = {'@call', '@callback', '@callbacks', '@calls'}

accept_callback()

Accept a callback.

add_callback()

Add a callback.

aliases = ['@calls', '@callbacks', '@callback']

del_callback()

Delete a callback.

edit_callback()

Edit a callback.

func()

Command body.

get_help(caller, cmdset)

Return the help message for this command and this caller.

The help text of this specific command will vary depending on user permission.

Parameters

• caller (Object or Account) – the caller asking for help on the command.

• cmdset (CmdSet) – the command set (if you need additional commands).

Returns

the help text to provide the caller for this command.

Return type

docstring (str)

help_category = 'building'

key = '@call'

list_callbacks()

Display the list of callbacks connected to the object.

list_tasks()

List the active tasks.

lock_storage = 'cmd:perm(developer)'

locks = 'cmd:perm(developer)'

search_index_entry = {'aliases': '@calls @callbacks @callback', 'category': 'building', 'key': '@call', 'tags': '', 'text': '\n Command to edit callbacks.\n '}

evennia.contrib.ingame_python.commands._ev_load(caller)

evennia.contrib.ingame_python.commands._ev_quit(caller)

evennia.contrib.ingame_python.commands._ev_save(caller, buf)

Save and add the callback.

evennia.contrib.ingame_python.eventfuncs module

Module defining basic eventfuncs for the event system.

Eventfuncs are just Python functions that can be used inside of calllbacks.

evennia.contrib.ingame_python.eventfuncs.call_event(obj, event_name, seconds=0)

Call the specified event in X seconds.

Parameters

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

• event_name (str) – the event name to be called.

• seconds (int or float) – the number of seconds to wait before calling the event.

Notes

This eventfunc can be used to call other events from inside of an event in a given time. This will create a pause between events. This will not freeze the game, and you can expect characters to move around (unless you prevent them from doing so).

Variables that are accessible in your event using ‘call()’ will be kept and passed on to the event to call.

Chained callbacks are designed for this very purpose: they are never called automatically by the game, rather, they need to be called from inside another event.

evennia.contrib.ingame_python.eventfuncs.deny()

Deny, that is stop, the callback here.

Notes

This function will raise an exception to terminate the callback in a controlled way. If you use this function in an event called prior to a command, the command will be cancelled as well. Good situations to use the deny() function are in events that begins by can_, because they usually can be cancelled as easily as that.

evennia.contrib.ingame_python.eventfuncs.get(**kwargs)

Return an object with the given search option or None if None is found.

Kwargs:

Any searchable data or property (id, db_key, db_location…).

Returns

The object found that meet these criteria for research, or None if none is found.

Notes

This function is very useful to retrieve objects with a specific ID. You know that room #32 exists, but you don’t have it in the callback variables. Quite simple:

room = get(id=32)

This function doesn’t perform a search on objects, but a direct search in the database. It’s recommended to use it for objects you know exist, using their IDs or other unique attributes. Looking for objects by key is possible (use db_key as an argument) but remember several objects can share the same key.

evennia.contrib.ingame_python.scripts module

Scripts for the in-game Python system.

class evennia.contrib.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.

exception DoesNotExist

Bases: evennia.scripts.scripts.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.MultipleObjectsReturned

_meta = <Options for EventHandler>

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.

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.

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.

at_script_creation()

Hook called when the script is created.

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

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.

Kwargs:

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.

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

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.

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.

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.

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.

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

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.

typename = 'EventHandler'

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

Bases: evennia.scripts.scripts.DefaultScript

Gametime-sensitive script.

exception DoesNotExist

Bases: evennia.scripts.scripts.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.MultipleObjectsReturned

_meta = <Options for TimeEventScript>

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.

at_script_creation()

The script is created.

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

typename = 'TimeEventScript'

evennia.contrib.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.

evennia.contrib.ingame_python.tests module

Module containing the test cases for the in-game Python system.

class evennia.contrib.ingame_python.tests.TestCmdCallback(methodName='runTest')

Bases: evennia.commands.default.tests.CommandTest

Test the @callback command.

setUp()

Create the callback handler.

tearDown()

Stop the callback handler.

test_accept()

Accept an callback.

test_add()

Test to add an callback.

test_del()

Add and remove an callback.

test_list()

Test listing callbacks with different rights.

test_lock()

Test the lock of multiple editing.

class evennia.contrib.ingame_python.tests.TestDefaultCallbacks(methodName='runTest')

Bases: evennia.commands.default.tests.CommandTest

Test the default callbacks.

setUp()

Create the callback handler.

tearDown()

Stop the callback handler.

test_exit()

Test the callbacks of an exit.

class evennia.contrib.ingame_python.tests.TestEventHandler(methodName='runTest')

Bases: evennia.utils.test_resources.EvenniaTest

Test cases of the event handler to add, edit or delete events.

setUp()

Create the event handler.

tearDown()

Stop the event handler.

test_accept()

Accept an callback.

test_add_validation()

Add a callback while needing validation.

test_call()

Test to call amore complex callback.

test_del()

Try to delete a callback.

test_edit()

Test editing a callback.

test_edit_validation()

Edit a callback when validation isn’t automatic.

test_handler()

Test the object handler.

test_start()

Simply make sure the handler runs with proper initial values.

evennia.contrib.ingame_python.typeclasses module

Typeclasses for the in-game Python system.

To use them, change your base typeclasses to inherit from the classes in this module (EventObject, EventRoom, EventCharacter and EventExit) instead of the default ones in evennia core.

class evennia.contrib.ingame_python.typeclasses.EventCharacter(*args, **kwargs)

Bases: evennia.objects.objects.DefaultCharacter

Typeclass to represent a character and call event types.

exception DoesNotExist

Bases: evennia.objects.objects.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.MultipleObjectsReturned

_events = {'can_delete': (['character'], "\nCan the character be deleted?\nThis event is called before the character is deleted. You can use\n'deny()' in this event to prevent this character from being deleted.\nIf this event doesn't prevent the character from being deleted, its\n'delete' event is called right away.\n\nVariables you can use in this event:\n character: the character connected to this event.\n"), 'can_move': (['character', 'origin', 'destination'], "\nCan the character move?\nThis event is called before the character moves into another\nlocation. You can prevent the character from moving\nusing the 'deny()' eventfunc.\n\nVariables you can use in this event:\n character: the character connected to this event.\n origin: the current location of the character.\n destination: the future location of the character.\n"), 'can_part': (['character', 'departing'], "\nCan the departing charaacter leave this room?\nThis event is called before another character can move from the\nlocation where the current character also is. This event can be\nused to prevent someone to leave this room if, for instance, he/she\nhasn't paid, or he/she is going to a protected area, past a guard,\nand so on. Use 'deny()' to prevent the departing character from\nmoving.\n\nVariables you can use in this event:\n departing: the character who wants to leave this room.\n character: the character connected to this event.\n"), 'can_say': (['speaker', 'character', 'message'], '\nBefore another character can say something in the same location.\nThis event is called before another character says something in the\ncharacter\'s location. The "something" in question can be modified,\nor the action can be prevented by using \'deny()\'. To change the\ncontent of what the character says, simply change the variable\n\'message\' to another string of characters.\n\nVariables you can use in this event:\n speaker: the character who is using the say command.\n character: the character connected to this event.\n message: the text spoken by the character.\n', <function phrase_event>), 'delete': (['character'], "\nBefore deleting the character.\nThis event is called just before deleting this character. It shouldn't\nbe prevented (using the `deny()` function at this stage doesn't\nhave any effect). If you want to prevent deletion of this character,\nuse the event `can_delete` instead.\n\nVariables you can use in this event:\n character: the character connected to this event.\n"), 'greet': (['character', 'newcomer'], '\nA new character arrives in the location of this character.\nThis event is called when another character arrives in the location\nwhere the current character is. For instance, a puppeted character\narrives in the shop of a shopkeeper (assuming the shopkeeper is\na character). As its name suggests, this event can be very useful\nto have NPC greeting one another, or accounts, who come to visit.\n\nVariables you can use in this event:\n character: the character connected to this event.\n newcomer: the character arriving in the same location.\n'), 'move': (['character', 'origin', 'destination'], '\nAfter the character has moved into its new room.\nThis event is called when the character has moved into a new\nroom. It is too late to prevent the move at this point.\n\nVariables you can use in this event:\n character: the character connected to this event.\n origin: the old location of the character.\n destination: the new location of the character.\n'), 'puppeted': (['character'], '\nWhen the character has been puppeted by an account.\nThis event is called when an account has just puppeted this character.\nThis can commonly happen when an account connects onto this character,\nor when puppeting to a NPC or free character.\n\nVariables you can use in this event:\n character: the character connected to this event.\n'), 'say': (['speaker', 'character', 'message'], '\nAfter another character has said something in the character\'s room.\nThis event is called right after another character has said\nsomething in the same location.. The action cannot be prevented\nat this moment. Instead, this event is ideal to create keywords\nthat would trigger a character (like a NPC) in doing something\nif a specific phrase is spoken in the same location.\nTo use this event, you have to specify a list of keywords as\nparameters that should be present, as separate words, in the\nspoken phrase. For instance, you can set an event tthat would\nfire if the phrase spoken by the character contains "menu" or\n"dinner" or "lunch":\n @call/add ... = say menu, dinner, lunch\nThen if one of the words is present in what the character says,\nthis event will fire.\n\nVariables you can use in this event:\n speaker: the character speaking in this room.\n character: the character connected to this event.\n message: the text having been spoken by the character.\n', <function phrase_event>), 'time': (['character'], '\nA repeated event to be called regularly.\nThis event is scheduled to repeat at different times, specified\nas parameters. You can set it to run every day at 8:00 AM (game\ntime). You have to specify the time as an argument to @call/add, like:\n @call/add here = time 8:00\nThe parameter (8:00 here) must be a suite of digits separated by\nspaces, colons or dashes. Keep it as close from a recognizable\ndate format, like this:\n @call/add here = time 06-15 12:20\nThis event will fire every year on June the 15th at 12 PM (still\ngame time). Units have to be specified depending on your set calendar\n(ask a developer for more details).\n\nVariables you can use in this event:\n character: the character connected to this event.\n', None, <function time_event>), 'unpuppeted': (['character'], '\nWhen the character is about to be un-puppeted.\nThis event is called when an account is about to un-puppet the\ncharacter, which can happen if the account is disconnecting or\nchanging puppets.\n\nVariables you can use in this event:\n character: the character connected to this event.\n')}

_meta = <Options for EventCharacter>

announce_move_from(destination, msg=None, mapping=None)

Called if the move is to be announced. This is called while we are still standing in the old location.

Parameters

• destination (Object) – The place we are going to.

• msg (str, optional) – a replacement message.

• mapping (dict, optional) – additional mapping objects.

You can override this method and call its parent with a message to simply change the default message. In the string, you can use the following as mappings (between braces):

object: the object which is moving. exit: the exit from which the object is moving (if found). origin: the location of the object before the move. destination: the location of the object after moving.

announce_move_to(source_location, msg=None, mapping=None)

Called after the move if the move was not quiet. At this point we are standing in the new location.

Parameters

• source_location (Object) – The place we came from

• msg (str, optional) – the replacement message if location.

• mapping (dict, optional) – additional mapping objects.

You can override this method and call its parent with a message to simply change the default message. In the string, you can use the following as mappings (between braces):

object: the object which is moving. exit: the exit from which the object is moving (if found). origin: the location of the object before the move. destination: the location of the object after moving.

at_after_move(source_location)

Called after move has completed, regardless of quiet mode or not. Allows changes to the object due to the location it is now in.

Parameters

source_location (Object) – Wwhere we came from. This may be None.

at_before_move(destination)

Called just before starting to move this object to destination.

Parameters

destination (Object) – The object we are moving to

Returns

If we should move or not.

Return type

shouldmove (bool)

Notes

If this method returns False/None, the move is cancelled before it is even started.

at_before_say(message, **kwargs)

Before the object says something.

This hook is by default used by the ‘say’ and ‘whisper’ commands as used by this command it is called before the text is said/whispered and can be used to customize the outgoing text from the object. Returning None aborts the command.

Parameters

message (str) – The suggested say/whisper text spoken by self.

Kwargs:

whisper (bool): If True, this is a whisper rather than

a say. This is sent by the whisper command by default. Other verbal commands could use this hook in similar ways.

receiver (Object): If set, this is a target for the say/whisper.

Returns

The (possibly modified) text to be spoken.

Return type

message (str)

at_object_delete()

Called just before the database object is permanently delete()d from the database. If this method returns False, deletion is aborted.

at_post_puppet()

Called just after puppeting has been completed and all Account<->Object links have been established.

Note

You can use self.account and self.sessions.get() to get account and sessions at this point; the last entry in the list from self.sessions.get() is the latest Session puppeting this Object.

at_pre_unpuppet()

Called just before beginning to un-connect a puppeting from this Account.

Note

You can use self.account and self.sessions.get() to get account and sessions at this point; the last entry in the list from self.sessions.get() is the latest Session puppeting this Object.

at_say(message, **kwargs)

Display the actual say (or whisper) of self.

This hook should display the actual say/whisper of the object in its location. It should both alert the object (self) and its location that some text is spoken. The overriding of messages or mapping allows for simple customization of the hook without re-writing it completely.

Parameters

• message (str) – The text to be conveyed by self.

• msg_self (str, optional) – The message to echo to self.

• msg_location (str, optional) – The message to echo to self’s location.

• receiver (Object, optional) – An eventual receiver of the message (by default only used by whispers).

• msg_receiver (str, optional) – Specific message for receiver only.

• mapping (dict, optional) – Additional mapping in messages.

Kwargs:

whisper (bool): If this is a whisper rather than a say. Kwargs

can be used by other verbal commands in a similar way.

Notes

Messages can contain {} markers, which must If used, msg_self, msg_receiver and msg_location should contain references to other objects between braces, the way location.msg_contents would allow. For instance:

msg_self = ‘You say: “{speech}”’ msg_location = ‘{object} says: “{speech}”’ msg_receiver = ‘{object} whispers: “{speech}”’

The following mappings can be used in both messages:

object: the object speaking. location: the location where object is. speech: the text spoken by self.

You can use additional mappings if you want to add other information in your messages.

callbacks

Return the CallbackHandler.

path = 'evennia.contrib.ingame_python.typeclasses.EventCharacter'

typename = 'EventCharacter'

class evennia.contrib.ingame_python.typeclasses.EventExit(*args, **kwargs)

Bases: evennia.objects.objects.DefaultExit

Modified exit including management of events.

exception DoesNotExist

Bases: evennia.objects.objects.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.MultipleObjectsReturned

_events = {'can_traverse': (['character', 'exit', 'room'], '\nCan the character traverse through this exit?\nThis event is called when a character is about to traverse this\nexit. You can use the deny() function to deny the character from\nexitting for this time.\n\nVariables you can use in this event:\n character: the character that wants to traverse this exit.\n exit: the exit to be traversed.\n room: the room in which stands the character before moving.\n'), 'msg_arrive': (['character', 'exit', 'origin', 'destination', 'message', 'mapping'], '\nCustomize the message when a character arrives through this exit.\nThis event is called when a character arrives through this exit.\nTo customize the message that will be sent to the room where the\ncharacter arrives, change the value of the variable "message"\nto give it your custom message. The character itself will not be\nnotified. You can use mapping between braces, like this:\n message = "{character} climbs out of a hole."\nIn your mapping, you can use {character} (the character who has\narrived), {exit} (the exit), {origin} (the room in which\nthe character was), and {destination} (the room in which the character\nnow is). If you need to customize the message with other information,\nyou can also set "message" to None and send something else instead.\n\nVariables you can use in this event:\n character: the character who is arriving through this exit.\n exit: the exit having been traversed.\n origin: the past location of the character.\n destination: the current location of the character.\n message: the message to be displayed in the destination.\n mapping: a dictionary containing the mapping of the message.\n'), 'msg_leave': (['character', 'exit', 'origin', 'destination', 'message', 'mapping'], '\nCustomize the message when a character leaves through this exit.\nThis event is called when a character leaves through this exit.\nTo customize the message that will be sent to the room where the\ncharacter came from, change the value of the variable "message"\nto give it your custom message. The character itself will not be\nnotified. You can use mapping between braces, like this:\n message = "{character} falls into a hole!"\nIn your mapping, you can use {character} (the character who is\nabout to leave), {exit} (the exit), {origin} (the room in which\nthe character is), and {destination} (the room in which the character\nis heading for). If you need to customize the message with other\ninformation, you can also set "message" to None and send something\nelse instead.\n\nVariables you can use in this event:\n character: the character who is leaving through this exit.\n exit: the exit being traversed.\n origin: the location of the character.\n destination: the destination of the character.\n message: the message to be displayed in the location.\n mapping: a dictionary containing additional mapping.\n'), 'time': (['exit'], '\nA repeated event to be called regularly.\nThis event is scheduled to repeat at different times, specified\nas parameters. You can set it to run every day at 8:00 AM (game\ntime). You have to specify the time as an argument to @call/add, like:\n @call/add north = time 8:00\nThe parameter (8:00 here) must be a suite of digits separated by\nspaces, colons or dashes. Keep it as close from a recognizable\ndate format, like this:\n @call/add south = time 06-15 12:20\nThis event will fire every year on June the 15th at 12 PM (still\ngame time). Units have to be specified depending on your set calendar\n(ask a developer for more details).\n\nVariables you can use in this event:\n exit: the exit connected to this event.\n', None, <function time_event>), 'traverse': (['character', 'exit', 'origin', 'destination'], "\nAfter the characer has traversed through this exit.\nThis event is called after a character has traversed through this\nexit. Traversing cannot be prevented using 'deny()' at this\npoint. The character will be in a different room and she will\nhave received the room's description when this event is called.\n\nVariables you can use in this event:\n character: the character who has traversed through this exit.\n exit: the exit that was just traversed through.\n origin: the exit's location (where the character was before moving).\n destination: the character's location after moving.\n")}

_meta = <Options for EventExit>

at_traverse(traversing_object, target_location)

This hook is responsible for handling the actual traversal, normally by calling traversing_object.move_to(target_location). It is normally only implemented by Exit objects. If it returns False (usually because move_to returned False), at_after_traverse below should not be called and instead at_failed_traverse should be called.

Parameters

• traversing_object (Object) – Object traversing us.

• target_location (Object) – Where target is going.

callbacks

Return the CallbackHandler.

path = 'evennia.contrib.ingame_python.typeclasses.EventExit'

typename = 'EventExit'

class evennia.contrib.ingame_python.typeclasses.EventObject(*args, **kwargs)

Bases: evennia.objects.objects.DefaultObject

Default object with management of events.

exception DoesNotExist

Bases: evennia.objects.objects.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.MultipleObjectsReturned

_events = {'drop': (['character', 'obj'], '\nWhen a character drops this object.\nThis event is called when a character drops this object. It is\ncalled after the command has ended and displayed its message, and\nthe action cannot be prevented at this time.\n\nVariables you can use in this event:\n character: the character having dropped the object.\n obj: the object connected to this event.\n'), 'get': (['character', 'obj'], '\nWhen a character gets this object.\nThis event is called when a character gets this object. It is\ncalled after the command has ended and displayed its message, and\nthe action cannot be prevented at this time.\n\nVariables you can use in this event:\n character: the character having picked up the object.\n obj: the object connected to this event.\n'), 'time': (['object'], '\nA repeated event to be called regularly.\nThis event is scheduled to repeat at different times, specified\nas parameters. You can set it to run every day at 8:00 AM (game\ntime). You have to specify the time as an argument to @call/add, like:\n @call/add here = time 8:00\nThe parameter (8:00 here) must be a suite of digits separated by\nspaces, colons or dashes. Keep it as close from a recognizable\ndate format, like this:\n @call/add here = time 06-15 12:20\nThis event will fire every year on June the 15th at 12 PM (still\ngame time). Units have to be specified depending on your set calendar\n(ask a developer for more details).\n\nVariables you can use in this event:\n object: the object connected to this event.\n', None, <function time_event>)}

_meta = <Options for EventObject>

at_drop(dropper)

Called by the default drop command when this object has been dropped.

Parameters

dropper (Object) – The object which just dropped this object.

Notes

This hook cannot stop the drop from happening. Use permissions from that.

at_get(getter)

Called by the default get command when this object has been picked up.

Parameters

getter (Object) – The object getting this object.

Notes

This hook cannot stop the pickup from happening. Use permissions for that.

callbacks

Return the CallbackHandler.

path = 'evennia.contrib.ingame_python.typeclasses.EventObject'

typename = 'EventObject'

class evennia.contrib.ingame_python.typeclasses.EventRoom(*args, **kwargs)

Bases: evennia.objects.objects.DefaultRoom

Default room with management of events.

exception DoesNotExist

Bases: evennia.objects.objects.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.MultipleObjectsReturned

_events = {'can_delete': (['room'], "\nCan the room be deleted?\nThis event is called before the room is deleted. You can use\n'deny()' in this event to prevent this room from being deleted.\nIf this event doesn't prevent the room from being deleted, its\n'delete' event is called right away.\n\nVariables you can use in this event:\n room: the room connected to this event.\n"), 'can_move': (['character', 'room'], "\nCan the character move into this room?\nThis event is called before the character can move into this\nspecific room. You can prevent the move by using the 'deny()'\nfunction.\n\nVariables you can use in this event:\n character: the character who wants to move in this room.\n room: the room connected to this event.\n"), 'can_say': (['character', 'room', 'message'], '\nBefore a character can say something in this room.\nThis event is called before a character says something in this\nroom. The "something" in question can be modified, or the action\ncan be prevented by using \'deny()\'. To change the content of what\nthe character says, simply change the variable \'message\' to another\nstring of characters.\n\nVariables you can use in this event:\n character: the character who is using the say command.\n room: the room connected to this event.\n message: the text spoken by the character.\n', <function phrase_event>), 'delete': (['room'], "\nBefore deleting the room.\nThis event is called just before deleting this room. It shouldn't\nbe prevented (using the `deny()` function at this stage doesn't\nhave any effect). If you want to prevent deletion of this room,\nuse the event `can_delete` instead.\n\nVariables you can use in this event:\n room: the room connected to this event.\n"), 'move': (['character', 'origin', 'destination'], '\nAfter the character has moved into this room.\nThis event is called when the character has moved into this\nroom. It is too late to prevent the move at this point.\n\nVariables you can use in this event:\n character: the character connected to this event.\n origin: the old location of the character.\n destination: the new location of the character.\n'), 'puppeted_in': (['character', 'room'], "\nAfter the character has been puppeted in this room.\nThis event is called after a character has been puppeted in this\nroom. This can happen when an account, having connected, begins\nto puppet a character. The character's location at this point,\nif it's a room, will see this event fire.\n\nVariables you can use in this event:\n character: the character who have just been puppeted in this room.\n room: the room connected to this event.\n"), 'say': (['character', 'room', 'message'], '\nAfter the character has said something in the room.\nThis event is called right after a character has said something\nin this room. The action cannot be prevented at this moment.\nInstead, this event is ideal to create actions that will respond\nto something being said aloud. To use this event, you have to\nspecify a list of keywords as parameters that should be present,\nas separate words, in the spoken phrase. For instance, you can\nset an event tthat would fire if the phrase spoken by the character\ncontains "menu" or "dinner" or "lunch":\n @call/add ... = say menu, dinner, lunch\nThen if one of the words is present in what the character says,\nthis event will fire.\n\nVariables you can use in this event:\n character: the character having spoken in this room.\n room: the room connected to this event.\n message: the text having been spoken by the character.\n', <function phrase_event>), 'time': (['room'], '\nA repeated event to be called regularly.\nThis event is scheduled to repeat at different times, specified\nas parameters. You can set it to run every day at 8:00 AM (game\ntime). You have to specify the time as an argument to @call/add, like:\n @call/add here = time 8:00\nThe parameter (8:00 here) must be a suite of digits separated by\nspaces, colons or dashes. Keep it as close from a recognizable\ndate format, like this:\n @call/add here = time 06-15 12:20\nThis event will fire every year on June the 15th at 12 PM (still\ngame time). Units have to be specified depending on your set calendar\n(ask a developer for more details).\n\nVariables you can use in this event:\n room: the room connected to this event.\n', None, <function time_event>), 'unpuppeted_in': (['character', 'room'], "\nBefore the character is un-puppeted in this room.\nThis event is called before a character is un-puppeted in this\nroom. This can happen when an account, puppeting a character, is\ndisconnecting. The character's location at this point, if it's a\nroom, will see this event fire.\n\nVariables you can use in this event:\n character: the character who is about to be un-puppeted in this room.\n room: the room connected to this event.\n")}

_meta = <Options for EventRoom>

at_object_delete()

Called just before the database object is permanently delete()d from the database. If this method returns False, deletion is aborted.

callbacks

Return the CallbackHandler.

path = 'evennia.contrib.ingame_python.typeclasses.EventRoom'

typename = 'EventRoom'

evennia.contrib.ingame_python.utils module

Functions to extend the event system.

These functions are to be used by developers to customize events and callbacks.

exception evennia.contrib.ingame_python.utils.InterruptEvent

Bases: RuntimeError

Interrupt the current event.

You shouldn’t have to use this exception directly, probably use the deny() function that handles it instead.

evennia.contrib.ingame_python.utils.get_event_handler()

Return the event handler or None.

evennia.contrib.ingame_python.utils.get_next_wait(format)

Get the length of time in seconds before format.

Parameters

format (str) – a time format matching the set calendar.

Returns

the number of seconds until the event. usual (int or float): the usual number of seconds between events. format (str): a string format representing the time.

Return type

until (int or float)

Notes

The time format could be something like “2018-01-08 12:00”. The number of units set in the calendar affects the way seconds are calculated.

evennia.contrib.ingame_python.utils.keyword_event(callbacks, parameters)

Custom call for events with keywords (like push, or pull, or turn…).

Parameters

• callbacks (list of dict) – the list of callbacks to be called.

• parameters (str) – the actual parameters entered to trigger the callback.

Returns

A list containing the callback dictionaries to be called.

Notes

This function should be imported and added as a custom_call parameter to add the event when the event supports keywords as parameters. Keywords in parameters are one or more words separated by a comma. For instance, a ‘push 1, one’ callback can be set to trigger when the player ‘push 1’ or ‘push one’.

evennia.contrib.ingame_python.utils.phrase_event(callbacks, parameters)

Custom call for events with keywords in sentences (like say or whisper).

Parameters

• callbacks (list of dict) – the list of callbacks to be called.

• parameters (str) – the actual parameters entered to trigger the callback.

Returns

A list containing the callback dictionaries to be called.

Notes

This function should be imported and added as a custom_call parameter to add the event when the event supports keywords in phrases as parameters. Keywords in parameters are one or more words separated by a comma. For instance, a ‘say yes, okay’ callback can be set to trigger when the player says something containing either “yes” or “okay” (maybe ‘say I don’t like it, but okay’).

evennia.contrib.ingame_python.utils.register_events(path_or_typeclass)

Register the events in this typeclass.

Parameters

path_or_typeclass (str or type) – the Python path leading to the class containing events, or the class itself.

Returns

The typeclass itself.

Notes

This function will read events from the _events class variable defined in the typeclass given in parameters. It will add the events, either to the script if it exists, or to some temporary storage, waiting for the script to be initialized.

evennia.contrib.ingame_python.utils.time_event(obj, event_name, number, parameters)

Create a time-related event.

Parameters

• obj (Object) – the object on which sits the event.

• event_name (str) – the event’s name.

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

• parameters (str) – the parameter of the event.