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-instring.format
, but instead uses our ownformat
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()
ornpgettext()
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 usingpop_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 topush_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 thecount
variable in the string, do not usengettext
, but rather anif
-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 disambiguationmsgid (
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 disambiguationmsgid (
string
) – text to translatemsgid_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.