new GuiInterface()
- Source:
Methods
AddTimeNotification()
Add a timed notification.
Warning: timed notifacations are serialised
(to also display them on saved games or after a rejoin)
so they should allways be added and deleted in a deterministic way.
- Source:
CheckTechnologyRequirements()
Checks whether the requirements for this technology have been met.
- Source:
DisplayRallyPoint()
Displays the rally points of a given list of entities (carried in cmd.entities).
The 'cmd' object may carry its own x/z coordinate pair indicating the location where the rally point should
be rendered, in order to support instantaneously rendering a rally point marker at a specified location
instead of incurring a delay while PostNetworkCommand processes the set-rallypoint command (see input.js).
If cmd doesn't carry a custom location, then the position to render the marker at will be read from the
RallyPoint component.
- Source:
FindIdleUnits()
Find any idle units.
Parameters:
| Name | Type | Description |
|---|---|---|
data.idleClasses |
Array of class names to include. | |
data.prevUnit |
The previous idle unit, if calling a second time to iterate through units. May be left undefined. | |
data.limit |
The number of idle units to return. May be left undefined (will return all idle units). | |
data.excludeUnits |
Array of units to exclude. Returns an array of idle units. If multiple classes were supplied, and multiple items will be returned, the items will be sorted by class. |
- Source:
GetBattleState()
Returns the battle state of the player.
- Source:
GetCampaignGameEndData()
Called when the game ends if the current game is part of a campaign run.
- Source:
GetEntityState()
Get common entity info, often used in the gui.
- Source:
GetExtendedSimulationState()
Returns global information about the current game state, plus statistics.
This is used by the GUI at the end of a game, in the summary screen.
Note: Amongst statistics, the team exploration map percentage is computed from
scratch, so the extended simulation state should not be requested too often.
- Source:
GetFoundationSnapData()
Given the current position {data.x, data.z} of an foundation of template data.template, returns the position and angle to snap
it to (if necessary/useful).
Parameters:
| Name | Type | Description |
|---|---|---|
data.x |
The X position of the foundation to snap. | |
data.z |
The Z position of the foundation to snap. | |
data.template |
The template to get the foundation snapping data for. | |
|
||
|
- Source:
GetIncomingAttacks()
Returns a list of ongoing attacks against the player.
- Source:
GetInitAttributes()
Returns the gamesettings that were chosen at the time the match started.
- Source:
GetNeededResources()
Used to show a red square over GUI elements you can't yet afford.
- Source:
GetReplayMetadata()
This data will be stored in the replay metadata file after a match has been finished recording.
- Source:
GetSimulationState()
Returns global information about the current game state.
This is used by the GUI and also by AI scripts.
- Source:
GetStartedResearch()
Returns technologies that are being actively researched, along with
which entity is researching them and how far along the research is.
- Source:
HasIdleUnits()
Discover if the player has idle units.
Parameters:
| Name | Type | Description |
|---|---|---|
data.idleClasses |
Array of class names to include. | |
data.excludeUnits |
Array of units to exclude. Returns a boolean of whether the player has any idle units |
- Source:
IdleUnitFilter(unit, idleclasses, excludeUnits)
Whether to filter an idle unit
Parameters:
| Name | Type | Description |
|---|---|---|
unit |
The unit to filter. | |
idleclasses |
Array of class names to include. | |
excludeUnits |
Array of units to exclude. Returns an object with the following fields: - idle - true if the unit is considered idle by the filter, false otherwise. - bucket - if idle, set to the index of the first matching idle class, undefined otherwise. |
- Source:
OnDisabledTemplatesChanged()
Some changes may require an update to the selection panel,
which is cached for efficiency. Inform the GUI it needs reloading.
- Source:
OnTemplateModification()
State of the templateData (player dependent): true when some template values have been modified
and need to be reloaded by the gui.
- Source:
SetBuildingPlacementPreview()
Display the building placement preview.
cmd.template is the name of the entity template, or "" to disable the preview.
cmd.x, cmd.z, cmd.angle give the location.
Returns result object from CheckPlacement:
{
"success": true iff the placement is valid, else false
"message": message to display in UI for invalid placement, else ""
"parameters": parameters to use in the message
"translateMessage": localisation info
"translateParameters": localisation info
"pluralMessage": we might return a plural translation instead (optional)
"pluralCount": localisation info (optional)
}
- Source:
SetWallPlacementPreview()
Previews the placement of a wall between cmd.start and cmd.end, or just the starting piece of a wall if cmd.end is not
specified. Returns an object with information about the list of entities that need to be newly constructed to complete
at least a part of the wall, or false if there are entities required to build at least part of the wall but none of
them can be validly constructed.
It's important to distinguish between three lists of entities that are at play here, because they may be subsets of one
another depending on things like snapping and whether some of the entities inside them can be validly positioned.
We have:
- The list of entities that previews the wall. This list is usually equal to the entities required to construct the
entire wall. However, if there is snapping to an incomplete tower (i.e. a foundation), it includes extra entities
to preview the completed tower on top of its foundation.
- The list of entities that need to be newly constructed to build the entire wall. This list is regardless of whether
any of them can be validly positioned. The emphasishere here is on 'newly'; this list does not include any existing
towers at either side of the wall that we snapped to. Or, more generally; it does not include any _entities_ that we
snapped to; we might still snap to e.g. terrain, in which case the towers on either end will still need to be newly
constructed.
- The list of entities that need to be newly constructed to build at least a part of the wall. This list is the same
as the one above, except that it is truncated at the first entity that cannot be validly positioned. This happens
e.g. if the player tries to build a wall straight through an obstruction. Note that any entities that can be validly
constructed but come after said first invalid entity are also truncated away.
With this in mind, this method will return false if the second list is not empty, but the third one is. That is, if there
were entities that are needed to build the wall, but none of them can be validly constructed. False is also returned in
case of unexpected errors (typically missing components), and when clearing the preview by passing an empty wallset
argument (see below). Otherwise, it will return an object with the following information:
result: {
'startSnappedEnt': ID of the entity that we snapped to at the starting side of the wall. Currently only supports towers.
'endSnappedEnt': ID of the entity that we snapped to at the (possibly truncated) ending side of the wall. Note that this
can only be set if no truncation of the second list occurs; if we snapped to an entity at the ending side
but the wall construction was truncated before we could reach it, it won't be set here. Currently only
supports towers.
'pieces': Array with the following data for each of the entities in the third list:
[{
'template': Template name of the entity.
'x': X coordinate of the entity's position.
'z': Z coordinate of the entity's position.
'angle': Rotation around the Y axis of the entity (in radians).
},
...]
'cost': { The total cost required for constructing all the pieces as listed above.
'food': ...,
'wood': ...,
'stone': ...,
'metal': ...,
'population': ...,
}
}
Parameters:
| Name | Type | Description |
|---|---|---|
cmd.wallSet |
Object holding the set of wall piece template names. Set to an empty value to clear the preview. | |
cmd.start |
Starting point of the wall segment being created. | |
cmd.end |
(Optional) Ending point of the wall segment being created. If not defined, it is understood that only the starting point of the wall is available at this time (e.g. while the player is still in the process of picking a starting point), and that therefore only the first entity in the wall (a tower) should be previewed. | |
cmd.snapEntities |
List of candidate entities to snap the start and ending positions to. |
- Source: