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 boost::format. This allows for better control of the formatting as well as reordering of arguments which is needed for proper localisation.

Returns

nil

set_textdomain(domain)

Sets the textdomain for all further calls to _().

Parameters

domain (string) – The 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.

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 “build-16[debug]”.