Global

Members

clickedEntity

Store the clicked entity on mousedown or mouseup for single/double/triple clicks to select entities. If any mousedown or mouseup of a sequence of clicks lands on a unit, that unit will be selected, which makes it easier to click on moving units.
Source:

g_AlwaysDisplayFriendlyFire

If true, always shows whether the splash damage deals friendly fire. Otherwise display the friendly fire tooltip only if it does.
Source:

g_BackgroundLayerData

Available backgrounds, added by the files in backgrounds/.
Source:

(constant) g_BiomesDirectory

Directory containing all biomes supported for random map scripts.
Source:

g_Buddies

Array of playernames that the current user has marked as buddies.
Source:

g_BuddyListDelimiter

XEP-0172 doesn't restrict nicknames, but our lobby policy does. So use this human readable delimiter to separate buddy names in the config file.
Source:

g_BuddySymbol

Denotes which players are a lobby buddy of the current user.
Source:

g_CeasefireEndedHandlers

These handlers are called when the ceasefire time has run out.
Source:

g_ChangedKeys

Names of config keys that have changed, value returned when closing the page.
Source:

(constant) g_CivData

Offer users to select playable civs only. Load unselectable civs as they could appear in scenario maps.
Source:

(constant) g_CivData

Needed for formatPlayerInfo to show the player civs in the details.
Source:

(constant) g_CivData

Used for civ settings display of the selected game.
Source:

(constant) g_CivData

Needed for formatPlayerInfo to show the player civs in the details.
Source:

g_ClientsLoadingHandlers

These handlers are triggered whenever a client finishes the loading screen.
Source:

g_ColorFade

Used for storing information about color fades
Source:

g_ConfigChangeHandlers

These events are fired when the user has closed the options page. The handlers are provided a Set storing which config values have changed. TODO: This should become a GUI event sent by the engine.
Source:

g_DefaultLobbyRating

The rating assigned to lobby players who didn't complete a ranked 1v1 yet.
Source:

g_DependentLabelIndentation

Horizontal indentation to distinguish options that depend on another option.
Source:

g_DescriptionHighlight

Highlights the victory condition in the game-description.
Source:

g_Disconnected

True if the connection to the server has been lost.
Source:

g_DragStart

Used for remembering mouse coordinates at start of drag operations.
Source:

g_DurationFilterIntervals

Allow to filter replays by duration in 15min / 30min intervals.
Source:

(constant) g_EngineInfo

Used for checking replay compatibility.
Source:

g_EntityCommands

Info and actions for the entity commands Currently displayed in the bottom of the central panel
Source:

g_EntitySelectionChangeHandlers

These events are fired whenever the player added or removed entities from the selection.
Source:

(constant) g_FlareCooldown

The duration in ms for which we disable flaring after each flare to prevent overusage.
Source:

g_FlareRateLimitLastTimes

Contains the arrival timestamps the flares of the last g_FlareRateLimitScope seconds.
Source:

g_FlareRateLimitMaximumFlares

The maximum allowed number of flares within g_FlareRateLimitScope seconds. This should be a bit larger than the number of flares that can be sent in theory by using the GUI.
Source:

g_FlareRateLimitScope

The number of seconds we monitor to rate limit flares.
Source:

g_FlareSound

Sound we play when displaying a flare.
Source:

g_FollowPlayer

True if the camera should focus on attacks and player commands and select the affected units.
Source:

g_FreehandSelection_InputLine

Containing the ingame position which span the line.
Source:

(constant) g_FreehandSelection_MinLengthOfLine

Minimum length a dragged line should have to use the freehand selection.
Source:

(constant) g_FreehandSelection_MinNumberOfUnits

To start the freehandSelection function you need a minimum number of units. Minimum must be 2, for better performance you could set it higher.
Source:

(constant) g_FreehandSelection_ResolutionInputLineSquared

Minimum squared distance when a mouse move is called a drag.
Source:

g_GameSettings

Holds the actual settings & related logic. Global out of convenience in GUI controls.
Source:

g_GameSettingsLayout

This array determines the order in which the GUI controls are shown in the GameSettingTabs panel. The names correspond to property names of the GameSettingControls prototype.
Source:

g_GameType

"server" or "client"
Source:

g_HasRejoined

True if the current user has rejoined (or joined the game after it started).
Source:

g_HotkeyChangeHandlers

These events are fired when the user has performed a hotkey assignment change. Currently only fired on init, but to be fired from any hotkey editor dialog.
Source:

g_HotkeyTags

Used to highlight hotkeys in tooltip descriptions.
Source:

g_Indent

String of four spaces to be used as indentation in gui strings.
Source:

(constant) g_InitAttributes

Map, player and match settings set in game setup.
Source:

g_InsaneColor

Color used to indicate that the string entered by the player isn't a sane color.
Source:

g_IsConnecting

Whether we are attempting to join or host a game.
Source:

(constant) g_IsController

Is this user in control of game settings (i.e. is a network server, or offline player).
Source:

(constant) g_IsController

TODO: better global state handling in the GUI. In particular a bunch of those shadow gamesetup/gamesettings stuff.
Source:

g_IsController

Is this user in control of game settings (i.e. is a network server, or offline player).
Source:

