Scenario Tutorial¶
This section describes how to get a map ready for scripting addition and how to write simple Lua scripts. It goes trough all the concepts required to get you started writing cool widelands scenarios and campaigns.
Designing the Map¶
Wideland’s map files are plain directories containing various different files
that describe a map. Normally, widelands saves those files in one zip archive
file with the file extension .wmf
. To add scripting capabilities to maps,
we have to create new text files in the scripting/
directory of the map,
therefore we want to have the map as a plain directory, so that we can
easily add new scripting files. There are two ways to achieve this:
Set the nozip option in the advanced options inside of Widelands. Widelands will now save maps (and savegames) as plain directories.
Manually unpack the zip file. To do this, do the following:
Rename the file:
map.wmf
->map.zip
Unpack this zipfile, a folder
map.wmf
will be created.
Now create a new directory called scripting/
inside the map folder.
Hello World¶
The language widelands is using for scripting is called Lua. It is a simple scripting language that is reasonable fast and easy to embed in host applications. We will now learn how to start the map as a scenario and how to add a simple Lua script to it. For this create a new text file and write the following inside:
print "###############################"
print "Hello World"
print "###############################"
Save this file inside the maps directory as scripting/init.lua
.
Note
When we talk about text files, we mean the very basic representation of characters that a computer can understand. That means that any fancy word processor (Word, OpenOffice and their like) will likely produce the wrong file format when saving. Make sure to use a plain text editor (like Notepad under Windows, nedit under Linux and TextEdit under Mac OS X). If you have programmed before, you likely already have found your favorite editor….
Now we try to start this scenario. We can either directly select the map when
starting a new single player game and mark the scenario box or we manually
tell widelands to open our map as a scenario directly from the console.
This is very convenient if you need to test drive the same map over and over
again: Open up a command line (Terminal under Mac OS X/Linux, Cmd under
Windows) and cd
into the widelands directory. Now start up widelands and
add the scenario switch like so:
./widelands --scenario=path/to/map/mapname.wmf
Widelands should start up and immediately load a map. Look at it’s output on
the cmdline (Under Windows, you might have to look at stdout.txt
) and you
should see our text been printed:
###############################"
Hello World"
###############################"
So what we learned is that widelands will run the script
scripting/init.lua
as soon as the map is finished loading. This script is
the entry point for all scripting inside of widelands.
A Lua Primer¶
This section is intentionally cut short. There are excellent tutorials in Luas Wiki and there is a complete book free online: Programming in Lua. You should definitively start there to learn Lua.
This section only contains the parts of Lua that I found bewildering and it also defines a few conventions that are used in this documentation.
Data Types¶
Lua only has one fundamental data type called table
. A Table is what
Python calls a dictionary and other languages call a Hashmap. It basically
contains a set of Key-Value combinations. There are two ways to access the
values in the table, either by using the d[key]
syntax or by using the
d.key
syntax. For the later, key
must be a string:
d = {
value_a = 23,
b = 34,
90 = "Hallo"
}
d.value_a -- is 23
d['value_a'] -- the same
d['b'] -- the same as d.b
d[90] -- is "Hallo"
b.90 -- this is illegal
Tables that are indexed with integers starting from 1 are called
arrays
throughout the documentation. Lua also accepts them as
something special, for example it can determine their length via the #
operator and they can be specially created:
a = { [1] = "Hi", [2] = "World }
b = { "Hi", "World" }
-- a and b have the same content
print(#a) -- will print 2
Calling conventions¶
Calling a function is Lua is straight forward, the only thing that comes as a surprise for most programmers is that Lua throws values away without notice.
function f(a1, a2, a3) print("Hello World:", a1, a2, a3) end
f() --- Prints 'Hello World: nil nil nil'
f("a", "house", "blah") --- Prints 'Hello World: a house blah'
f("a", "a", "a", "a", "a") --- Prints 'Hello World: a a a'
The same also goes for return values.
function f() return 1, 2, 3 end
a = f() -- a == 1
a,b = f() -- a == 1, b == 2
a,b,c,d = f() -- a == 1, b == 2, c == 3, d == nil
Another thing that comes to a surprise for some developer is the syntactic
sugar that Lua adds to calls. The following rules apply: If a function is
given exactly one argument and this argument is either a string
or a
table
, the surrounding parenthesis can be left out. This makes for
something similar to optional arguments. The following two lines are equal
some_function{a = "Hi", b = "no"}
some_function({a = "Hi", b = "no"})
The first one though is often used for functions that take mostly optional arguments. A second use case is for strings:
print "hi"
print("hi") -- same
We use this in widelands to our advantage to implement internationalization
via a global function called _()
(an long standing gettext paradigm):
print _ "Hello Word" -- Will print in German: "Hallo Welt"
print( _("Hello World")) -- the same in more verbose writing
Coroutines¶
The most important feature of Lua that widelands is using are coroutines. We use them watered down and very simple, but their power is enormous. In Widelands use case, a coroutine is simply a function that can interrupt it’s execution and give control back to widelands at any point in time. After it is awoken again by widelands, it will resume at precisely the same point again. Let’s dive into an example right away:
use("aux", "coroutine")
function print_a_word(word)
while 1 do
print(word)
sleep(1000)
end
end
run(print_a_word, "Hello World!")
If you put this code into our init.lua
file from the earlier example, you
will see “Hello World!” begin printed every second on the console. Let’s
digest this example. The first line imports the coroutine.lua
script from
the auxiliary Lua library that comes bundled with widelands. We use two
functions from this in the rest of the code, namly sleep()
and
run()
.
Then we define a simple function print_a_word()
that takes one argument
and enters an infinite loop: it prints the argument, then sleeps for a second.
The sleep()
function puts the coroutine to sleep and tells widelands to
wake the coroutine up again after 1000 ms have passed. The coroutine will then
continue its execution directly after the sleep call, that is it will enter
the loop’s body again.
All we need now is to get this function started and this is done via the
run()
function: it takes as first argument a function and then any
number of arguments that will be passed on to the given function. The
run()
will construct a coroutine and hand it over to widelands for
periodic execution.
These are all of the essential tools we need to write cool scenario scripts for widelands.
Note
Keep in mind that widelands won’t do anything else while you’re
coroutine is running, so if you plan to do long running tasks consider
adding some calls to sleep()
here and there so that widelands can act
and update the user interface.
Let’s consider a final example on how coroutines can interact with each other.
use("aux", "coroutine")
function print_a()
while 1 do
print(a)
sleep(1000)
end
end
function change_a()
while 1 do
if a == "Hello" then
a = "World"
else
a = "Hello"
end
sleep(1333)
end
end
a = "Hello"
run(print_a)
run(change_a)
The first coroutine will print out the current value of a, the second changes the value of the variable a asynchronously. So we see in this example that coroutines share the same environment and can therefore use global variables to communicate with each other.
Preparing Strings for Translation¶
If you want your scenario to be translatable into different languages, it is important to keep in mind that languages differ widely in their grammar. This entails that word forms and word order will change, and some languages have more than one plural form. So, here are some pointers for good string design. For examples for the formatting discussed here, have a look at data/maps/MP Scenarios/Island Hopping.wmf/scripting/multiplayer_init.lua
in the source code.
Marking a String for Translation¶
In order to tell Widelands to add a string to the list of translatable strings, simply add an underscore in front of it, like this:
print _"Translate me"
Strings that contain number variables have to be treated differently; cf. the Numbers in Placeholders
section below.
Translator Comments¶
If you have a string where you feel that translators will need a bit of help
to understand what it does, you can add a translator comment to it. Translator
comments are particularly useful when you are working with placeholders,
because you can tell the translator what the placeholder will be replaced
with. Translator comments need to be inserted into the code in the line
directly above the translation. Each line of a translator comment has to be
prefixed by -- TRANSLATORS:
, like this:
-- TRANSLATORS: This is just a test string
-- TRANSLATORS: With a multiline comment
print _"Hello Word"
Working with Placeholders¶
If you have multiple variables in your script that you wish to include dynamically in the same string, please use ordered placeholders to give translators control over the word order. We have implemented a special Lua function for this called bformat that works just like the boost::format
function in C++. Example:
local world = _("world") -- Will print in Gaelic: "saoghal"
local hello = _("hello") -- Will print in Gaelic: "halò"
-- TRANSLATORS: %1$s = hello, %2$s = world
print (_ "The %1$s is '%2$s'"):bformat(hello, world) -- Will print in Gaelic: "Is 'halò' an saoghal"
Numbers in Placeholders¶
Not all languages’ number systems work the same as in English. For example, the Gaelic word for “cat” conveniently is “cat”, and this is how its plural works: 0 cat, 1 or 2 chat, 3 cait, 11 or 12 chat, 13 cait, 20 cat… So, instead of using _
to fetch the translation, any string containing a placeholder that is a number should be fetched with ngettext
instead. First, you fetch the correct plural form, using the number variable and ngettext
:
pretty_plurals_string = ngettext("There is %s world" , "There are %s worlds", number_of_worlds)
Then you still need to format the string with your variable:
print pretty_plurals_string:format(number_of_worlds)
If you have a string with multiple numbers in it that would trigger plural forms, split it into separate strings that you can fetch with ngettext
. You can then combine them with bformat
and ordered placeholders.
Handling Long Strings¶
If you have a really long string, e.g. a dialog stretching over multiple sentences, check if there is a logical place where you could split this into two separate strings for translators. We don’t have a “break after x characters” rule for this; please use common sense here. It is easier for translators to translate smaller chunks, and if you should have to change the string later on, e.g. to fix a typo, you will break less translations. The strings will be put into the translation files in the same order as they appear in the source code, so the context will remain intact for the translators.
Also, please hide all formatting control characers from our translators. This includes HTML tags as well as new lines in the code! For an example, have a look at data/campaigns/atl01.wmf/scripting/texts.lua