LuaWML - Revision history

Gnombat: For some reason, the code example of complex WML represented by a Lua table had way too many braces (some of them unbalanced). It should be fixed now (I think).

2025-06-21T19:31:09Z

For some reason, the code example of complex WML represented by a Lua table had way too many braces (some of them unbalanced). It should be fixed now (I think).

Celtic Minstrel: /* WML table */ Clean up so that all examples use recommended format, leaving only a brief note on the old, deprecated format

2024-11-01T23:38:57Z

‎WML table: Clean up so that all examples use recommended format, leaving only a brief note on the old, deprecated format

Celtic Minstrel: /* The [lua] tag */ A few more minor clarifications

2024-09-11T23:54:02Z

‎The [lua] tag: A few more minor clarifications

Celtic Minstrel: /* The [lua] tag */ Try to explain things better, and also use the typical syntax for listing what's possible

2024-09-11T23:34:41Z

‎The [lua] tag: Try to explain things better, and also use the typical syntax for listing what's possible

Bssarkar: /* Encoding WML objects into Lua tables */ separate subsections for wml tables and vconfigs

2024-06-18T09:07:41Z

‎Encoding WML objects into Lua tables: separate subsections for wml tables and vconfigs

Bssarkar: /* Testing out Lua in-game */ fix typo in tag

2024-04-25T02:14:28Z

‎Testing out Lua in-game: fix typo in tag

Celtic Minstrel: /* The [lua] tag */ Add [campaign]

2024-04-21T14:24:41Z

‎The [lua] tag: Add [campaign]

Celtic Minstrel: /* The [lua] tag */ Some grammatical improvements.

2023-12-25T21:44:43Z

‎The [lua] tag: Some grammatical improvements.

Celtic Minstrel: /* The [lua] tag */ Better precision on the devtag

2023-12-25T21:44:14Z

‎The [lua] tag: Better precision on the devtag

Celtic Minstrel: /* The [lua] tag */ Link to ConditionalWML version of the tag

2023-12-25T21:41:06Z

‎The [lua] tag: Link to ConditionalWML version of the tag

@@ Line 294: / Line 294: @@
+{
      foo = 42,
-     wml.tag.bar { v = 1, w = 2 } },
+     wml.tag.bar { v = 1, w = 2 },
-     wml.tag.foo { x = false } },
+     wml.tag.foo { x = false },
-     wml.tag.bar { y = "foo" } },
+     wml.tag.bar { y = "foo" },
-     wml.tag.foobar { z = 5, { wml.tag.barfoo {} } } }
+     wml.tag.foobar { z = 5, wml.tag.barfoo {} }
+}
 </syntaxhighlight>

@@ Line 285: / Line 285: @@
 </syntaxhighlight>
-WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys (it is possible to have a tag and an attribute with the same name). So child objects are stored as (string, table) pairs in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form <syntaxhighlight inline lang=lua>{[1] = "tag_name", [2] = {}}</syntaxhighlight> which is equivalent to <syntaxhighlight inline lang=lua>{"tag_name", {}}</syntaxhighlight>. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each.
+WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys (it is possible to have a tag and an attribute with the same name). So child objects are stored as (string, table) pairs in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form <syntaxhighlight inline lang=lua>{tag = "tag_name", contents = {}}</syntaxhighlight>. The table under <tt>contents</tt> in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. In code, this format is constructed using [[LuaAPI/wml#wml.tag|wml.tag]] to improve readability. For example <syntaxhighlight inline lang=lua>wml.tag_name{}</syntaxhighlight> is equivalent to the prior example.
-{{DevFeature1.17|?}} As of 1.17, the structure has changed slightly. Now the additional table "layer" for each tag looks like <syntaxhighlight inline lang=lua>{tag = "tag_name", contents = {}}</syntaxhighlight>. For backwards compatibility, accessing [1] and [2] still return or set tag and contents respectively (in fact, it is a structure created by [[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]]).
+'''Note''': As of 1.17, the structure changed slightly. Previously the additional table "layer" for each tag looked like <syntaxhighlight inline lang=lua>{[1] = "tag_name", [2] = {}}</syntaxhighlight>. For backwards compatibility, accessing [1] and [2] still return or set tag and contents respectively (in fact, it is a structure created by [[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]]). However, in older versions, only [1] and [2] work.
 For instance, the following Lua table
@@ Line 294: / Line 294: @@
+{
      foo = 42,
-     { "bar", { v = 1, w = 2 } },
+     wml.tag.bar { v = 1, w = 2 } },
-     { "foo", { x = false } },
+     wml.tag.foo { x = false } },
-     { "bar", { y = "foo" } },
+     wml.tag.bar { y = "foo" } },
-     { "foobar", { z = 5, { "barfoo", {} } } }
+     wml.tag.foobar { z = 5, { wml.tag.barfoo {} } } }
+}
 </syntaxhighlight>