(constant) g_IsNetworked

Whether this is a single- or multiplayer match.
Source:

(constant) g_IsNetworked

True if this is a multiplayer game.
Source:

g_IsNetworkedActive

Whether we have finished the synchronization and can start showing simulation related message boxes.
Source:

g_IsObserver

True if the current user has observer capabilities.
Source:

g_JumpCameraPositions

Camera jumping: when the user presses a hotkey the current camera location is marked. When pressing another camera jump hotkey the camera jumps back to that position. When the camera is already roughly at that location, jump back to where it was previously.
Source:

g_LastFlareTime

Store the last time the flare functionality was used to prevent overusage.
Source:

g_LastTickTime

Last time when onTick was called(). Used for animating the main menu.
Source:

g_LobbyGamelistReporter

The host sends a gamelist update everytime a client joins or leaves the match.
Source:

g_LobbyHandler

This class organizes all components of this GUI page.
Source:

g_LobbyRatingReporter

The participants of a rated 1v1 match send a rating report when the winner was decided.
Source:

g_MainMenuPage

This is the handler that coordinates all other handlers.
Source:

g_MapNames

Sorted list of unique maptitles. Used by mapfilter.
Source:

(constant) g_MapSizes

Used for the gamelist-filtering.
Source:

(constant) g_MapSizes

Used for creating the mapsize filter.
Source:

(constant) g_MapTypes

Used for the gamelist-filtering.
Source:

(constant) g_MaxPlayers

The maximum number of players that the engine supports. TODO: Maybe we can support more than 8 players sometime.
Source:

(constant) g_MaxTeams

The maximum number of teams allowed.
Source:

g_MilitaryTypes

Unit classes to be checked for the military-only-selection modifier and for the idle-warrior-hotkey.
Source:

g_NetMessageTypes

Handle all netmessage types that can occur.
Source:

g_NetworkOutOfSyncHandlers

These handlers are fired if the server informed the players that the networked game is out of sync.
Source:

g_NetworkStatusChangeHandlers

These handlers are fired when the match is networked and the current client established the connection, authenticated, finished the loading screen, starts or finished synchronizing after a rejoin. The messages are constructed in NetClient.cpp.
Source:

g_NetworkWarnings

Currently displayed network warnings. At most one message per user.
Source:

g_NetworkWarningTexts

Message-types to be displayed.
Source:

g_NetworkWarningTimeout

Number of milliseconds to display network warnings.
Source:

g_Nickname

Current nickname.
Source:

g_NotificationsTypes

Defines how the GUI reacts to notifications that are sent by the simulation. Don't open new pages (message boxes) here! Otherwise further notifications handled in the same turn can't access the GUI objects anymore.
Source:

g_OnSelectTab

Function to be executed when selecting a tab. The new category index is passed.
Source:

g_OptionControlDist

Vertical distance between two consecutive options.
Source:

g_OptionControlHeight

Vertical size of each option control.
Source:

g_OptionControlOffset

Vertical distance between the top of the page and the first option.
Source:

g_Options

Translated JSON file contents.
Source:

g_OptionType

Defines the parsing of config strings and GUI control interaction for the different option types.
Properties:
Name Type Description
configToValue parses a string from the user config to a value of the declared type.
valueToGui sets the GUI control to display the given value.
guiToValue returns the value of the GUI control.
guiSetter event name that should be considered a value change of the GUI control.
initGUI sets properties of the GUI control that are independent of the current value.
sanitizeValue Displays a visual clue if the entered value is invalid and returns a sane value.
tooltip appends a custom tooltip to the given option description depending on the current value.
Source:

g_OrderTabNames

Order in which the tabs should show up.
Source:

g_OverlayCounterManager

Since every GUI page can display the FPS or realtime counter, this manager is initialized for every GUI page.
Source:

g_PanelData

Array of Objects containg all relevant data per tab.
Source:

g_PanelEntityOrder

Order in which the panel entities are shown.
Source:

g_PanelsOrder

If two panels need the same space, so they collide, the one appearing first in the order is rendered. Note that the panel needs to appear in the list to get rendered.
Source:

g_PatrolTargets

Which enemy entity types will be attacked on sight when patroling.
Source:

g_PlayerAssignments

Remembers which clients are assigned to which player slots and whether they are ready. The keys are GUIDs or "local" in single-player.
Source:

g_PlayerAssignments

Remembers which clients are assigned to which player slots. The keys are GUIDs or "local" in single-player.
Source:

g_PlayerAssignmentsChangeHandlers

These handlers are called everytime a client joins or disconnects.
Source:

g_PlayerFinishedHandlers

These handlers are called when a player has been defeated or won the game.
Source:

g_Playernames

Array of unique usernames of all replays. Used for autocompleting usernames.
Source:

g_Players

Cache the basic player data (name, civ, color).
Source:

g_PlayersInitHandlers

These handlers are called after the player states have been initialized.
Source:

(constant) g_PopulationCapacities

Allow to filter by population capacity.
Source:

g_ProjectInformation

IMPORTANT: Remember to update session/top_panel/BuildLabel.xml in sync with this.
Source:

g_Replays

All replays found in the directory.
Source:

g_ReplaySelectionData

For restoring selection, order and filters when returning to the replay menu
Source:

