LuaAPI/wesnoth/game events

NOTE: This is only a draft documentation page for an API that is not yet available in any released version. However, some parts of the API are already available under other names:

• wesnoth.add_event_handler takes an [event] tag as the argument and is otherwise equivalent to the last form of wesnoth.game_events.add
• wesnoth.remove_event_handler is equivalent to wesnoth.game_events.remove
• wesnoth.fire_event is equivalent to wesnoth.game_events.fire
• wesnoth.fire_event_by_id is equivalent to wesnoth.game_events.fire_by_id

The game_events module contains functions for manipulating game event handlers.

wesnoth.game_events.add

Registers a new event handler, as EventWML. There are three ways to call this function. The first and most flexible is to use the options table. The second method is suitable for quick, recurring events, or for menu items. The third is the underlying mechanism of the event tag and mostly exists just for quick compatibility.

• wesnoth.game_events.add(options table)

Registers an event handler in the scenario. The argument is a table containing several optional named arguments. The possible arguments are:

• name: The name of the event to handle. This can be a string (a single event name, a comma-separated list, or an expression of WML variables that can expand to one or more event names) or a table of event names as individual strings (which can also possibly contain WML variables). Default is an empty string, but note that either a name or ID is required.
• id: The event ID, used to remove it later; also, if an event with the same ID is already registered, then this event will be ignored and will not be registered. Default is an empty string.
• menu_item: True if this is a menu item (an ID is required); this means removing the menu item will automatically remove this event, and selecting the menu item will trigger this event. Default false.
• first_time_only: Controls whether this event will fire more than once. Default true, meaning that it fires only once and is then removed.
• filter: Filters that, if not passed, will prevent the event from firing. There are three possible formats for this:
  • A WML table with filter tags and attributes (like an [event] tag with no action content and no name or id). In this case the filters are parsed in the same way as they would be for an [event] tag.
  • A table of the form {filter_type = filter_contents}. The possible filter types are: condition, side, unit, second_unit, attack, and second_attack. Each filter is a WML table.
  • A function that optionally takes a WML table as argument and returns a boolean value.
• filter_args: An optional WML table that will be passed to the filter function. This is used only if the filter is a function.
• content: The content of the event. If action is specified, this is a WML table passed verbatim to that function when the event fires. If action is not specified, this will be interpreted as ActionWML to be executed when the event fires.
• action: The function to call when the event triggers. It can take a WML table as argument (the content) but does not return anything.

• wesnoth.game_events.add(event name, function, false)

Registers a recurring event (as [event]first_time_only=no) with the specified event name which will call the function when it triggers. The event name is the same as the name key in the options table.

The function takes no argument and returns nothing.

• wesnoth.game_events.add(menu item id, function, true)

Registers a recurring event for a menu item. The first argument is the menu item ID, rather than an event name, so it cannot be an array or contain any commas. (TODO: Can it contain variables?) The event will be automatically linked to the menu item with the same ID and will be removed from the scenario if that menu item is removed.

The function takes no argument and returns nothing.

• wesnoth.game_events.add(delayed variable substitution?, event config)

This is simply the underlying implementation of the event tag. The first argument is the value of the delayed_variable_substitution key, and the second argument is the entire content of an event tag. It will parse name, id, first_time_only, filters, and ActionWML from this config and use that to register an event.

wesnoth.game_events.remove

• wesnoth.game_events.remove(id)

Removes the event handler with the given ID, if it exists. If it does not exist, this does nothing.

wesnoth.game_events.fire

• wesnoth.game_events.fire(name, [first location, [second location]], [event data]) → processed?

Fires all events with the given name, passing any specified data into the event. If the locations passed in have a unit on them, that unit will become the primary or secondary unit of the event. The event data is a config that can contain arbitrary data.

The most common use of event data is to pass in the weapons for an attack event - to do this, add a first and second tag to the config. Other data used by built-in events includes the damage_inflicted value in an attack hit event, or the owner_side value in a village capture event. For custom events, you can put anything you want in here.

wesnoth.game_events.fire_by_id

• wesnoth.game_events.fire(id, [first location, [second location]], [event data]) → processed?

Same as #wesnoth.game_events.fire, but triggers the event with a specific ID instead of all events with the given name.