@@ Line 322: / Line 322: @@
      [/foobar]
 [/dummy]
 </syntaxhighlight>
@@ Line 340: / Line 328: @@
 <syntaxhighlight lang=lua>
 a_int = cfg.foo        -- "dummy.foo", 42
-a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
+a_string = cfg[3].contents.y -- "dummy.bar[1].y", "foo"
-a_table = cfg[4][2]    -- "dummy.foobar", { z = 5, { "barfoo", {} } }
+a_table = cfg[4].contents    -- "dummy.foobar", { z = 5, { "barfoo", {} } }
 </syntaxhighlight>

@@ Line 11: / Line 11: @@
 * '''code''': A string containing the Lua script.
 * '''name''': An arbitrary string used to identify this tag in error messages.
-* '''[args]''': Arbitrary data that will be passed to the Lua script as its only argument. It can be accessed via the special <code>...</code> variable in the Lua code.
+* '''[args]''': Arbitrary data that will be passed to the Lua script as its only argument. It can be accessed in the Lua code via the special variadic variable <code>...</code>.
-Since Lua makes usage of double quotes and curly braces, it is recommended to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization. This is not strictly required, however. Example:
+Since Lua makes usage of double quotes and curly braces, it is recommended to enclose the script between [[SyntaxWML#macro-protected-string|stronger quotes]] (as shown in the below example), as they prevent the preprocessor from performing macro expansion and tokenization. This is not strictly required, however. Example:
 <syntaxhighlight lang='wml'>
@@ Line 32: / Line 32: @@
 </syntaxhighlight>
-When code in a '''[lua]''' tag has errors, it's often hard to find the location of the error because the line numbers are not within the code string and not the entire file. To help with this, you can set the '''name''' key. When an error is reported, the value of '''name''' will be used shown as if it were the filename, allowing you to more easily locate the tag that raised it.
+When code in a '''[lua]''' tag has errors, it's often hard to find the location of the error because the line numbers are not within the code string and not the entire file. To help with this, you can set the '''name''' key. When an error is reported, the value of '''name''' will be shown as if it were the filename, allowing you to more easily locate the tag that raised it.
 == Testing out Lua in-game ==

@@ Line 3: / Line 3: @@
 == The '''[lua]''' tag ==
-This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It can also be used as [[ConditionalActionsWML#.5Blua.5D|ConditionalWML]] It makes it possible to write actions with the [http://www.lua.org Lua 5.4] language.
+This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.4] language.
-{{DevFeature1.13|?}} It is also possible to put this tag inside a [scenario] [[ScenarioWML]], those tags will be executed immediately when the lua engine loads which is even before the scenario preload event is fired. It is now also allowed in [era], [modification], [campaign] and [resource]. These [lua] tags are then copied into the [scenario]/[multiplayer] when it is played, just like [event]s inside [era] or [modification]
+{{DevFeature1.13|?}} In addition to ActionWML, the '''[lua]''' tag may now be used in several other places. It can be placed at toplevel (outside of any tag) to make code that loads no matter what. ('''Note''': This should usually be avoided, unless you're making a [[CoreWML|custom core]].) It can be placed in any [[AddonsWML|addon module tag]], such as '''[scenario]''', '''[era]''', or '''[resource]''', to load code when the scenario boots up. Lua code placed in either of these places is executed even earlier than a '''preload''' event. And finally, it can now be used as [[ConditionalActionsWML#.5Blua.5D|ConditionalWML]]. In this case, the code must return either '''true''' or '''false''' to determine the outcome of the condition.
-The tag requires only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.
+The '''[lua]''' tag can contain the following contents:
 <syntaxhighlight lang='wml'>
@@ Line 15: / Line 21: @@
 </syntaxhighlight>
+The '''[args]''' tag is useful if you need to pass WML variables or macro expansions into the code.
 <syntaxhighlight lang='wml'>
@@ Line 22: / Line 27: @@
       code = << local t = ...; wesnoth.interface.add_chat_message(tostring(t.text)) >>
       [args]
-          text = _ "Hello world!"
+          text = _ "Hello $unit.name!"
       [/args]
   [/lua]
 </syntaxhighlight>
-The tag also supports a '''name''' key. When code in a '''[lua]''' tag has errors, it's often hard to find the location of the error because the line numbers are not within the code string and not the entire file. To help with this, you can set the '''name''' key. When an error is reported, the value of '''name''' will be used shown as if it were the filename, allowing you to more easily locate the tag that raised it.
+When code in a '''[lua]''' tag has errors, it's often hard to find the location of the error because the line numbers are not within the code string and not the entire file. To help with this, you can set the '''name''' key. When an error is reported, the value of '''name''' will be used shown as if it were the filename, allowing you to more easily locate the tag that raised it.
 == Testing out Lua in-game ==

@@ Line 253: / Line 253: @@
 == Encoding WML objects into Lua tables ==
 Many functions in the Wesnoth Lua API expect a table representing a WML object (that is, the contents of a WML tag) to be passed as a parameter, for example [[LuaAPI/wml#wml.fire|wml.fire]]. Other functions return WML data converted to a Lua table. All these tables have the same format. The Lua API documentation refers to a table using this specific format convention as a "WML table".
@@ Line 381: / Line 382: @@
 </syntaxhighlight>
 Functions registered in [[LuaAPI/wesnoth#wesnoth.wml_actions|wesnoth.wml_actions]] and other similar tables that provide hooks that the engine calls will receive their data either in lua tables encoding a WML object or as a [[LuaAPI/wml#wml.tovconfig|WML vconfig userdata]], which has the same structure but is read-only. Accessing fields or children on a vconfig performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain, writable tables. '''__literal''' returns the original text of the data (including dollar symbols in attributes and '''[insert_tag]''' children), while '''__parsed''' performs a full variable substitution.

@@ Line 35: / Line 35: @@
   :lua local u = wesnoth.units.find_on_map{ id = "Konrad" }[1]; u.moves = 5
-In addition, if you enable debug mode, you can access a <acronym title="Read, evaluate, print loop">REPL</acronym< console by pressing the Lua Console hotkey, which is bound to ~ by default. You can enable debug mode by using the <tt>:debug</tt> command, or by running Wesnoth with the <tt>--debug</tt> command-line argument. In the latter case, the Lua Console can even be summoned from the main menu screen.
+In addition, if you enable debug mode, you can access a <acronym title="Read, evaluate, print loop">REPL</acronym> console by pressing the Lua Console hotkey, which is bound to ~ by default. You can enable debug mode by using the <tt>:debug</tt> command, or by running Wesnoth with the <tt>--debug</tt> command-line argument. In the latter case, the Lua Console can even be summoned from the main menu screen.
 You can use the Lua console to examine anything about the Lua environment and execute any Lua code you wish. It is recommended to use command mode to execute Lua that affects the map however, for example moving a unit. In the Lua Console you can use a special [[LuaAPI/wesnoth#wesnoth.print_attributes|dir()]] function to examine the contents of objects and modules. You can also access a special <tt>_</tt> variable which contains the result of the previous command executed in the console. Global variables assigned in the Lua console are not visible to scenario code, but remain between invocations of the console within a single game, as long as you don't reload. If you need to assign a global variable that is visible outside of the console, you can do so via the special variable <tt>_G</tt>.

@@ Line 5: / Line 5: @@
 This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It can also be used as [[ConditionalActionsWML#.5Blua.5D|ConditionalWML]] It makes it possible to write actions with the [http://www.lua.org Lua 5.4] language.
-{{DevFeature1.13|?}} It is also possible to put this tag inside a [scenario] [[ScenarioWML]], those tags will be executed immediately when the lua engine loads which is even before the scenario preload event is fired. [lua] is now also allowed in [era], [modification] and [resource], those [lua] tags are then copied into the [scenario]/[multiplayer] when it is played just like [event]s inside [era] or [modification]
+{{DevFeature1.13|?}} It is also possible to put this tag inside a [scenario] [[ScenarioWML]], those tags will be executed immediately when the lua engine loads which is even before the scenario preload event is fired. It is now also allowed in [era], [modification] and [resource]. These [lua] tags are then copied into the [scenario]/[multiplayer] when it is played, just like [event]s inside [era] or [modification]
 The tag requires only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.