g_ReplaysFiltered

List of replays after applying the display filter.
Source:

g_ReplaysLoaded

Skip duplicate expensive GUI updates before init is complete.
Source:

g_ResourceData

This needs to stay in the global scope, as it is used by various functions within gui/common/tooltip.js
Source:

g_ScancodesMap

Holds a map of scancode name -> user keyboard name
Source:

g_SelectedChart

Selected chart indexes.
Source:

g_SelectedReplayDirectory

Directory name of the currently selected replay. Used to restore the selection after changing filters.
Source:

g_Selection

Cache some quantities which depends only on selection
Source:

g_ServerHasPassword

Identifier if server is using password.
Source:

g_ServerName

Server title shown in the lobby gamelist.
Source:

(constant) g_Settings

An object containing all values given by setting name. Used by lobby, game setup, session, summary screen, and replay menu.
Source:

(constant) g_SettingsDirectory

Directory containing all editable settings.
Source:

g_SetupWindow

This instance owns all handlers that control the two synchronized states g_GameSettings and g_PlayerAssignments.
Source:

g_ShowAllStatusBars

Whether status bars should be shown for all of the player's units.
Source:

g_ShowGuarding

List of additional entities to highlight.
Source:

g_ShowGUI

Whether the entire UI should be hidden (useful for promotional screenshots). Can be toggled with a hotkey.
Source:

g_SimState

Cache of simulation state and template data (apart from TechnologyData, updated on every simulation update).
Source:

g_SimulationUpdateHandlers

These handlers are called each time a new turn was simulated. Use this as sparely as possible.
Source:

g_SoundNotifications

Used for acoustic GUI notifications. Define the soundfile paths and specific time thresholds (avoid spam). And store the timestamp of last interaction for each notification.
Source:

g_StatusBarUpdate

Recalculate which units have their status bars shown with this frequency in milliseconds.
Source:

g_SummarySelection

Remember last viewed summary panel and charts.
Source:

g_SummaryTypes

Colors, captions and format used for units, structures, etc. types
Source:

g_TabButtonDist

Vertical space between two tab buttons.
Source:

g_TabButtonDist

Vertical space between two tab buttons.
Source:

g_TabButtonDist

Horizontal space between two tab buttons.
Source:

g_TabButtonHeight

Vertical size of a tab button.
Source:

g_TabButtonHeight

Vertical size of a tab button.
Source:

g_TabButtonWidth

Horizontal size of a tab button.
Source:

g_TabCategoryCount

Number of categories.
Source:

g_TabCategorySelected

Index of the currently visible tab, set first tab as default.
Source:

g_TabHorizontal

Align the buttons horizontally or vertically.
Source:

g_TargetMarker

Specifies which template should indicate the target location of a player command, given a command type.
Source:

g_TutorialMessages

All tutorial messages received so far.
Source:

g_TutorialNewMessageTags

GUI tags applied to the most recent tutorial message.
Source:

g_UnitActions

List of different actions units can execute, this is mostly used to determine which actions can be executed "execute" is meant to send the command to the engine The next functions will always return false in case you have to continue to seek (i.e. look at the next entity for getActionInfo, the next possible action for the actionCheck ...) They will return an object when the searching is finished "getActionInfo" is used to determine if the action is possible, and also give visual feedback to the user (tooltips, cursors, ...) "preSelectedActionCheck" is used to select actions when the gui buttons were used to set them, but still require a target (like the guard button) "hotkeyActionCheck" is used to check the possibility of actions when a hotkey is pressed "actionCheck" is used to check the possibilty of actions without specific command. For that, the specificness variable is used "specificness" is used to determine how specific an action is, The lower the number, the more specific an action is, and the bigger the chance of selecting that action when multiple actions are possible
Source:

(constant) g_VictoryConditions

Used for gameselection details.
Source:

g_VictoryConditions

Sorted list of the victory conditions occuring in the replays
Source:

g_ViewedPlayer

The playerID selected in the change perspective tool.
Source:

g_WorkerTypes

Unit classes to be checked for the idle-worker-hotkey.
Source:

Methods

_watch()

Wrap object in a proxy, that calls callback anytime a property is set, passing the property name as parameter. Note that this doesn't modify any variable that pointer towards object, so this is _not_ equivalent to replacing the target object with a proxy.
Source:

abbreviateLargeNumbers(number)

Parameters:
Name Type Description
number number A number to shorten using SI prefix.
Source:

addNetworkWarning(msg)

Remember this warning for a few seconds. Overwrite previous warnings for this user.
Parameters:
Name Type Description
msg GUI message sent by NetServer or NetClient
Source:

addResearchToQueue()

Called by GUI when user clicks a research button.
Source:

addTrainingByPosition(position)

Add the unit shown at position to the training queue for all entities in the selection.
Parameters:
Name Type Description
position number The position of the template to train.
Source:

allowedPlayersCheck(entStates, validPlayers) → {boolean}

Checks whether the entities have the right diplomatic status with respect to the currently active player. Also "Observer" can be used.
Parameters:
Name Type Description
entStates Array.<Object> An array containing the entity states to check.
validPlayers Array.<string> An array containing the diplomatic statuses.
Source:
Returns:
- Whether the currently active player is allowed.
Type
boolean

