win_condition_functions.lua
---------------------------

This script contains functions that are shared by different win conditions.

To make these functions available include this file at the beginning
of a script via:

.. code-block:: lua

   include "scripting/win_conditions/win_condition_functions.lua"


.. function:: make_extra_data(plr, name, version[, extra])

   Constructs a string containing information about the win condition.
   This can e.g be used to inform the metaserver about it.

   :arg plr: Player to calculate extra data for
   :type plr: :class:`~wl.game.Player`
   :arg name: Name of the win-condition
   :type name: :class:`string`
   :arg version: Version the win-condition
   :type version: :class:`integer`
   :arg extra: List of other extra arguments that should be passed
               to the server. They will also be incorporated into the
               extra string.
   :type extra: :class:`array`

   :returns: The extra string that can be passed on


.. function:: check_player_defeated(plrs, heading, msg, wc_name, wc_ver)

   Checks whether one of the players in the list was defeated and if yes,
   removes that player from the list and sends him/her a message.

   :arg plrs: List of :class:`players <wl.game.Player>` to be checked
   :type plrs: :class:`array`
   :arg heading: Heading of the message the defeated player will get
   :type heading: :class:`string`
   :arg msg:     Message the defeated player will get
   :type msg: :class:`string`
   :arg wc_name: Name of the win condition. If not nil, :meth:`wl.game.report_result`
                 will be called.
   :type wc_name: :class:`string`
   :arg wc_ver:  Version of the win condition
   :type wc_ver: :class:`integer`

   :returns: :const:`nil`

.. function:: count_factions(plrs)

   Calculates and returns the number of factions that are still involved in
   the running game.
   A faction is a team or an unteamed player.

   :arg plrs: List of :class:`players <wl.game.Player>`
   :type plrs: :class:`array`

   :returns: The number of factions left in game


.. function:: broadcast(plrs, header, msg[, options])

   Broadcast a message to all players using
   :meth:`send_to_inbox`. All parameters are passed
   literally.

.. function:: broadcast_objective(header, msg, body)

   Broadcast an :class:`~wl.game.Objective` to all players. Technically,
   it is assigned to player1, because all players will see all objectives.

   :arg name:  A unique name for the objective
   :type name: :class:`string`
   :arg title: The title to be displayed for the objective
   :type title: :class:`string`
   :arg body: The content text to be displayed for the objective
   :type body: :class:`string`

.. function:: count_owned_valuable_fields_for_all_players(players[, attribute])

   Counts all owned fields for each player.

   :arg players: Table of all :class:`players <wl.game.Player>`
   :type players: :class:`array` of :class:`wl.game.Player`
   :arg attribute: If this is set, only count fields that have an immovable
                   with this attribute.
   :type attribute: :class:`string`

   :returns: A table with ``playernumber=count_of_owned_fields``  entries


.. function:: rank_players(all_player_points, plrs)

   Rank the players and teams according to the highest points

   :arg all_player_points: A table of ``playernumber=points`` entries for
                           all players.
   :type all_player_points: :class:`array`
   :arg plrs: A table of all :class:`wl.game.Player` objects
   :type plrs: :class:`array`

   :returns: A table with ranked player and team points, sorted by points
             descending. Example:

   .. code-block:: lua

      {
         -- A player without team
         {
            team = 0,
            points = 1000,
            players = {
               { "number" = 5, "points" = 1000 }
            }
         },
         -- This team has a draw with player 5
         {
            team = 1,
            points = 1000,
            players = {
               { "number" = 2, "points" = 500 }
               { "number" = 3, "points" = 400 }
               { "number" = 4, "points" = 100 }
         },
         -- Another player without team
         {
            team = 0,
            points = 800,
            players = {
               { "number" = 1, "points" = 800 }
            }
         },
      }


.. function:: format_remaining_raw_time(remaining_time)

   Return a localized message that contains only the remaining game time
   to be used when sending messages with a duration in them.

   :arg remaining_time: The remaining game time in minutes.
   :type remaining_time: :class:`integer`


.. function:: format_remaining_time(remaining_time)

   Return a localized message that contains the remaining game time
   to be used when sending status messages about the remaining game time.

   :arg remaining_time: The remaining game time in minutes.
   :type remaining_time: :class:`integer`


.. function:: notification_remaining_time(max_time, remaining_time)

   Calculate the remaining game time for notifications.
   Should only be called within a coroutine, because the routine gets blocked.
   Returns the remaining time and whether the notification should popup.

   To be used when sending status messages.
   Status messages are to be sent every 30 minutes and every 5 during the last 30 minutes,
   the message window pops up ever hour, 30, 20 & 10 minutes before the game ends.

   :arg max_time:    The time maximum game time in minutes
   :type max_time: :class:`integer`
   :arg remaining_time: The remaining time until game ends. On first call
                        this is equal to **max_time**.
   :type remaining_time: :class:`integer`

   :returns: The remaining_time and :class:`true` if the end of the
             predefined periods are reached.