LuaAPI/wesnoth/game events - Revision history

Celtic Minstrel: Undo revision 73922 by ZombieKnight (talk)

2024-11-03T13:44:48Z

Undo revision 73922 by ZombieKnight (talk)

ZombieKnight: /* wesnoth.game_events.fire */

2024-11-03T12:38:06Z

‎wesnoth.game_events.fire

Celtic Minstrel: /* wesnoth.game_events.on_mouse_button */ Fix missing return type on the callback

2024-09-13T03:21:30Z

‎wesnoth.game_events.on_mouse_button: Fix missing return type on the callback

Celtic Minstrel: /* wesnoth.game_events.add */ Document priority parameter

2024-08-13T13:15:37Z

‎wesnoth.game_events.add: Document priority parameter

Celtic Minstrel: /* wesnoth.game_events.add_repeating */ Document optional priority and undo handler parameters

2024-08-13T13:11:49Z

‎wesnoth.game_events.add_repeating: Document optional priority and undo handler parameters

Celtic Minstrel: Categorize

2024-04-20T14:14:04Z

Categorize

White haired uncle: onload -> on_load for clarity

2024-02-26T16:09:58Z

onload -> on_load for clarity

Daniel.santos: /* wesnoth.game_events.on_mouse_button */ clean up a bit

2023-10-18T14:06:34Z

‎wesnoth.game_events.on_mouse_button: clean up a bit

Daniel.santos: /* wesnoth.game_events.on_mouse_button */ list events in order they usually occur

2023-10-18T02:53:34Z

‎wesnoth.game_events.on_mouse_button: list events in order they usually occur

Daniel.santos: Add initial description of on_mouse_button

2023-10-18T02:52:10Z

Add initial description of on_mouse_button

@@ Line 61: / Line 61: @@
 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''' (weapon) 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.
+The most common use of event data is to pass in the weapons for an attack event - to do this, add a '''primary_attack''' and '''secondary_attack''' 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 ===

@@ Line 61: / Line 61: @@
 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 '''primary_attack''' and '''secondary_attack''' 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.
+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''' (weapon) 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 ===

@@ Line 156: / Line 156: @@
 {{DevFeature1.17|22}}
-* {{LuaGameOnly}} '''wesnoth.game_events.on_mouse_button''' &harr; '''function'''(''x'', ''y'', ''button'', ''event'')
+* {{LuaGameOnly}} '''wesnoth.game_events.on_mouse_button''' &harr; '''function'''(''x'', ''y'', ''button'', ''event'') &rarr; ''consume?''
 Registers a handler for mouse button events occurring on a valid map tile and when the UI is in a normal play state. It does not receive notification for any events on a GUI, the minimap, or when a message is up.

