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.

Use bformat() whenever your string contains values from variables.

Returns:

The formatted string.

bformat() can be used with the global _(str) function. Examples:

local a_str    = _("Widelands")
local a_number = 5
local a_float  = 3.4

_("This is a string: %1$s"):bformat(a_str)             -- s = string
_("This is a number: %1$d"):bformat(a_number)          -- d = number (integer)
_("This is a number: %1$f"):bformat(a_float)           -- f = number (float)

-- %1$ refers to the first,
-- %2$ to the second placeholder and so on:

local tribe_name = _("Atlanteans")
_("The %1$s are one of the tribes in %2$s."):bformat(tribe_name, a_str)

-- Formatting numbers with two digits:
local hours   = 2
local minutes = 10
local seconds = 5

-- TRANSLATORS: A time string (hh:mm:ss) like "10:02:30"
_("%1$02d:%2$02d:%3$02d"):bformat(hours, minutes, seconds) -- result: 02:10:05

-- Formatting floating point numbers with precision:
local endless = 10 / 3

_("Precision of 2: %1$.2f"):bformat(endless)           -- result: Precision of 2: 3.33

If your variable contains a number you should use ngettext() or npgettext() to allow proper translation of plural strings.

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.

Example to show how it works:

local count = _get_items()                -- count can be 0 or more
local text  = ngettext("You have %1$d item", "You have %1$d items", count):bformat(count)

Note

The singular and plural forms should be identical except for the plural form itself. If you want to special-case the number 1 (or any other number), or if you don’t want to include the count variable in the string, do not use ngettext, but rather an if-else-construct. Example:

local count = _get_items()  -- count can be 0 or more
local text

if count == 0 then
   text = _("You have no items.")
elseif count == 1 then
   text = _("You have only one item.")
else
   text = _("You have a lot of items.")
end

-- Note the _() function for translation.
-- The arguments to ngettext do not require an additional _() call.
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])

Added 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.