Events
This page is intended for developers, and contains technical content. Understanding this page is not required to play Werewolf, nor will it give you any knowledge that can be used for a gameplay advantage.
Lykos contains an events system, which allows for hooking code into existing methods easily and without making messy-looking functions. This system is modeled after javascript events, and uses much of the same nomenclature. This page gives an overview of the events API, and afterwards an alphabetical listing of all currently-defined events in lykos. For examples on how to use events and the wide amount of flexibility given to the system, see src/gamemodes.py, much of the complexity of modes that add extra stuff (such as sleepy and maelstrom) is implemented via events.
The events API may be found in the src.events module, the recommended import line is from src import events followed by Event = events.Event for a convenient shortcut. For events that should always run (such as when adding new roles), use from src.decorators import event_listener to get the event_listener decorator. The examples below will assume that these lines are used.
events.add_listener(event, callback, priority=5)
The events.add_listener method will register callback to fire off whenever an event of name event is dispatched. The callback function will always be given at least one parameter: the Event object (as defined below) that was constructed for the current event. The priority parameter may be used to order event listeners -- lower numbers are run before higher numbers. The default is usually fine unless you know you need to execute first or last. This function is a no-op if passed in an event, callback, and priority that it has previously registered.
events.remove_listener(event, callback, priority=5)
The opposite of events.add_listener, this will remove the listener with the given event, callback, and priority. This function does not return a value, and will not throw an error if it cannot find a matching listener (it will no-op in that case).
@event_listener(event, priority=5)
The event listener decorator is useful for registering a listener that likely does not need to be removed. They can be removed just in case by calling .remove() on the decorated function name, but the general assumption (unlike add_listener) is that it's there to stay.
Event(name, data, **kwargs) (class)
Creates a new Event instance with the given name, data, and params (the keyword args). The data parameter is meant to be any mutable data you wish to pass to event callbacks. Typically this is a dict, but it doesn't have to be. Keyword arguments will be made available as attributes on the params member. The events list below will describe what data is passed to callbacks (if any) for any particular event.
Event.dispatch(*args) (instance method)
Dispatches a previously constructed event, which calls all currently-registered event listeners on it. The listener callback functions will be passed in the Event instance followed by *args. What these are vary by event, see below for more information for any particular event. When dispatching an event, it is typically good to include enough state information as to be useful as part of the args.
Event.stop_processing (instance variable)
An event listener can set this to True to prevent the rest of the registered listeners from firing on this event.
Event.prevent_default (instance variable)
An event listener can set this to True to prevent the "default" action of the event from occurring. This is not always used by every event, see the documentation below to see what this does for any particular event.