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:

include "scripting/win_conditions/win_condition_functions.lua"

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.

Parameters

• plr (Player) – Player to calculate extra data for

• name (string) – Name of the win-condition

• version (integer) – Version the win-condition

• extra (array) – List of other extra arguments that should be passed to the server. They will also be incorporated into the extra string.

Returns

The extra string that can be passed on

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.

Parameters

• plrs (array) – List of players to be checked

• heading (string) – Heading of the message the defeated player will get

• msg (string) – Message the defeated player will get

• wc_name (string) – Name of the win condition. If not nil, wl.game.report_result() will be called.

• wc_ver (integer) – Version of the win condition

Returns

nil

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.

Parameters

plrs (array) – List of players

Returns

The number of factions left in game

broadcast(plrs, header, msg[, options])

Broadcast a message to all players using send_to_inbox(). All parameters are passed literally.

broadcast_objective(header, msg, body)

Broadcast an Objective to all players. Technically, it is assigned to player1, because all players will see all objectives.

Parameters

• name (string) – A unique name for the objective

• title (string) – The title to be displayed for the objective

• body (string) – The content text to be displayed for the objective

count_owned_valuable_fields_for_all_players(players[, attribute])

Counts all owned fields for each player.

Parameters

• players (array of wl.game.Player) – Table of all players

• attribute (string) – If this is set, only count fields that have an immovable with this attribute.

Returns

A table with playernumber=count_of_owned_fields entries

rank_players(all_player_points, plrs)

Rank the players and teams according to the highest points

Parameters

• all_player_points (array) – A table of playernumber=points entries for all players.

• plrs (array) – A table of all wl.game.Player objects

Returns

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

{
   -- 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 }
      }
   },
}

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.

Parameters

remaining_time (integer) – The remaining game time in minutes.

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.

Parameters

remaining_time (integer) – The remaining game time in minutes.

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.

Parameters

• max_time (integer) – The time maximum game time in minutes

• remaining_time (integer) – The remaining time until game ends. On first call this is equal to max_time.

Returns

The remaining_time and true if the end of the predefined periods are reached.