Events

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.

The events API may be found in the  module, the recommended import line is   followed by   for a convenient shortcut. The examples below will assume that these two lines are used.

The  method will register   to fire off whenever an event of name   is dispatched. The  function will always be given at least one parameters: the   object (as defined below) that was constructed for the current event. The  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,  , and   that it has previously registered.

The opposite of, this will remove the listener with the given  ,  , and. 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).

(class)
Creates a new  instance with the given   and. The  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. The events list below will describe what data is passed to callbacks (if any) for any particular event.

(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  instance followed by. 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.

(instance variable)
An event listener can set this to  to prevent the rest of the registered listeners from firing on this event.

(instance variable)
An event listener can set this to  to prevent the &quot;default&quot; 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.

Alphabetical list of events
The first argument to be passed in to the callback will always be the  instance (this is hardcoded). This is the instance that can be manipulated to communicate with the dispatcher.

amnesiac_turn
This event is fired in, if amnesiacs are to be converted to their final roles. It is fired before the default logic runs, and once for each amnesiac to convert. Setting the instance variable  to   will prevent the default logic from executing.

Callback parameters:,  ,  ,


 * : The  object
 * : Holds game state information (reference to the  module)
 * : The nick of the amnesiac to turn
 * : The role the amnesiac is to turn into


 * Event data:**

There is no data associated with this event.

chk_traitor
This event is fired inside of the  function, and can be used to supplement or supplant the default checks to see if wolf cubs or traitors need to turn. This event is fired before the default logic runs, and setting the instance variable  to   can, as advertised, prevent the default logic from running.

Callback parameters:,  ,  ,  ,


 * : The  object
 * : The  instance, which is connected to the channel
 * : Holds game state information (reference to the  module)
 * : Number of wolf cubs currently alive
 * : Number of traitors currently alive


 * Event data:**

There is no data associated with this event.

chk_win
This event is fired inside of the  function, and can be used to supplement or supplant the default checks to see if the game is over and who (if anyone) won. This event is fired after the default winner logic has already ran, but before it stops the game or credits any particular team for winning. Modifying the instance variable  has no effect for this event.

Callback parameters:,  ,  ,  ,


 * : The  object
 * : Holds game state information (reference to the  module)
 * : Number of players currently able to vote (e.g. alive players minus wounded and people with narcolepsy totem)
 * : Number of wolfteam members currently able to vote
 * : Number of alive wolves, werecrows, alpha wolves, werekittens, wolf mystics and fallen angels (no cubs), does not factor in ability to vote (so this number could include wolves afflicted with narcolepsy, as an example)


 * Event data:**


 * The  key contains the name of the team that won the game, or   if the game is not yet over. If an individual player won (e.g. fool), it is their nick prefixed with [mailto:%22@%22 &quot;@&quot;].
 * The  key contains the game over message to be played to the channel to signify the game is over and which team won.

role_attribution
This event is fired when starting the game, and can be used to override the default role attribution mechanism. Setting the instance variable  to   will prevent the normal role attribution logic from running.

Callback parameters:,  ,  ,


 * : The  object
 * : The  instance, which is connected to the channel
 * : Holds game state information (reference to the  module)
 * : List of joined players


 * Event data:**


 * The  key is a dict, which is a mapping of  . It should be mutated, not replaced, as the code works on the passed-in object and does not read back the data. Setting the instance variable   to   will prevent the default logic from occuring. If   is left to , it is possible to only partially mutate the   dict, and the remaining roles will be filled in with the current   found in  . If   doesn't have all the roles defined in   (or too many), the bot will refuse to start the game.