territorial_functions.lua
---------------------------

This file contains common code for the "Territorial Lord" and "Territorial Time" win conditions.

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

.. code-block:: lua

   include "scripting/win_conditions/territorial_functions.lua"


.. data:: territory_points

   This table contains information about the current points and winning status for all
   players and teams:

   .. code-block:: lua

      territory_points = {
         -- The currently winning team, if any. -1 means that no team is currently winning.
         last_winning_team = -1,
         -- The currently winning player, if any. -1 means that no player is currently winning.
         last_winning_player = -1,
         -- The name of the currently winning player, if any. Empty means that no player is currently winning.
         last_winning_player_name = "",
         -- Remaining time in secs for victory by > 50% territory. Default value is also used to calculate whether to send a report to players.
         remaining_time = 10,
         -- Points by player
         all_player_points = {},
         -- Points by rank, used to generate messages to the players
         points = {}
      }


.. function:: calculate_territory_points(fields, players, wc_descname, wc_version)

   First checks if a player was defeated, then fills the :data:`territory_points` table
   with current data.

   :arg fields: Number of all valuable fields
   :type fields: :class:`integer`
   :arg players: Table of all players
   :type players: :class:`array` of :class:`~wl.game.Player`
   :arg wc_descname: The win condition's descname
   :type wc_descname: :class:`string`
   :arg wc_version: The win condition's version
   :type wc_version: :class:`integer`


.. function:: territory_status(fields, has_had)

   Returns a string containing the current land percentages of players/teams
   for messages to the players

   :arg fields: Number of all valuable fields
   :type fields: :class:`integer`
   :arg has_had: Use "has" for an interim message, "had" for a game over message.
   :type has_had: :class:`string`

   :returns: a richtext-formatted string with information on current points for each player/team


.. function:: winning_status_header()

   Returns a string containing a status message header for a winning player

   :returns: a richtext-formatted string with header information for a winning player


.. function:: losing_status_header(players)

   Returns a string containing a status message header for a losing player

   :arg players: Table of all players
   :type players: :class:`array` of :class:`~wl.game.Player`

   :returns: a richtext-formatted string with header information for a losing player


.. function:: territory_game_over(fields, players, wc_descname, wc_version)

   Updates the territory points and sends game over reports

   :arg fields: Number of all valuable fields
   :type fields: :class:`integer`
   :arg players: Table of all players
   :type players: :class:`array` of :class:`~wl.game.Player`
   :arg wc_descname: The win condition's descname
   :type wc_descname: :class:`string`
   :arg wc_version: The win condition's version
   :type wc_version: :class:`integer`