buildListText()

Creates text in the following format: Header: value1, value2, ..., valueN This function is only used below, nowhere else.
Source:

calculateEconomyScore()

Keep this in sync with the score computation in session/ for the lobby rating reports!
Source:

calculateExplorationScore()

Keep this in sync with the score computation in session/ for the lobby rating reports!
Source:

calculateMilitaryScore()

Keep this in sync with the score computation in session/ for the lobby rating reports!
Source:

calculateScoreTotal()

Keep this in sync with the score computation in session/ for the lobby rating reports!
Source:

cancelOnLoadGameError()

This function is called from the engine whenever starting a game fails.
Source:

clampColorValue(value) → {number}

Ensure `value` is between 0 and 1.
Parameters:
Name Type Description
value number
Source:
Returns:
Type
number

clearTimeout()

deletes a timer id: of the timer
Source:

closePage()

Close GUI page and inform the parent GUI page which options changed.
Source:

colorDistance(color1, color2) → {number}

Computes the euclidian distance between the two colors. The smaller the return value, the close the colors. Zero if identical.
Parameters:
Name Type Description
color1 Object
color2 Object
Source:
Returns:
Type
number

colorizeAutocompleteHotkey()

The autocomplete hotkey is hardcoded in SDLK_TAB of CInput.cpp, as we don't want hotkeys interfering with typing text.
Source:

colorizePlayernameByID()

This function is used for AIs, whose names don't exist in g_PlayerAssignments.
Source:

colorizePlayernameParameters()

Insert the colorized playername to chat messages sent by the AI and time notifications.
Source:

controlsPlayer()

Returns true if the current user can issue commands for that player.
Source:

createReplaySelectionData()

Creates the data for restoring selection, order and filters when returning to the replay menu.
Source:

deleteReplay()

Shows a confirmation dialog and deletes the selected replay from the disk in case.
Source:

deleteReplayButtonPressed()

Callback.
Source:

deleteReplayWithoutConfirmation()

Attempts to delete the selected replay from the disk.
Source:

determineAction()

Determine the context-sensitive action that should be performed when the mouse is at (x,y)
Source:

displayGamestateNotifications()

Update the overlay with the most recent network warning of each client.
Source:

displayOptions()

Sets up labels and controls of all options of the currently selected category.
Source:

displayReplayCompatibilityError(replay)

Shows an error message stating why the replay is not compatible.
Parameters:
Name Type Description
replay Object
Source:

displayReplayDetails()

Shows preview image, description and player text in the right panel.
Source:

displayReplayList()

Filter g_Replays, fill the GUI list with that data and show the description of the current replay.
Source:

enableButtons()

Enable exactly the buttons whose dependencies are met.
Source:

EntityGroups()

EntityGroups class for managing grouped entities
Source:

EntityGroupsContainer()

EntityGroupsContainer class for managing grouped entities
Source:

EntitySelection()

EntitySelection class for managing the entity selection list and the primary selection
Source:

escapeQuotation()

Prepends a backslash to all quotation marks.
Source:

escapeText()

Escape tag start and escape characters, so users cannot use special formatting.
Source:

executeNetworkCommand(input) → {boolean}

Execute a command locally. Requires addChatMessage.
Parameters:
Name Type Description
input string
Source:
Returns:
whether a command was executed
Type
boolean

fadeColorTick(name)

Changes the color on tick.
Parameters:
Name Type Description
name string name of the object which color should be faded
Source:

filterReplay() → {bool}

Decides whether the replay should be listed.
Source:
Returns:
- true if replay should be visible
Type
bool

filterReplays()

Initializes g_ReplaysFiltered with replays that are not filtered out and sort it.
Source:

fireConfigChangeHandlers(changes)

Parameters:
Name Type Description
changes a Set of config names
Source:

formatBatchTrainingString()

Format batch training string for the tooltip Examples: buildingsCountToTrainFullBatch = 1, fullBatchSize = 5, remainderBatch = 0: "Shift-click to train 5" buildingsCountToTrainFullBatch = 2, fullBatchSize = 5, remainderBatch = 0: "Shift-click to train 10 (2*5)" buildingsCountToTrainFullBatch = 1, fullBatchSize = 15, remainderBatch = 12: "Shift-click to train 27 (15 + 12)"
Source:

formatHotkeyCombinations()

Source:
Returns:
a sorted array when @param translateScancodes is false, a formatted string otherwise.

formatLimitString()

Format entity count/limit message for the tooltip
Source:

formatMatchLimitString(matchEntLimit, matchEntCount, type) → {string}

Format template match count/limit message for the tooltip.
Parameters:
Name Type Description
matchEntLimit number The limit of the entity.
matchEntCount number The count of the entity.
type string The type of the action (i.e. "build" or "training").
Source:
Returns:
- The string to show the user with information regarding the limit of this template.
Type
string

formatPlayerInfo(playerDataArray, playerStates) → {string}

Returns a formatted string describing the player assignments. Needs g_CivData to translate!
Parameters:
Name Type Description
playerDataArray Object As known from game setup and sim state.
playerStates Array.<string> | false One of "won", "defeated", "active" for each player.
Source:
Returns:
Type
string

get(input, list, keyopt)

Returns a new list filtered and sorted by the similarity with the input text Order of sorting: 1. Exact match 2. Exact lowercase match 3. Starting letters match and sorted alphabetically 4. By similarity score (lookahead match) 5. Entry is discarded if one of the previous don't apply
Parameters:
Name Type Attributes Description
input string text to seach for
list Array.<string> | Array.<object>
key string <optional>
 text to use if the list is made up of objects
Source:

getBuildText() → {string}

Source:
Returns:
List of the names of the buildings the selected unit can build.
Type
string

getBuiltByText()

The following functions in this file work on the same basis as those in gui/common/tooltips.js Note: Due to quirks in loading order, this file might not be loaded before ReferencePage.js. Do not put anything in here that you wish to access static'ly there.
Source:

getDescriptionTooltip()

Technologies have a `description` attribute, and Auras have an `auraDescription` attribute, which becomes `description`. (For technologies, this happens in globalscripts.) (For auras, this happens either in the Auras component (for session gui) or reference/common/load.js (for Reference Suite gui))
Source:

getDisconnectReason()

Must be kept in sync with source/network/NetHost.h
Source:

getEntityCostComponentsTooltipString()

Helper function for getEntityCostTooltip.
Source:

getEntityCostTooltip()

Returns the cost information to display in the specified entity's construction button tooltip.
Source:

getEntityOrHolder(ent) → {number}

Parameters:
Name Type Description
ent number The entity to get its ID for.
Source:
Returns:
- The entity ID of the entity or of its garrisonHolder.
Type
number

getEntityTooltip()

Entity templates have a `Tooltip` tag in the Identity component. (The contents of which are copied to a `tooltip` attribute in globalscripts.) Technologies have a `tooltip` attribute.
Source:

getGameDescription()

Sets an additional map label, map preview image and describes the chosen game settings more closely. Requires g_VictoryConditions.
Source:

getHistoryTooltip()

Entity templates have a `History` tag in the Identity component. (The contents of which are copied to a `history` attribute in globalscripts.)
Source:

getLocalizedResourceAmounts()

Format resource amounts to proper english and translate (for example: "200 food, 100 wood and 300 metal").
Source:

getNeededResourcesTooltip()

Returns a message with the amount of each resource needed to create an entity.
Source:

getNetworkWarnings()

Colorizes and concatenates all network warnings. Returns text and textWidth.
Source:

getPopulationBonusTooltip()

Returns the population bonus information to display in the specified entity's construction button tooltip.
Source:

getReplayDateTime()

Returns a human-readable version of the replay date.
Source:

getReplayDuration() → {string}

Returns a human-readable version of the time when the replay started.
Source:
Returns:
Type
string

getReplayMapName() → {string}

Returns the name of the map of the given replay.
Source:
Returns:
Type
string

getReplayMonth() → {string}

Returns the month of the given replay in the format "yyyy-MM".
Source:
Returns:
Type
string

getReplayPlayernames() → {string}

Returns a human-readable list of the playernames of that replay.
Source:
Returns:
Type
string

getResearchText() → {string}

Source:
Returns:
List of the names of the technologies the selected structure/unit can research.
Type
string

getResourceSupplyTooltip()

Returns the resources this entity supplies in the specified entity's tooltip
Source:

getStatusEffectsTooltip(applier)

Parameters:
Name Type Description
applier if true, return the tooltip for the Applier. If false, Receiver is returned.
Source:

GetTemplateData()

This is needed because getEntityCostTooltip in tooltip.js needs to get the template data of the different wallSet pieces. In the session this function does some caching, but here we do that in the TemplateLoader class already.
Source:

GetTemplateData(templateName, player)

Returns template data calling GetTemplateData defined in GuiInterface.js and deepfreezing returned object.
Parameters:
Name Type Description
templateName string Data of this template will be returned.
player number | undefined Modifications of this player will be applied to the template. If undefined, id of player calling this method will be used.
Source:

getTradingTooltip()

Returns a message with the details of the trade gain.
Source:

getTrainingStatus()

Returns the number of units that will be present in a batch if the user clicks the training button depending on the batch training modifier hotkey.
Source:

getTrainText() → {string}

Source:
Returns:
List of the names of the units the selected unit can train.
Type
string

getTreasureTooltip(template) → {string}

Parameters:
Name Type Description
template Object The entity's template.
Source:
Returns:
- The resources this entity rewards to a collecter.
Type
string

getUpgradeText() → {string}

Source:
Returns:
List of the names of the buildings/units the selected structure/unit can upgrade to.
Type
string

getUsernameList() → {string}

Get a colorized list of usernames sorted by player slot, observers last. Requires g_PlayerAssignments and colorizePlayernameByGUID.
Source:
Returns:
Type
string

getWallPieceTooltip()

Returns an array of strings for a set of wall pieces. If the pieces share resource type requirements, output will be of the form '10 to 30 Stone', otherwise output will be, e.g. '10 Stone, 20 Stone, 30 Stone'.
Source:

handleNetMessages()

Process every CNetMessage (see NetMessage.h, NetMessages.h) sent by the CNetServer. Saves the received object to mainlog.html.
Source:

handleNotifications()

Processes all pending notifications sent from the GUIInterface simulation component.
Source:

hideRemaining()

Hide all children after a certain index
Source:

horizontallySpaceObjects(margin)

Horizontally spaces objects within a parent
Parameters:
Name Type Default Description
margin 0 The gap, in px, between the objects
Source:

hslToRgb(h, s, l) → {Array}

Convert color value from HSL to RGB space.
Parameters:
Name Type Description
h number hueness
s number saturation
l number lightness
Source:
See:
Returns:
Type
Array

init()

This is a transient page, triggered at the end of a game session, to perform custom computations on the endgame data.
Source:

init()

Called after the XmppConnection succeeded and when returning from a game.
Source:

init()

Initialize the dropdown containing all the available civs.
Source:

init(data)

Initialize the page.
Parameters:
Name Type Description
data Object Parameters passed from the code that calls this page into existence.
Source:

init(data)

Page initialisation. May also eventually pre-draw/arrange objects.
Parameters:
Name Type Description
data Object Contains the civCode and the name of the template to display.
Properties
Name Type Attributes Description
templateName string
civ string <optional>
Source:

init()

Initializes globals, loads replays and displays the list.
Source:

initDateFilter()

Allow to filter by month. Uses g_Replays.
Source:

initDurationFilter()

Allow to filter by game duration. Uses g_DurationFilterIntervals.
Source:

initFilters()

Reloads the selectable values in the filters. The filters depend on g_Settings and g_Replays (including its derivatives g_MapSizes, g_MapNames).
Source:

initGUIWindow()

Sets the style and title of the page.
Source:

initMapNameFilter()

Allow to filter by mapname. Uses g_MapNames.
Source:

initMapSizeFilter()

Allow to filter by mapsize. Uses g_MapSizes.
Source:

initPopCapFilter()

Allow to filter by population capacity.
Source:

isColorFadeRunning(name) → {boolean}

Checks, if a color fade on that object is running.
Parameters:
Name Type Description
name string name of the object which color fade should be checked
Source:
Returns:
- true a running fade was found
Type
boolean

isPlayerObserver()

Returns true if the player with that ID is in observermode.
Source:

isReplayCompatible()

True if we can start the given replay with the currently loaded mods.
Source:

isUndeletable()

Keep in sync with Commands.js.
Source:

loadAIDescriptions() → {Array}

Loads the descriptions as defined in simulation/ai/.../data.json and loaded by ICmpAIManager.cpp.
Source:
Returns:
Type
Array

loadAIDifficulties() → {Array}

Hardcoded, as modding is not supported without major changes. Notice the AI code parses the difficulty level by the index, not by name.
Source:
Returns:
Type
Array

loadCivData()

Returns translated history and gameplay data of all civs, optionally including a mock gaia civ.
Source:

loadMapTypes()

Hardcoded, as modding is not supported without major changes.
Source:

loadPlayerDefaults() → {Array|undefined}

Loads the default player settings (like civs and colors).
Source:
Returns:
Type
Array | undefined

loadPopulationCapacities() → {Array|undefined}

Loads available population capacities.
Source:
Returns:
Type
Array | undefined

loadReplays(replaySelectionData, compareFiles)

Store the list of replays loaded in C++ in g_Replays. Check timestamp and compatibility and extract g_Playernames, g_MapNames, g_VictoryConditions. Restore selected filters and item.
Parameters:
Name Type Description
replaySelectionData Currently selected filters and item to be restored after the loading.
compareFiles If true, compares files briefly (which might be slow with optical harddrives), otherwise blindly trusts the replay cache.
Source:

loadSettingsValues() → {Object|undefined}

Loads and translates all values of all settings which can be configured by dropdowns in the game setup.
Source:
Returns:
Type
Object | undefined

loadSettingValuesFile(filename) → {Array|undefined}

Returns an array of objects reflecting all possible values for a given setting.
Parameters:
Name Type Description
filename string
Source:
See:
  • simulation/data/settings/
Returns:
Type
Array | undefined

loadVictoryConditions() → {Array|undefined}

Loads available victoryCondtions from json files.
Source:
Returns:
Type
Array | undefined

loadWorldPopulationCapacities() → {Array.<Object>|undefined}

Loads available world population capacities.
Source:
Returns:
- An array of the world population capacities in the form: { "Population": number, "Default": number, "Title": number|String }.
Type
Array.<Object> | undefined

makePrimarySelectionGroup()

Called by unit selection buttons.
Source:

markLevelComplete()

Various utilities.
Source:

multiplyEntityCosts()

Multiplies the costs for a template by a given batch size.
Source:

ObservableMixin()

Observable is a self-proxy to enable opt-in reactive programming. Properties of an Observable can be watched, and whenever they are changed a callback will be fired.
Source:

onLogin()

The data from Engine.SendGetBoardList() is used for the leaderboard, but also for autocompletion in the profile player search field.
Source:

onTick()

Other message types (such as gamelists) may be received in case of the current player being logged in and logging in in a second program instance with the same account name. Therefore messages without handlers are ignored without reporting them here.
Source:

onTick()

Called every frame.
Source:

openDialog()

Custom dialog opening, usable by trigger maps.
Source:

placeTabButtons(categoriesData, horizontal, buttonSize, spacing, onPress, onSelect)

Create tab buttons.
Parameters:
Name Type Description
categoriesData Array Arrays of objects containing for every tab a (translated) label and tooltip.
horizontal boolean Have the tabs horizontally or vertically aligned.
buttonSize number Size of a button in the specified direction.
spacing number Distance between two buttons in the specified direction.
onPress function Function to be executed when a button is pressed, it gets the new category index passed.
onSelect function Function to be executed whenever the selection changes (so also for scrolling), it gets the new category index passed.
Source:

playerDataToStringifiedTeamList()

Merge players by team to remove duplicate Team entries, thus reducing the packet size of the lobby report.
Source:

playersFinished(players, victoryString, won)

Called when one or more players have won or were defeated.
Parameters:
Name Type Description
players array IDs of the players who have won or were defeated.
victoryString Object a plural string stating the victory reason.
won boolean whether these players have won or lost.
Source:

prepareForDropdown(settingValues) → {Object|undefined}

Creates an object with all values of that property of the given setting and finds the index of the default value. This allows easy copying of setting values to dropdown lists.
Parameters:
Name Type Description
settingValues Array
Source:
Returns:
Type
Object | undefined

ProfilableMixin()

This is an auto-proxying class that adds profiling to all method. Can be quite useful to track where time is spent in the GUI. Usage: Just add "extens Profilable" to your class and call super() in the constructor as appropriate. Give your class a name if you want the ouput to be usable. It is recommended to only use this class when actually working on profiling, or the profiler2 graph will be very cluttered.
Source:

reallyDeleteReplay(replayDirectory)

Attempts to delete the given replay directory from the disk.
Parameters:
Name Type Description
replayDirectory string
Source:

reallyStartGame()

This is a reserved function name that is executed by the engine when it is ready to start the game (i.e. loading progress has reached 100%).
Source:

reallyStartVisualReplay(replayDirectory)

Attempts the visual replay, regardless of the compatibility.
Parameters:
Name Type Description
replayDirectory string
Source:

recalculateStatusBarDisplay(remove)

Toggles the display of status bars for all of the player's entities.
Parameters:
Name Type Default Description
remove boolean false Whether to hide all previously shown status bars.
Source:

removeFromProductionQueue()

Called by GUI when user clicks a production queue item.
Source:

replayHasSameEngineVersion()

True if we can start the given replay with the currently loaded mods.
Source:

reportDisconnect(reason)

Show the disconnect reason in a message box.
Parameters:
Name Type Description
reason number
Source:

resistanceLevelToPercentageString()

Converts an resistance level into the actual reduction percentage.
Source:

resizeGUIObjectToCaption(object, align, margin)

Change the width of a GUIObject to make the caption fits nicely.
Parameters:
Name Type Description
object Object The GUIObject to consider.
align Object Directions to change the side either "left" or "right" for horizontal and "top" or "bottom" for vertical.
margin Object Margins to be added to the width and height (can be negative).
Source:

resourcesToAlphaMask()

Returns a "color:255 0 0 Alpha" string based on how many resources are needed.
Source:

restartColorFade(name)

Restarts a color fade using the parameters stored in g_ColorFade.
Parameters:
Name Type Description
name string Name of the object whose color should be faded.
Source:

rgbToGuiColor(color, alpha) → {string}

Concatenate integer color values to a string (for use in GUI objects)
Parameters:
Name Type Description
color Object
alpha number
Source:
Returns:
Type
string

rgbToHsl(r, g, b) → {Array}

Convert color value from RGB to HSL space.
Parameters:
Name Type Description
r number red
g number green
b number blue
Source:
See:
Returns:
Type
Array

sameColor(color1, color2) → {boolean}

True if the colors are identical.
Parameters:
Name Type Description
color1 Object
color2 Object
Source:
Returns:
Type
boolean

sanitizeInitAttributes()

We may encounter malformed replays.
Source:

scoreText()

The lower the score the better the match.
Source:

selectNextTab(direction)

Show next/previous panel.
Parameters:
Name Type Description
direction +1/-1 for forward/backward.
Source:

sendDialogAnswer()

Custom dialog response handling, usable by trigger maps.
Source:

setCameraFollow()

Set the camera to follow the given entity if it's a unit. Otherwise stop following.
Source:

setNewTimerFunction()

alters an function call id: of the timer func: function to call
Source:

setOutcomeIcon()

Sets the win/defeat icon to indicate current player's state.
Source:

setPanelObjectPosition()

Set the position of a panel object according to the index, from left to right, from top to bottom. Will wrap around to subsequent rows if the index is larger than rowLength.
Source:

setTimeout()

Set a timeout to call func() after 'delay' msecs. func: function to call delay: delay in ms Returns an id that can be passed to clearTimeout.
Source:

setupUnitPanel(guiName, unitEntStates, playerState)

Helper function for updateUnitCommands; sets up "unit panels" (i.e. panels with rows of icons) for the currently selected unit.
Parameters:
Name Type Description
guiName Short identifier string of this panel. See g_SelectionPanels.
unitEntStates Entity states of the selected units
playerState Player state
Source:

showReplaySummary()

Opens the summary screen of the given replay, if its data was found in that directory, , or shows an error message in case of incompatibility.
Source:

