game_context¶

Source: base/tealdef/gui/main/game_context.d.tl

Notes

Types for the shared in-game GUI context (GameContext), the dialogue overlay and callout APIs, the game speed API and the base game's GUI save data.

Globals¶

Types

Name	Definition	Description
`Notification`	`declared here, defined in Notification`	A notification as sent with the `Notifications`/`add` script event and stored in `NotificationsState`.

DialogueOverlayApi¶

record global base/tealdef/gui/main/game_context.d.tl:5

global record DialogueOverlayApi

Notes

API of the mission dialogue overlay that plays voice-over dialogues, instructions and the credits.

Details

Provided by the DialogueOverlay recipe in mission/mission_react_util.tl. Get it from the game context with gameCtx.dialogueOverlayRef:get():getApi().

Functions

isPlaying() : boolean base/tealdef/gui/main/game_context.d.tl:6

Notes

Whether a dialogue or instruction is currently shown.

Returns boolean

getPlayingForTask() : string base/tealdef/gui/main/game_context.d.tl:7

Notes

Mission task UID of the dialogue or instruction currently shown.

Returns string: The task UID, or nil if nothing is playing.

areCreditsPlaying() : boolean base/tealdef/gui/main/game_context.d.tl:9

Notes

Whether the credits are currently shown.

Returns boolean

stopCredits() : boolean base/tealdef/gui/main/game_context.d.tl:10

Notes

Stops the credits if they are playing.

Returns boolean

abortCurrent() base/tealdef/gui/main/game_context.d.tl:12

Notes

Stops the credits and the current voice-over and ends the current dialogue or instruction; the next queued instruction, if any, starts.

Details

The base game calls it from the uiCloseAll input action.

skipCurrentLine() base/tealdef/gui/main/game_context.d.tl:13

Notes

Stops the current voice-over line. An instruction is ended (the next queued one starts); in a dialogue only the current line is skipped.

Details

The base game calls it from the IA_SKIP_VOICEOVER_AND_CUTSCENE input action.

enqueueUnlessExisting(taskUid : string, instructionKey : string, function() : MissionDialogueData.InstructionData) base/tealdef/gui/main/game_context.d.tl:14

Notes

Shows a mission instruction now, or queues it if something is already playing, unless the same task UID and instruction key are already queued.

Parameter	Type	Description
`taskUid`	`string`	UID of the mission task the instruction belongs to.
`instructionKey`	`string`	Key identifying the instruction within the task.
`#3`	`function() : MissionDialogueData.InstructionData`	Function that builds the instruction data; it is only called when the instruction is actually added. Returning `nil` logs an error and adds nothing.

CalloutApi¶

record global base/tealdef/gui/main/game_context.d.tl:17

global record CalloutApi

Notes

API of the callout container, a floating layer that shows one callout (a popup recipe placed next to a GUI element or at a position) at a time.

Details

In the game, get it with gameCtx.calloutContainerRef:get():getApi(); the main menu has its own container (commonParams.calloutContainerRef). Opening a new callout replaces the current one.

Example

-- from gui/construction/construction.tl
gameCtx.calloutContainerRef:get():getApi().open({
    recipe = ConstructionInfoPanelCallout,
    recipeParam = { info = nameAndDescription },
    anchor = api.type.Vec2f.new(0.0, 1.0),
    parent = params.listRef,
    getPositionFn = function() return nameAndDescription.position end,
    delay = 0.5,
})

Functions

open<R is IRecipeParamWithMeta>(CalloutParamsT<R>) base/tealdef/gui/main/game_context.d.tl:33

Notes

Shows a callout, replacing the current one. Calling it again with equal parameters keeps the open callout unchanged.

Details

The position comes from getPositionFn if given, otherwise from parent's position at gravity. It is recalculated every frame. The callout closes by itself when its parent node is destroyed.

close(any) base/tealdef/gui/main/game_context.d.tl:34

any=ReactRefWrap (interfaces don't work)

CalloutApi.CalloutParamsT¶

record base/tealdef/gui/main/game_context.d.tl:18

record CalloutParamsT<R is IRecipeParamWithMeta>

Notes

Parameters of CalloutApi.open.

Used in the base game: 10 times in 6 files

base/content/gui/gui/menu/new_game_or_map_settings_page.tl:724

} as CalloutApi.CalloutParamsT<IRecipeParamWithMeta>

base/content/gui/gui/menu/main_page.tl:395

} as CalloutApi.CalloutParamsT<IRecipeParamWithMeta>