@@ Line 18: / Line 18: @@
 * '''menu_item''': True if this is a menu item (an ID is required); this means removing the menu item will automatically remove this event. Default false. Note that this does not, by itself, mean the event will be triggered when the menu item is selected. The '''name''' determines when the event is triggered.
 * '''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. It can contain any supported event filter tag, or '''[insert_tag]''' tags that expand to a supported event filter tag.

@@ Line 28: / Line 28: @@
 === wesnoth.game_events.add_repeating ===
-* {{LuaGameOnly}} '''wesnoth.game_events.add_repeating'''(''event name'', ''handler function'')
+* {{LuaGameOnly}} '''wesnoth.game_events.add_repeating'''(''event name'', ''handler function'', [''priority''], [''on undo function''])
 Registers a recurring event (as <syntaxhighlight lang=wml inline>[event]first_time_only=no</syntaxhighlight>) 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 in [[#wesnoth.game_events.add|game_events.add]].

← Older revision		Revision as of 14:14, 20 April 2024
Line 207:		Line 207:

	This function is called when the mouse moves. More specifically, it's called whenever the currently hovered hex changes. This callback does not share most of the shortcomings of the '''on_mouse_action''' callback, but it is still unsynced.		This function is called when the mouse moves. More specifically, it's called whenever the currently hovered hex changes. This callback does not share most of the shortcomings of the '''on_mouse_action''' callback, but it is still unsynced.
		+
		+	[[Category:Lua Reference]]

@@ Line 88: / Line 88: @@
 * {{LuaGameOnly}} '''wesnoth.game_events.on_load''' &harr; '''function'''(''scenario wml'')
-This is a lower-level method of handling the load game event and the [[../#wesnoth.persistent_tags|'''wesnoth.persistent_tags''']] mechanism. It is called whenever the game is loaded, before the onload event is triggered. If overriding this, be sure to call the original version of the function, as '''wesnoth.persistent_tags''' also depends on this event.
+This is a lower-level method of handling the load game event and the [[../#wesnoth.persistent_tags|'''wesnoth.persistent_tags''']] mechanism. It is called whenever the game is loaded, before the on_load event is triggered. If overriding this, be sure to call the original version of the function, as '''wesnoth.persistent_tags''' also depends on this event.
 The scenario WML passed to this function is not the complete WML of the scenario but only the tags that the core Wesnoth engine does not know how to handle. You will never find an [event] or [side] tag in this table, for example. Although some core tags are already handled using this mechanism, you should not rely on this - for example, reading [item] tags in '''on_load''' is not guaranteed to work in future versions. The following is a list of all such tags:

@@ Line 189: / Line 189: @@
 At this time, there is no Lua support for drag and drop events. When a right, mouse4 or mouse5 down occurs on one tile, but then an up event on a different one (i.e., the mouse is dragged), there will be no click event. For a proper click event, both down and up must occur on the same tile. While this restriction is not currently possible with left and middle clicks, the behavior may be changed in a future release so that all mouse button events are handled consistently.
-<big>'''WARNING'''</big>: ''Your event handler should be as brief as possible!'' It should check for the exact events it is looking for and immediately return false for all others. It should not attempt to display any messages, ask the user questions, pontificate the meaning of life, sell memorabilia on ebay, etc., or undefined behavior may result. Any intensive operations should be delegated to a [https://www.lua.org/pil/9.1.html coroutine] or otherwise scheduled to occur later (e.g., setting a variable).
+<big>'''WARNING'''</big>: ''Your event handler should be as brief as possible!'' It should check for the exact events it is looking for and immediately return false for all others. It should not attempt to display any messages, ask the user questions, pontificate the meaning of life, sell memorabilia on ebay, etc. Any intensive operations (requiring more than a few milliseconds) should be delegated to a [https://www.lua.org/pil/9.1.html coroutine] or otherwise scheduled to occur later (e.g., setting by a "flag" variable).
 <syntaxhighlight lang=lua>wesnoth.game_events.on_mouse_button = function(x, y, button, event)
-     if not (button == "right" and event == "click) then
+     if not (button == "right" and event == "click") then
          return false
      end
-−
-     wml.variables['unit.hitpoints'] = 1
+     -- Do stuff here
      return false
 end

@@ Line 161: / Line 161: @@
 * '''x''', '''y''': The map coordinates the event occurred on
 * '''button''': The name of the button as a string, which will be one of <syntaxhighlight lang=lua inline>"left"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"middle"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"right"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"mouse4"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"mouse5"</syntaxhighlight>.
-* '''event''': One of <syntaxhighlight lang=lua inline>"up"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"down"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"click"</syntaxhighlight>
+* '''event''': One of <syntaxhighlight lang=lua inline>"down"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"up"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"click"</syntaxhighlight>
 The usual order of events is down, up, and then click. However, left and middle clicks ''currently'' occur at the mouse down, so the order is different for these two. The most common use case will be to handle click events and ignore the rest. The callback may ''consume'' a click event, preventing the game engine from invoking it's default action, by returning ''true''. The return value when called for down or up events is ignored.

← Older revision		Revision as of 02:52, 18 October 2023
Line 150:		Line 150:

	Some discussion of the problems with this callback can be found in [https://github.com/wesnoth/wesnoth/issues/2325 this enhancement request].		Some discussion of the problems with this callback can be found in [https://github.com/wesnoth/wesnoth/issues/2325 this enhancement request].
		+
		+	=== wesnoth.game_events.on_mouse_button ===
		+
		+	{{DevFeature1.17\|22}}
		+
		+	* {{LuaGameOnly}} '''wesnoth.game_events.on_mouse_button''' ↔ '''function'''(''x'', ''y'', ''button'', ''event'')
		+
		+	Registers a handler for mouse button events occurring on a valid map tile and when the UI is in a normal play state. It does not receive notification for any events on a GUI, the minimap, or when a message is up.
		+
		+	* '''x''', '''y''': The map coordinates the event occurred on
		+	* '''button''': The name of the button as a string, which will be one of <syntaxhighlight lang=lua inline>"left"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"middle"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"right"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"mouse4"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"mouse5"</syntaxhighlight>.
		+	* '''event''': One of <syntaxhighlight lang=lua inline>"up"</syntaxhighlight>, <syntaxhighlight lang=lua inline>"down"</syntaxhighlight>, or <syntaxhighlight lang=lua inline>"click"</syntaxhighlight>
		+
		+	The usual order of events is down, up, and then click. However, left and middle clicks ''currently'' occur at the mouse down, so the order is different for these two. The most common use case will be to handle click events and ignore the rest. The callback may ''consume'' a click event, preventing the game engine from invoking it's default action, by returning ''true''. The return value when called for down or up events is ignored.
		+
		+	{\| class="wikitable"
		+	\|+ Order of button events
		+	\|-
		+	! Button
		+	! Order
		+	\|-
		+	\| left
		+	\| down, click, up
		+	\|-
		+	\| middle
		+	\| down, click, up
		+	\|-
		+	\| right
		+	\| down, up, click
		+	\|-
		+	\| mouse4
		+	\| down, up, click
		+	\|-
		+	\| mouse5
		+	\| down, up, click
		+	\|}
		+
		+	At this time, there is no Lua support for drag and drop events. When a right, mouse4 or mouse5 down occurs on one tile, but then an up event on a different one (i.e., the mouse is dragged), there will be no click event. For a proper click event, both down and up must occur on the same tile. While this restriction is not currently possible with left and middle clicks, the behavior may be changed in a future release so that all mouse button events are handled consistently.
		+
		+	<big>'''WARNING'''</big>: ''Your event handler should be as brief as possible!'' It should check for the exact events it is looking for and immediately return false for all others. It should not attempt to display any messages, ask the user questions, pontificate the meaning of life, sell memorabilia on ebay, etc., or undefined behavior may result. Any intensive operations should be delegated to a [https://www.lua.org/pil/9.1.html coroutine] or otherwise scheduled to occur later (e.g., setting a variable).
		+
		+	<syntaxhighlight lang=lua>wesnoth.game_events.on_mouse_button = function(x, y, button, event)
		+	if not (button == "right" and event == "click) then
		+	return false
		+	end
		+
		+	wml.variables['unit.hitpoints'] = 1
		+	return false
		+	end
		+	</syntaxhighlight>

	=== wesnoth.game_events.on_mouse_move ===		=== wesnoth.game_events.on_mouse_move ===