Global functions

The following functions are imported into the global namespace of all scripts that are running inside widelands. They provide convenient access to other scripts in other locations, localisation features and more.

There is also a global variable called __file__ defined that is the current files name.

string.bformat()

Not really a global function. But we add a method to string built-in type in Lua that has similar functionality to the built-in string.format, but instead uses our own format function. This allows for better control of the formatting as well as reordering of arguments which is needed for proper localisation.

Returns

The formatted string.

push_textdomain(domain[, addon=false])

Sets the textdomain for all further calls to _() until it is reset to the previous value using pop_textdomain().

If your script is part of an add-on, the second parameter needs to be true.

Parameters

domain (string) – The textdomain

Returns

nil

pop_textdomain()

Resets the textdomain for calls to _() to the value it had before the last call to push_textdomain().

Returns

nil

_(str)

This peculiar function is used to translate texts in your scenario into another language. The function takes a single string, grabs the textdomain of your map (which is usually the maps name) and returns the translated string. Make sure that you separate translatable and untranslatable stuff:

s = "<p><br>" .. _("Only this should be translated") .. "<br></p>"
Parameters

str (string) – text to translate.

Returns

The translated string.

ngettext(msgid, msgid_plural, n)

A wrapper for the ngettext() function, needed for translations of numbered strings.

Parameters

  • msgid (string) – text to translate (singular)

  • msgid_plural (string) – text to translate (plural)

  • n (An unsigned integer.) – The number of elements.

Returns

The translated string.

pgettext(msgctxt, msgid)

A wrapper for the pgettext() function, needed for allowing multiple translations of the same string according to context.

Parameters

  • msgctxt (string) – a named context for this string for disambiguation

  • msgid (string) – text to translate

Returns

The translated string.

npgettext(msgctxt, msgid, msgid_plural, n)

A wrapper for the npgettext() function, needed for allowing multiple translations of the same plural string according to context.

Parameters

  • msgctxt (string) – a named context for this string for disambiguation

  • msgid (string) – text to translate

  • msgid_plural (string) – text to translate (plural)

  • n (An unsigned integer.) – The number of elements.

Returns

The translated string.

include(script)

Includes the script at the given location at the current position in the file. The script can begin with ‘map:’ to include files from the map.

Parameters

script (string) – The filename relative to the root of the data directory.

Returns

nil

ticks()

Returns an integer value representing the number of milliseconds since the SDL library initialized.

get_build_id()

returns the version string of this widelands executable. Something like “1.1” (for a release), “1.2~git26354 (4ba897c@master)” (development for 1.2) or “build-16[debug]” (old, before version 1.0).

play_sound(file[, priority = 100, allow_multiple = true, field = nil])

New in version 1.3.

Play a sound effect.

See the playsound program for information on how the file has to be provided and the meaning of the optional arguments. Only .ogg files are supported.

If a field is provided, the sound is played in stereo, and only if the player can hear sounds on the given field.

The volume of the sound and whether the sound will be played at all are determined by the user’s settings for ambient sounds.

Parameters

  • file (string) – The path and basename of the sound effect to play (without the .ogg filename extension and the optional _?? numbering).

  • priority (number) – The priority of the sound in percent.

  • allow_multiple (boolean) – Whether the sound may be played even when another instance of it is already playing.

  • field (wl.map.Field) – The map position of the sound, if any.