base/content/gui/gui/main/tile_list_react_util.tl:75

} as CalloutApi.CalloutParamsT<IRecipeParamWithMeta>

base/content/gui/gui/main/callout_container.tl:10

current : CalloutApi.CalloutParamsT<IRecipeParamWithMeta>

base/content/gui/gui/main/content_card.tl:110

} as CalloutApi.CalloutParamsT<IRecipeParamWithMeta>    -- Note: teal does not understand that CalloutParamsT<TextViewParam> can be treated as subtype of CalloutPa

base/content/game_mechanics/game_mechanics/celebrations/celebration_react_util.tl:179

} as CalloutApi.CalloutParamsT<IRecipeParamWithMeta>

Fields

Name	Type	Description
`recipe`	`Recipe<R>`	Recipe rendered as the callout content.
`recipeParam`	`R`	Parameter passed to `recipe`. It is copied, and its style sheet gets `anchorPoint = anchor`.
`anchor`	`Vec2f`	Anchor point of the callout content, in relative coordinates (0..1 per axis), placed at the computed position.
`parent`	`any`	any=ReactRefWrap (interfaces don't work)
`gravity`	`Vec2f`	requires parent
`delay`	`number`	default 0 seconds
`noRepeatedDelay`	`boolean`	default false, if true, the delay will not be applied if the callout is already open

Functions

getPositionFn() : Vec2f base/tealdef/gui/main/game_context.d.tl:26

overrides automatic placement

Returns Vec2f

recipeParamCompareFn(R, R) : boolean base/tealdef/gui/main/game_context.d.tl:27

overrides default compare

Returns boolean

GameContext¶

record global base/tealdef/gui/main/game_context.d.tl:37

global record GameContext

Notes

Shared context of the in-game GUI. Holds references to the main renderer component, window container and tool stack, plus mission filters, disabled features and a few shared states.

Details

Created once by GameUIRoot in gui/main/game.tl and passed to tools, windows and HUD recipes as gameCtx (for example toolParam.gameCtx). Code that has no gameCtx can reach the most important parts through GameReactGlobals (gui/main/game_react_globals.tl).

Example

-- open a singleton window and push a tool through the context
gameCtx.windowContainer:get():getApi().addSingletonWindow(ContextHelperWindow, { gameCtx = gameCtx, onClose = onClose })
gameCtx.toolStack:get():getApi().push(FinanceTool, nil, toolParam)

Fields

Name	Type	Description
`rendererComponent`	`ReactRefWrapApiT<Builtin.RendererComponentParam, Builtin.RenderComponentAPI>`	Reference to the main 3D view (`builtin.RendererComponent`). Used, for example, as the target of `react.fireEvent(gameCtx.rendererComponent, "selectEntity", ...)`.
`windowContainer`	`ReactRefWrapApiT<Builtin.WindowContainerDelegateParam, Builtin.WindowAPI>`	Reference to the in-game window container. `gameCtx.windowContainer:get():getApi()` returns the `Builtin.WindowAPI` used to add and remove windows.
`toolStack`	`ReactRefWrapApiT<Builtin.ToolStackParam, Builtin.ToolStackAPI>`	Reference to the in-game tool stack. `gameCtx.toolStack:get():getApi()` returns the `Builtin.ToolStackAPI` used to push and pop tools.
`metroMode`	`ReactStateT<boolean>`	Shared "metro mode" state, initially `false`. The line view shows only vehicle HUD icons while it is `true` and the camera is more than 500 m above the terrain.
`preferredLayerConfig`	`ReactRefT<LayerConfig>`	Layer configuration last requested through the `preferredLayerConfig` React event (`nil` when cleared).
`dialogueOverlayRef`	`ReactRefWrapApi0<DialogueOverlayApi>`	Reference to the mission dialogue overlay; `getApi()` returns a `DialogueOverlayApi`.
`calloutContainerRef`	`ReactRefWrapApi0<CalloutApi>`	Reference to the in-game callout container; `getApi()` returns a `CalloutApi`.
`filters`	`ReactRefT<Filters>`	Current mission filters (see `GameContext.Filters`). Read with `gameCtx.filters:get()`.
`disableFeatures`	`ReactRefT<{DisableFeatures : boolean}>`	Set of currently disabled GUI features (`DisableFeatures` names mapped to `true`). Replaced by the `setDisableFeatures` React event, which the mission system fires.

Functions

accessNotificationCacheFn(Engine.Entity) : {Notification} base/tealdef/gui/main/game_context.d.tl:64

Notes

Returns the persisting notifications attached to an entity, from a cache that is refreshed every frame.

Parameter	Type	Description
`#1`	`Engine.Entity`	Entity id.

Returns {Notification}: List of notifications of the entity (each with notificationId set); empty if there are none.

focusGameBar() base/tealdef/gui/main/game_context.d.tl:72

Notes

Moves keyboard/gamepad focus to the game bar.

GameContext.Filters¶

record base/tealdef/gui/main/game_context.d.tl:38

record Filters

Notes

GUI restrictions set by the mission system (construction menu, vehicle store, protected entities, selectable entities).

Details

Filled by the setMenuFilter, setVehicleFilter, setProtectedEntities and setSelectorEntityFilter React events, which mission/mission_sim.script.tl fires when the active mission tasks change. All filters are empty by default, which means no restriction.

Used in the base game: 2 times in 2 files

base/content/gui/gui/main/selector_react_util.tl:89

allowStacking : boolean, filters? : ReactRefT<GameContext.Filters>, invertedSelectionColors? : boolean) : TreeNodeId

base/content/gui/gui/main/game.tl:135

local filters : ReactRefT<GameContext.Filters> = react.useRef({

Fields

Name	Type	Description
`menuFilter`	`MenuFilter`	Construction menu restriction.
`vehicleFilter`	`VehicleFilter`	Vehicle store restriction.
`protectedEntities`	`{Engine.Entity : ProtectionConfig \| boolean}`	Entities (lines, vehicles) the player must not change, for example in the line manager. `true` protects the entity completely; a `ProtectionConfig` protects only the listed stops of a line.
`selectorEntityFilter`	`{Engine.Entity : boolean}`	If not empty, only these entities can be hovered and selected with the default selector.

GameContext.Filters.MenuFilter¶

record base/tealdef/gui/main/game_context.d.tl:39

record MenuFilter

Notes

Restriction of the construction menu.

Details

Items are matched by construction tag: the definition's resName, with @<constructionTemplate> appended for template constructions (or the action name if there is no resource name).

Used in the base game: 5 times in 3 files

base/content/mission/mission/mission_sim.script.tl:18

menuFilter : GameContext.Filters.MenuFilter

base/content/gui/gui/construction/construction.tl:484

local getMenuFilterState = function(gameCtx : GameContext) : GameContext.Filters.MenuFilter

base/content/gui/gui/main/game.tl:149

local menuFilter = param as GameContext.Filters.MenuFilter

Fields

Name	Type	Description
`enabledItems`	`{string}`	Construction tags allowed in the construction menu. If not empty, only these items are shown and `disabledItems` is ignored.
`disabledItems`	`{string}`	Construction tags hidden from the construction menu (used when `enabledItems` is empty).
`disabledParams`	`{string}`	Ids of construction parameters to hide from the construction parameter controls.

GameContext.Filters.VehicleFilter¶

record base/tealdef/gui/main/game_context.d.tl:44

record VehicleFilter

Notes

Restriction of the vehicle store.

Used in the base game: 6 times in 3 files

base/content/mission/mission/mission_sim.script.tl:20

vehicleFilter : GameContext.Filters.VehicleFilter

base/content/gui/gui/line_vehicle_mgmt/vehicle_store_window.tl:2449

getVehicleFilterState : function() : GameContext.Filters.VehicleFilter

base/content/gui/gui/main/game.tl:153

local vehicleFilter = param as GameContext.Filters.VehicleFilter

Fields

Name	Type	Description
`enabledVehicles`	`{string}`	Model paths of the vehicles offered in the vehicle store. If not empty, other vehicles are hidden.
`disabledVehicles`	`{string}`	Model paths of vehicles hidden from the vehicle store.

GameContext.Filters.ProtectionConfig¶

record base/tealdef/gui/main/game_context.d.tl:48

record ProtectionConfig

Notes

Partial protection of an entity, used instead of true in protectedEntities.

Used in the base game: 15 times in 7 files

base/content/mission/mission/mission_sim.script.tl:22

protectedEntities : {Engine.Entity : GameContext.Filters.ProtectionConfig|boolean}

base/content/mission/mission/tasks/task_decorator.tl:342

getProtectedEntities = function(ctx : MissionInterface.TaskContext<DecoratorState<S, GS>, DecoratorParam<P, GP>>) : {Engine.Entity : GameContext.Filters.Protect

base/content/mission/mission/tasks/utility/protected_entities.tl:13

local protected : {Engine.Entity : GameContext.Filters.ProtectionConfig|boolean} = {}

base/content/mission/mission/tasks/assign_vehicle/assign_vehicle.tl:17

getProtectedEntities = function(ctx : TaskContext<S, P>) : {Engine.Entity : GameContext.Filters.ProtectionConfig|boolean}

base/content/gui/gui/line_vehicle_mgmt/vehicle_react_util.tl:321

protectedEntities : {Engine.Entity : GameContext.Filters.ProtectionConfig|boolean},

base/content/gui/gui/line_vehicle_mgmt/line_util.tl:1734

protectedEntities : {Engine.Entity : GameContext.Filters.ProtectionConfig|boolean}

… and 1 more files.

Fields

Name	Type	Description
`line`	`Line`	Protection of individual stops of a line. Required when the protected entity is a line.

GameContext.Filters.ProtectionConfig.Line¶

record base/tealdef/gui/main/game_context.d.tl:49

record Line

Notes

Protection settings for a line.

Fields

Name	Type	Description
`stationGroups`	`{Engine.Entity : boolean}`	Station groups whose stops on the line are protected (set to `true`).

GameSpeedApi¶

record global base/tealdef/gui/main/game_context.d.tl:75

global record GameSpeedApi

Notes

API of the game speed helper used by the game bar to read and change the simulation speed.

Details

Provided by the GameSpeedHelper recipe in gui/main/game.tl. Speeds are speed-up factors: 0 is paused, 1, 2 and 4 are the normal steps. Changes are sent with api.cmd.makeGameSetSpeedCmd and are clamped to api.gui.game.getEstimatedMaximumGameSpeed().

Functions

isEnabled() : boolean base/tealdef/gui/main/game_context.d.tl:76

Notes

Whether game speed control is enabled, that is the GameSpeedControl feature is not disabled.

Returns boolean

getSpeed() : integer base/tealdef/gui/main/game_context.d.tl:77

Notes

Current speed-up factor.

Returns integer: 0 when paused, otherwise the last non-zero speed-up.

setSpeed(integer) base/tealdef/gui/main/game_context.d.tl:78

Notes

Sets the speed-up factor (0 pauses). Pausing is ignored while the GameSpeedPause feature is disabled.

togglePause() base/tealdef/gui/main/game_context.d.tl:79

Notes

Pauses the game, or resumes it at the last non-zero speed.

cycleSpeed() base/tealdef/gui/main/game_context.d.tl:80

Notes

Switches to the next speed step (1, 2, 4, then back to 1); when paused, resumes at speed 1.

BaseGUISaveData¶

record global base/tealdef/gui/main/game_context.d.tl:83

global record BaseGUISaveData

Notes

GUI data the base game stores in the savegame, read with api.gui.game.getGuiSaveData("") and written with api.gui.game.setGuiSaveData("", data).

Example

-- from gui/hud/cargo_flow.script.tl
local hudFilter = (api.gui.game.getGuiSaveData("") as BaseGUISaveData).hudFilter
if not hudFilter or hudFilter.showCargoFlow then
    -- draw cargo flow
end

Fields

Name	Type	Description
`hudFilter`	`HUDFilter`	HUD icon filter settings; `nil` until the player changes a filter.

BaseGUISaveData.FilterState¶

enum base/tealdef/gui/main/game_context.d.tl:84

enum FilterState

Notes

Visibility of one kind of HUD icon.

Value	Description
`"Hidden"`	The icons are hidden.
`"Default"`	The icons are shown (default).

BaseGUISaveData.HUDFilter¶

record base/tealdef/gui/main/game_context.d.tl:88

record HUDFilter

Notes

Settings of the HUD icon filter layer (gui/layers/layer_hud_filter.tl). Missing entries count as shown.

Used in the base game: 2 times in 1 file

base/content/gui/gui/layers/layer_hud_filter.tl:36

local hudFilterState = engine_react_util.useStepState(function() : BaseGUISaveData.HUDFilter

Fields

Name	Type	Description
`preFilters`	`{Engine.ComponentType : FilterState}`	Visibility of HUD icons per component type (stations, industries, warehouses, towns, landmarks).
`preFilterTvCarriers`	`{Carrier : FilterState}`	Visibility of vehicle HUD icons per carrier (rail, road, tram, water, air). If all carriers are hidden, vehicle icons are hidden completely.
`showIncome`	`boolean`	Whether income HUD icons are shown (the "Income" toggle).
`showCosts`	`boolean`	Whether cost HUD icons are shown (the "Costs" toggle).
`showEventIcons`	`boolean`	Whether event icons (for example happiness changes, marketing and greening effects) are shown (the "Events" toggle).
`showCargoFlow`	`boolean`	Whether cargo flow is shown (the "Cargo Flow" toggle).