LuaWML/Events - Revision history

Celtic Minstrel: Add move notice

2021-02-12T13:26:59Z

Add move notice

2019-11-13T01:52:39Z

‎wesnoth.wml_actions: Fix reference to loooong-deprecated function

2019-05-07T13:58:22Z

‎on_event.lua

2018-05-17T01:45:47Z

‎wesnoth.game_events

2018-05-15T14:28:27Z

Document some gotchas of on_mouse_action

2018-04-18T02:35:09Z

‎wesnoth.persistent_tags: fix markup

2018-04-18T02:33:48Z

Document wesnoth.persistent_tags

2018-03-18T21:47:31Z

‎wesnoth.game_events: Add some other engine-reserved save/load tags

2018-03-18T21:45:08Z

Syntax highlighting

2018-01-09T03:43:30Z

‎wesnoth.game_events: on_mouse_action

← Older revision		Revision as of 13:26, 12 February 2021
Line 1:		Line 1:
		+	{{Template:LuaMove}}
		+
	This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.		This page describes the [[LuaWML]] functions and helpers for interacting with events and action handlers.

@@ Line 13: / Line 13: @@
 ==== wesnoth.wml_actions ====
-This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is similar to calling [[#wesnoth.fire]], while setting entries of the table is similar to calling [[#wesnoth.register_wml_action]].
+This is not a function but an associative table indexed by WML action names. It contains functions performing the corresponding actions. Using these functions is slightly different from calling [[#wesnoth.fire]], which automatically casts the input to a vconfig before passing it to the function.
 <syntaxhighlight lang=lua>

@@ Line 301: / Line 301: @@
 </syntaxhighlight>
-The passed function will be called with '''wesnoth.current.event_context''' as paremter. THis isn't as powerful as wml event handlers though: Filters must be implemented with an if in the function body (as shown above with ''context.x1 == 10 and context.x1 == 11''). There is no way to remove those event handlers, in particular they behave like ''first_time_only=no'' events. They are not persisted on save/load so they must be re-defined on each load (e.g. in a preload event).
+The passed function will be called with '''wesnoth.current.event_context''' as paremter. This isn't as powerful as wml event handlers though: Filters must be implemented with an if in the function body (as shown above with ''context.x1 == 10 and context.x1 == 11''). There is no way to remove those event handlers, in particular they behave like ''first_time_only=no'' events. They are not persisted on save/load so they must be re-defined on each load (e.g. in a preload event).
 [[Category: Lua Reference]]

@@ Line 83: / Line 83: @@
 * '''on_mouse_action''': function called when the user leftclicks on hex; its arguments are x,y of location selected. {{DevFeature1.13|10}} Might be from earlier 1.13, not tested.
-''on_mouse_action'' has several gotchas. Currently (1.4.1), the sequence goes like this:
+''on_mouse_action'' has several gotchas. Currently (1.14.1), the sequence goes like this:
 * The player clicks the mouse (mousedown followed by mouse up in the same hex).
 * on_mouse_action triggers, for that hex.

@@ Line 81: / Line 81: @@
 * '''on_load''': function called when the engine loads a scenario file; its argument is a WML table that contains all the children of the savefile that the engine did not handle.
 * '''on_event''': function called before each WML event is executed; its argument is the event name; other event arguments can be recovered from [[LuaWML:Misc#wesnoth.current|wesnoth.current.event_context]].
-* '''on_mouse_action''': function called when the user leftclicks on hex; its arguments are x,y of location selected. {{DevFeature1.13|10}} Might be from earlier 1.13, not tested. Documentation based on https://github.com/wesnoth/wesnoth/issues/2325
+* '''on_mouse_action''': function called when the user leftclicks on hex; its arguments are x,y of location selected. {{DevFeature1.13|10}} Might be from earlier 1.13, not tested.
 The ''on_save'' and ''on_load'' hooks can be used to manipulate data that are neither meant to be forwarded to the next level nor substituted on the fly. (For either of these two purposes, WML variables are the best choice.) For instance, toplevel tags like [item], [event], [time_area], and so on, could typically be handled by such hooks.

@@ Line 139: / Line 139: @@
 {{DevFeature1.13|12}}
-This is an associative table defining tags that should be persisted in saved games. Each tag is itself a table containing two functions, read and write. The write function is called in <tt>on_load<tt> and passed a function as a parameter which takes a WML table and adds it the saved game under the specified tag; the read function is called once per matching tag found in the saved game, and is passed a WML table of its contents. Note the asymmetry here: if you're saving an array, the write function is responsible for saving the entire array (and is only called once), while the read function is only responsible for loading one item (and is called several times).
+This is an associative table defining tags that should be persisted in saved games. Each tag is itself a table containing two functions, read and write. The write function is called in <tt>on_load</tt> and passed a function as a parameter which takes a WML table and adds it the saved game under the specified tag; the read function is called once per matching tag found in the saved game, and is passed a WML table of its contents. Note the asymmetry here: if you're saving an array, the write function is responsible for saving the entire array (and is only called once), while the read function is only responsible for loading one item (and is called several times).
 Example:

@@ Line 134: / Line 134: @@
 {{DevFeature1.13|5}}:
 The event names passed to ''on_event'' always use underscores instead of spaces
 ==== wesnoth.fire_event ====

@@ Line 119: / Line 119: @@
 Note: Some tag names are reserved for engine use and should not be modified using the above on_save/on_load method. These tag names are:
-  "color_palette", "color_range", "era", "event", "generator",
+  "color_palette", "color_range", "era", "event", "generator", "label",
- "label", "lua", "menu_item", "music", "side", "sound_source", "story",
+ "lua", "menu_item", "music", "next_item_name", "objectives", "side", "sound_source",
- "terrain_graphics", "time", "time_area", "tunnel", "variables"
+ "story", "terrain_graphics", "time", "time_area", "tunnel", "used_item", "variables"
 Note: a on_event handler will not prevent undoing of that event, so usually you need to add an event to diallow undo to prevent OOS. You can add an event handler for that event inside a on_event callback. A possible way to define a disallow_undo function is: