From The Battle for Wesnoth Wiki

Practical Info for Lua beginners.

This is a concept to create a similar (but different and shorter) resource like WML_for_Complete_Beginners. The aim is to make people feel comfortable with Lua and the Lua Console (the UI). It's not aiming to tell how to build something, which LuaWML does already.

What's written here should someday get into the Wiki, i.e. onto an own page such as LuaSyntax or LuaIntro.


Lua table

Lua has only one data type.
This should be made clear, and that data type should be shown in detail.
Especially: - how does it look, i.e, showing a
table with all the braces and commas to the reader.

Resembling other Datatypes

Explaining (some) of these as special cases. Also, naming how other languages call these concepts if they exist there.

WML Table
Proxy Table
vconfig (whatever that is)
Set & Bag
Indexed Table
Sorted Table

However, examples should be taken somewhere from Wesnoth, not completely fictional.

Return Codes

Should be explained somewhere, but later down or somewhere else,
especially the part that a Lua function can have more than one return code
and that it can return a table.

The Lua Console

/* Practical Part */

/* Telling the reader how to play with Lua */

/* How to find your way into experimenting with what you read here */

  1. Activate Debug Mode: There's 2 ways to achieve that
    • Either start the Wesnoth application with the -d or --debug option.
    • Or use ingame the :debug command.
  2. Open the Lua Console:
    If you are not in debug mode, nothing will happen when you try to open it.
    The Lua Console can be opened by pressing the hotkey ` (the grave accent sign)
    If it does not work, please change the hotkey in the settings.
    (It likely won't work out of the box on non-American keyboards.)

Inspecting Data

With simple data, e.g. a unit.

Try out these commands. Play around. And find the secret behind

a = … some Lua command here …
print (a)
print (a[1])
print (a[1][1])
print (a[1].side_name)
print (a[2].gold)
print (a[923])
type  (a[1])
print (a[1].__cfg)

/* The intention is to get a feeling of what Lua is. What are tables. How can one access specific information. etc. This is the main part. */


Iterating is one central tool in Lua. It fills the same role like the WML tags [foreach] or [while].
You always need to iterate when you want to make the same action for multiple units or sides or …
In short — when the print(a[1].side_name) is not enough for your needs anymore, when you want to print it for all sides.


Below is an often seen piece of code:

i stands for index, it's a convention that this variable is named i.
v stands for value.

The argument to ipairs, in this case a, is a table.

 for i, v in ipairs(a) do
     print(i, v.faction, v.color)

Ipairs only prints the elements of the table, which have a number as index. (As opposed to anything else as index, i.e. a string. Remember, tables are the only data structure in Lua, and they can contain lot of different things which do not necessarily make sense).

Relevant WML tag: [foreach]


Very similar, but for some reason used less, the pairs function.
Instead of index and value, it's key and value.
(Bad example, output is the same.)

 for k, v in pairs(a) do
    print(k, v.faction, v.color)

This mechanism is for tables which do not use a numerical key.

Relevant WML tag: [foreach]


/* Mentioning this only for sake of completeness */

/* This should rather be on a separate wiki page */



 for a = 1, 20, 1
     print("value of a:", a)

Relevant WML tag: [for]


 while a < 20 
    print("value of a:", a)
    a = a+1

Relevant WML tag: [while]


Lua is an old language, it also knows the repeat statement.

     print("value of a:", a)
     a = a+1
 until a == 20

This code is similar to the while loop above, but the code inside is executed at least once, as the condition is checked at the end. In other languages this is known as do-while-loop.

The WML tag [repeat], has not the same possibilities as Lua's repeat, as the WML tag only allows to repeat for a number of times, while Lua's repeat allows for any kind of condition, like while does.

Miscellaneous Links

Introduction to Programming and Lua in German, English, Spanish, French and partially Italian

This page was last edited on 20 May 2021, at 00:43.