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.

.. function:: 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.

   .. function:: push_textdomain(domain [, addon=false])

      Sets the textdomain for all further calls to :func:`_` until it is reset
      to the previous value using :func:`pop_textdomain`.

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

      :arg domain: The textdomain
      :type domain: :class:`string`
      :returns: :const:`nil`

   .. function:: pop_textdomain()

      Resets the textdomain for calls to :func:`_` to the value it had
      before the last call to :func:`push_textdomain`.

      :returns: :const:`nil`

   .. function:: _(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:

      .. code-block:: lua

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

      :arg str: text to translate.
      :type str: :class:`string`
      :returns: The translated string.

.. function:: ngettext(msgid, msgid_plural, n)

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

   :arg msgid: text to translate (singular)
   :type msgid: :class:`string`
   :arg msgid_plural: text to translate (plural)
   :type msgid_plural: :class:`string`
   :arg n: The number of elements.
   :type n: An unsigned integer.

   :returns: The translated string.

.. function:: pgettext(msgctxt, msgid)

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

   :arg msgctxt: a named context for this string for disambiguation
   :type msgctxt: :class:`string`
   :arg msgid: text to translate
   :type msgid: :class:`string`

   :returns: The translated string.

.. function:: 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.

   :arg msgctxt: a named context for this string for disambiguation
   :type msgctxt: :class:`string`
   :arg msgid: text to translate
   :type msgid: :class:`string`
   :arg msgid_plural: text to translate (plural)
   :type msgid_plural: :class:`string`
   :arg n: The number of elements.
   :type n: An unsigned integer.

   :returns: The translated string.

   .. function:: 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.

      :type script: :class:`string`
      :arg script: The filename relative to the root of the data directory.
      :returns: :const:`nil`

.. function:: ticks()

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

.. function:: 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).

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

   .. versionadded:: 1.3

   Play a sound effect.

   See :ref:`the playsound program <map_object_programs_playsound>` 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.

   :arg file: The path and basename of the sound effect to play
      (without the .ogg filename extension and the optional ``_??`` numbering).
   :type file: :class:`string`
   :arg priority: The priority of the sound in percent.
   :type priority: :class:`number`
   :arg allow_multiple: Whether the sound may be played
      even when another instance of it is already playing.
   :type allow_multiple: :class:`boolean`
   :arg field: The map position of the sound, if any.
   :type field: :class:`wl.map.Field`