showTemplateDetails(civCodeopt)

Pauses game and opens the template details viewer for a selected entity or technology. Technologies don't have a set civ, so we pass along the native civ of the template of the entity that's researching it.
Parameters:
Name Type Attributes Description
civCode string <optional>
 The template name of the entity that researches the selected technology.
Source:

sortGUIDsByPlayerID()

Sort GUIDs of connected users sorted by playerindex, observers last. Requires g_PlayerAssignments.
Source:

soundNotification(type)

Manage acoustic GUI notifications.
Parameters:
Name Type Description
type string Notification type.
Source:

splitRatingFromNick()

Returns the nickname without the lobby rating.
Source:

startBuildingPlacement(buildTemplate)

Called by GUI when user clicks construction button.
Parameters:
Name Type Description
buildTemplate string Template name of the entity the user wants to build.
Source:

startColorFade(name, tickInterval, duration, fun_colorTransform, restartableopt, fun_smoothRestartopt)

Starts fading a color of a GUI object using the sprite argument.
Parameters:
Name Type Attributes Default Description
name string name of the object which color should be faded
tickInterval number interval in ms when the next color change should be made
duration number maximum duration of the complete fade (if 0 it runs until it is stopped)
fun_colorTransform function function which transform the colors
restartable boolean <optional>
 true if false, the fade can not be restarted; default: true
fun_smoothRestart function <optional>
 false a function, which returns a smooth tick counter, if the fade should be started; arguments: [var data]; must return false, if smooth restart was not possible and true, if it was ok
Source:

startJoin()

Connect via direct IP (used by the 'simple' MP screen)
Source:

startJoinFromLobby()

Connect via the lobby.
Source:

startReplay()

Starts the selected visual replay, or shows an error message in case of incompatibility.
Source:

stopColorFade(name, hideOverlay) → {boolean}

Stops fading a color.
Parameters:
Name Type Default Description
name string name of the object which color fade should be stopped
hideOverlay boolean true hides the overlay, if true [default: true]
Source:
Returns:
true a running fade was stopped
Type
boolean

summaryAddObject(obj1, obj2)

Add two objects property-wise and writes the result to obj1. So summaryAddObject([1, 2], [7, 42]) will result in [8, 44] and summaryAddObject({ "f": 3, "o", 5 }, { "f": -1, "o", 42 }) will result in { "f": 2, "o", 47 }.
Parameters:
Name Type Description
obj1 Object First summand object. This will be set to the sum of both.
obj2 Object Second summand object.
Source:

summaryArraySum(array)

The sum of all elements of an array. So summaryArraySum([1, 2]) will be 3 and summaryArraySum([{ "f": 3, "o", 5 }, { "f": -1, "o", 42 }]) will be { "f": 2, "o", 47 }.
Parameters:
Name Type Description
array Array The array to sum up.
Source:
Returns:
the sum of all elements.

TechnologyTemplateExists()

This would ideally be an Engine method. Or part of globalscripts. Either would be better than here.
Source:

toggleConfigBool()

Inverts the given configuration boolean and returns the current state. For example "silhouettes".
Source:

translateAIBehavior(aiBehavior)

Returns title or placeholder.
Parameters:
Name Type Description
aiBehavior string for example "defensive"
Source:

translateAIDifficulty(index)

Returns title or placeholder.
Parameters:
Name Type Description
index number index of AIDifficulties
Source:

translateAIName(aiName)

Returns title or placeholder.
Parameters:
Name Type Description
aiName string for example "petra"
Source:

translateMapSize(mapSize) → {string}

Returns title or placeholder "Default".
Parameters:
Name Type Description
mapSize number tilecount
Source:
Returns:
Type
string

translateMapType(mapType) → {string}

Returns title or placeholder.
Parameters:
Name Type Description
mapType string for example "skirmish"
Source:
Returns:
Type
string

translatePopulationCapacity(population, world) → {string}

Returns title or placeholder.
Parameters:
Name Type Description
population number
world boolean Whether the entry has world population enabled.
Source:
Returns:
Type
string

translateVictoryCondition(victoryConditionName) → {string}

Returns title or placeholder.
Parameters:
Name Type Description
victoryConditionName string For example "conquest".
Source:
Returns:
Type
string

updateBandbox() → {array}

Updates the bandbox object with new positions and visibility.
Source:
Returns:
The coordinates of the vertices of the bandbox.
Type
array

updateDisplayedNames()

Updates the primary/secondary names in the simulation and GUI.
Source:

updateTimers()

If you want to use timers, then you must call this function regularly (e.g. in a Tick handler)
Source:

updateTutorial()

Updates the tutorial panel when a new goal.
Source:

updateUnitCommands(entStates, supplementalDetailsPanel, commandsPanel)

Updates the selection panels where buttons are supposed to depend on the context. Runs in the main session loop via updateSelectionDetails(). Delegates to setupUnitPanel to set up individual subpanels, appropriately activated depending on the selected unit's state.
Parameters:
Name Type Description
entStates Entity states of the selected units
supplementalDetailsPanel Reference to the "supplementalSelectionDetails" GUI Object
commandsPanel Reference to the "commandsPanel" GUI Object
Source: