mission_interface¶

Source: base/tealdef/mission/mission_framework/mission_interface.d.tl

onCompleteScriptFn : string onCompleteScriptFnParams : any getTaskInfoScriptFn : string getTaskInfoScriptFnParams : any

Notes

Core types of the mission framework, shared by missions, the tutorial and the guide system. It defines task scripts, task state, the task info shown in the mission window and the APIs passed to task callbacks.

MissionInterface¶

record global base/tealdef/mission/mission_framework/mission_interface.d.tl:3

global record MissionInterface

Notes

Namespace of the core mission-framework types. A mission is a list of tasks; each task is run by a TaskScript and described by static data.

Details

How the pieces fit together (from mission/mission_sim.script.tl and the campaign mods):

A mod registers a generic resource of type missiontask_boot (mission), tutorial_boot (tutorial) or guide_system_boot (guide system). Its data is a BootstrapDesc whose bootstrapScriptFn points to the spawnBootTasks function of a module built with MissionBootUtil.makeMission / makeGuide.
The game script ::mission/mission.gs (or the guide-system script) calls each bootstrap function once per savegame (remembered in MissionState.bootTypes); it adds the boot tasks.
Each task is identified by a TaskConfig. The framework resolves its TaskVTable through getVTableScriptFn, which returns the task's TaskScript and its static params from the story's task-data factory (MissionTaskUtil.StaticTaskInfo).
Every update the framework calls onUpdate and isComplete of each open task. When a task completes, onComplete runs and its followup tasks are added.

State is kept in the game script state (MissionState); everything in StaticTaskInfo (functions included) is re-created from the story code and never saved.

Example

-- mission.res.lua of urbangames_campaign_mission_01
function data()
return {
    type = "missiontask_boot",
    data = {
        bootstrapScriptFn = "urbangames_campaign_mission_01::/mission/mission.script@mission.spawnBootTasks",
        bootstrapScriptFnParams = nil,
    }
}
end

-- mission.script.lua
local mission = require "mission.tl"
function data()
    return { mission = mission }
end

MissionInterface.GameScriptMode¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:4

enum GameScriptMode

Notes

Which framework instance a game script runs, either the mission (missions and the tutorial) or the guide system.

Used in the base game: 1 time in 1 file

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

local trySpawnBootstrap = function(gameScriptMode : MissionInterface.GameScriptMode, scriptState : GameScriptState<MissionInterface.MissionState>, state : Missi

Value	Description
`"GuideSystem"`	Guide-system instance; boots from `guide_system_boot` resources and only runs when guides are enabled in the app config.
`"Mission"`	Mission instance; boots from `missiontask_boot` resources, or from `tutorial_boot` when no mission is present.

MissionInterface.CaptureParams¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:8

record CaptureParams

Notes

Parameters that the game-script resource (mission.gs.lua) passes to the framework's update and event scripts.

Used in the base game: 3 times in 1 file

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

local params = captureParams as MissionInterface.CaptureParams

Fields

Name	Type	Description
`gameScriptMode`	`GameScriptMode`	Which instance of the framework this game script is.

MissionInterface.MissionSavegameUtil¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:12

record MissionSavegameUtil

Load: local mission_savegame_util = ug_require "::/mission/mission_savegame_util.tl"

Notes

Helpers that prepare a mission savegame.

Used in the base game: 9 times in 9 files

base/content/mission/mission/mission_savegame_util.tl:3

local mission_savegame_util : MissionInterface.MissionSavegameUtil = {}

mods/release/urbangames_campaign_mission_03/content/init/init/init.script.tl:1

local mission_savegame_util = ug_require "::/mission/mission_savegame_util.tl" as MissionInterface.MissionSavegameUtil

mods/release/urbangames_campaign_mission_07/content/init/init/init.script.tl:1

local mission_savegame_util = ug_require "::/mission/mission_savegame_util.tl" as MissionInterface.MissionSavegameUtil

mods/release/urbangames_campaign_mission_02/content/init/init/init.script.tl:1

local mission_savegame_util = ug_require "::/mission/mission_savegame_util.tl" as MissionInterface.MissionSavegameUtil

mods/release/urbangames_campaign_mission_06/content/init/init/init.script.tl:1

local mission_savegame_util = ug_require "::/mission/mission_savegame_util.tl" as MissionInterface.MissionSavegameUtil

mods/release/urbangames_campaign_mission_01/content/init/init/init.script.tl:1

local mission_savegame_util = ug_require "::/mission/mission_savegame_util.tl" as MissionInterface.MissionSavegameUtil

… and 3 more files.

Functions

updateTownBuildings() base/tealdef/mission/mission_framework/mission_interface.d.tl:13

Call as mission_savegame_util.updateTownBuildings

Notes

Rebuilds every construction that contains town buildings, so they are refreshed from their current resources.

Used in the base game: 8 times in 8 files

mods/release/urbangames_campaign_mission_03/content/init/init/init.script.tl:56

mission_savegame_util.updateTownBuildings()

mods/release/urbangames_campaign_mission_07/content/init/init/init.script.tl:17

mission_savegame_util.updateTownBuildings()

mods/release/urbangames_campaign_mission_02/content/init/init/init.script.tl:16

mission_savegame_util.updateTownBuildings()

mods/release/urbangames_campaign_mission_06/content/init/init/init.script.tl:16

mission_savegame_util.updateTownBuildings()

mods/release/urbangames_campaign_mission_01/content/init/init/init.script.tl:16

mission_savegame_util.updateTownBuildings()

mods/release/urbangames_campaign_mission_05/content/init/init/init.script.tl:16

mission_savegame_util.updateTownBuildings()

… and 2 more files.

updateMaintenanceCost() base/tealdef/mission/mission_framework/mission_interface.d.tl:14

Call as mission_savegame_util.updateMaintenanceCost

Notes

Resets the maintenance cost of every entity that has one, and removes the owner of street/track edges that do not belong to a construction.

Used in the base game: 8 times in 8 files

mods/release/urbangames_campaign_mission_03/content/init/init/init.script.tl:65

mission_savegame_util.updateMaintenanceCost()

mods/release/urbangames_campaign_mission_07/content/init/init/init.script.tl:23

mission_savegame_util.updateMaintenanceCost()

mods/release/urbangames_campaign_mission_02/content/init/init/init.script.tl:19

mission_savegame_util.updateMaintenanceCost()

mods/release/urbangames_campaign_mission_06/content/init/init/init.script.tl:19

mission_savegame_util.updateMaintenanceCost()

mods/release/urbangames_campaign_mission_01/content/init/init/init.script.tl:19

mission_savegame_util.updateMaintenanceCost()

mods/release/urbangames_campaign_mission_05/content/init/init/init.script.tl:19

mission_savegame_util.updateMaintenanceCost()

… and 2 more files.

updateIndustriesPlayerOwned(except? : {Engine.Entity}) base/tealdef/mission/mission_framework/mission_interface.d.tl:15

Call as mission_savegame_util.updateIndustriesPlayerOwned

Notes

Removes the owner (sets player -1) of every industry construction.

Parameter	Type	Description
`except?`	`{Engine.Entity}`	Industry entities to leave unchanged.

Used in the base game: 8 times in 8 files

mods/release/urbangames_campaign_mission_03/content/init/init/init.script.tl:68

mission_savegame_util.updateIndustriesPlayerOwned()

mods/release/urbangames_campaign_mission_07/content/init/init/init.script.tl:20

mission_savegame_util.updateIndustriesPlayerOwned(params.entityList_decorationIndustries)

mods/release/urbangames_campaign_mission_02/content/init/init/init.script.tl:22

mission_savegame_util.updateIndustriesPlayerOwned()

mods/release/urbangames_campaign_mission_06/content/init/init/init.script.tl:22

mission_savegame_util.updateIndustriesPlayerOwned()

mods/release/urbangames_campaign_mission_01/content/init/init/init.script.tl:22

mission_savegame_util.updateIndustriesPlayerOwned()

mods/release/urbangames_campaign_mission_05/content/init/init/init.script.tl:22

mission_savegame_util.updateIndustriesPlayerOwned()

… and 2 more files.

MissionInterface.MissionLegacyUtil¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:18

record MissionLegacyUtil

Load: local mission_legacy_util = ug_require "/mission/mission_framework/mission_legacy_util.tl"

Notes

Upgrades a mission state saved by an older game version.

Used in the base game: 2 times in 2 files

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

local mission_legacy_util = ug_require "/mission/mission_framework/mission_legacy_util.tl" as MissionInterface.MissionLegacyUtil

base/content/mission/mission/mission_framework/mission_legacy_util.tl:4

local mission_legacy_util : MissionInterface.MissionLegacyUtil = {}

Fields

Name	Type	Description
`currentVersion`	`integer`	Current version of the mission state layout (4 in the base game). used 1× in the base game

Functions

updateLegacyState(missionState : MissionState) base/tealdef/mission/mission_framework/mission_interface.d.tl:20

Call as mission_legacy_util.updateLegacyState

Notes

Fills fields missing in older states, removes tasks whose static data no longer exists (needTaskDeletion), calls each task script's handleLegacy and sets version to currentVersion.

Parameter	Type	Description
`missionState`	`MissionState`	Mission state to upgrade in place.

Used in the base game: 1 time in 1 file

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

mission_legacy_util.updateLegacyState(missionState)

MissionInterface.TaskVTable¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:23

record TaskVTable<S, P>

Notes

Per-task lookup table through which the framework reaches a task's script, its static params and its callbacks. Built by MissionBootUtil from the story's StaticTaskInfo.

Used in the base game: 8 times in 2 files

base/content/mission/mission/mission_boot_util.tl:80

spawnFn : SpawnFn) : MissionInterface.TaskVTable<any, any>

base/content/mission/mission/mission_framework/mission_framework_util.tl:5

local vtableCache : {string : MissionInterface.TaskVTable<any, any>} = {}

Functions

getGenericParams() : GenericTaskParams base/tealdef/mission/mission_framework/mission_interface.d.tl:24

Notes

Returns the framework-level params of the task (filters, rules, medals, rewards, ...).

Returns GenericTaskParams: Generic params, cached per task key.

getSpecificParams() : P base/tealdef/mission/mission_framework/mission_interface.d.tl:25

Notes

Returns the task-type specific params (StaticTaskInfo.taskParams).

Returns P: The Params value of the task's script type.

onComplete(TaskContext<S, P>, MissionTaskApi) base/tealdef/mission/mission_framework/mission_interface.d.tl:27

Notes

Called by the framework after a task completed; the boot util uses it to add the task's followup tasks.

Parameter	Type	Description
`#1`	`TaskContext<S, P>`	Context of the completed task.
`#2`	`MissionTaskApi`	API to add further tasks.

getTaskInfo(TaskContext<S, P>) : TaskInfo base/tealdef/mission/mission_framework/mission_interface.d.tl:28

Notes

Returns what the mission window shows for the task (missions only).

Parameter	Type	Description
`#1`	`TaskContext<S, P>`	Context of the task.

Returns TaskInfo: The static taskInfo, with progress copied in from the task's generic state.

getGuideInfo(TaskContext<S, P>) : GuideInfo base/tealdef/mission/mission_framework/mission_interface.d.tl:29

Notes

Returns the hint shown for a guide task (guide system only).

Parameter	Type	Description
`#1`	`TaskContext<S, P>`	Context of the task.

Returns GuideInfo: The static guideInfo of the task.

getTaskScript() : TaskScript<S, P> base/tealdef/mission/mission_framework/mission_interface.d.tl:30

Notes

Returns the script that implements the task.

Returns TaskScript<S, P>: Task script (StaticTaskInfo.taskScript).

needTaskDeletion() : boolean base/tealdef/mission/mission_framework/mission_interface.d.tl:32

Notes

Tells whether the task no longer exists in the story (its static data is nil); such saved tasks are removed on load.

Returns boolean: true if the task should be deleted.

MissionInterface.TaskConfig¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:35

record TaskConfig

Notes

Saved identification of a task. It names the function that builds its vtable, the argument for it, and the task's unique key.

Details

MissionBootUtil creates it as { getVTableScriptFn = scriptKey .. "@mission.getVTable", getVTableScriptFnParams = taskKey, uniqueKey = MissionTaskUtil.makeTaskKey(taskKey, scriptKey) }.

Used in the base game: 5 times in 3 files

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

local addTask = function<TaskSpecificState>(state : MissionInterface.MissionState, currentGameTime : number, specific : TaskSpecificState, taskConfig : MissionI

base/content/mission/mission/mission_boot_util.tl:36

local makeTaskConfig = function(key : string) : MissionInterface.TaskConfig

base/content/mission/mission/mission_framework/mission_framework_util.tl:7

function mission_framework_util.getVTable(config : MissionInterface.TaskConfig) : MissionInterface.TaskVTable<any, any>

Fields

Name	Type	Description
`getVTableScriptFn`	`string`	Script function (`"<script>@<path.to.fn>"`) called with `getVTableScriptFnParams` and `uniqueKey` to obtain the task's `TaskVTable`.
`getVTableScriptFnParams`	`any`	First argument for `getVTableScriptFn`; the boot util passes the task key from the story.
`uniqueKey`	`string`	key created as bootstrapper"\|\|"unique-key-inside-bootstrapper

MissionInterface.TaskProgressData¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:46

record TaskProgressData

Notes

Progress of a task (or sub-task) as shown in the mission window. Which fields are set decides how it is drawn.

Details

Drawing order in MissionFrameworkReactUtil.makeTaskProgressItem: bool (check mark or cross, optionally next to a counter), then townRatingKey (rating icon; needs cargoTypeRes, counter and entity), then counter (with cargo icon if cargoTypeRes, as "text current/max" if max is set), then percentage, text, dynamicText. iconPath adds an icon in front of the result.

Used in the base game: 3 times in 1 file

base/content/mission/mission/mission_framework/mission_framework_react_util.tl:29

local function makeCargoIconProgress(progress : MissionInterface.TaskProgressData, perYear? : boolean) : TreeNodeId

Fields

Name	Type	Description
`iconPath`	`string`	Path of an icon shown in front of the progress.
`cargoTypeRes`	`ResName`	Cargo type resource (e.g. `"::/cargos/fish/fish.cargo"`) whose icon is shown with the counter.
`bool`	`boolean`	Done / not done flag, drawn as a check mark or a cross.
`text`	`string`	Label of the progress (e.g. "Trees Removed"); a static `text` from the task info overrides the runtime one.
`dynamicText`	`string`	Text computed at runtime, shown when no other progress form applies.
`counter`	`Counter`	Count towards a target.
`percentage`	`number`	range: 0.0 - 1.0
`progressBar`	`boolean`
`style`	`Style`
`townRatingKey`	`TownRatingKey`	Town rating whose icon is shown (needs `entity`, `cargoTypeRes` and `counter`).
`entity`	`Engine.Entity`	Town entity for `townRatingKey`.

MissionInterface.TaskProgressData.Counter¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:47

record Counter

Notes

Integer progress counter.

Fields

Name	Type	Description
`current`	`integer`	Current count.
`max`	`integer`	Target count; when `nil` only the current count is shown.

MissionInterface.TaskProgressData.Style¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:51

enum Style

No description in the game files yet.

Value	Description
`"Good"`
`"Neutral"`
`"Bad"`

MissionInterface.BootstrapDesc¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:70

record BootstrapDesc

Notes

data of a missiontask_boot, tutorial_boot or guide_system_boot generic resource: the function that spawns the first tasks.

Example

function data()
return {
    type = "guide_system_boot",
    data = {
        bootstrapScriptFn = "urbangames_campaign_mission_01::/guide_system/guide_system.script@guide_system.spawnBootTasks",
        bootstrapScriptFnParams = nil,
    }
}
end

Used in the base game: 1 time in 1 file

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

local bootstrapDesc = gr.data as MissionInterface.BootstrapDesc

Fields

Name	Type	Description
`bootstrapScriptFn`	`string`	Script function (`"<script>@<path.to.fn>"`) called once per savegame as `fn(bootstrapScriptFnParams, nil, missionTaskApi)`.
`bootstrapScriptFnParams`	`string`	First argument passed to `bootstrapScriptFn`.

MissionInterface.MissionSoundtrack¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:75

record MissionSoundtrack

Notes

Tracklist that a task puts on the music player while it is open.

Used in the base game: 2 times in 1 file

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

currentSoundtrack : MissionInterface.MissionSoundtrack

Fields

Name	Type	Description
`mode`	`AddMode`	the mode to use when adding the tracklist to the music player default: "set"
`enableRepeat`	`boolean`	when true, repeats the entire tracklist default: "true"
`tracks`	`{Track}`	the list of tracks to play

MissionInterface.MissionSoundtrack.Track¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:77

record Track

describe a single track of the tracklist

Notes

One track of a tracklist.

Fields

Name	Type	Description
`name`	`string`	the name of the track, this is optional
`file`	`string`	the path to the track file, this is required
`enableRepeat`	`boolean`	when true, repeats a single track default: "false"

MissionInterface.MissionSoundtrack.AddMode¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:88

enum AddMode

a mode that controls how a tracklist is added to the music player

Value	Description
`"add"`	pushes the given tracklist on top of the current tracklist; when the tracklist ends, resumes the previous tracklist.
`"set"`	replaces the current tracklist with the given tracklist.

MissionInterface.HighlightStyle¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:105

enum HighlightStyle

Notes

Shape of the highlight drawn around a GUI element (api.gui.HighlightStyle).

Used in the base game: 5 times in 3 files

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

knownHighlightOverride : {string : MissionInterface.HighlightStyle}

base/content/mission/mission/mission_task_util.tl:42

local highlightRules : {string : MissionInterface.HighlightStyle} = {}

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

getHighlightRules = function(ctx : MissionInterface.TaskContext<DecoratorState<S, GS>, DecoratorParam<P, GP>>) : { string : MissionInterface.HighlightStyle }

Value	Description
`"Circle"`	Circle highlight.
`"Square"`	Rectangle highlight.
`"Mask"`	Mask highlight.

MissionInterface.GenericTaskParams¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:111

record GenericTaskParams

Notes

Framework-level params of a task, applied while the task is open. Built from MissionTaskUtil.StaticTaskInfo by MissionTaskUtil.extractGenericParams.

Used in the base game: 6 times in 3 files

base/content/mission/mission/mission_boot_util.tl:13

: GetTaskDataFn, {string : MissionInterface.GenericTaskParams}, SpawnFn

base/content/mission/mission/mission_task_util.tl:37

function mission_task_util.extractGenericParams(taskKey : string, getTaskData : function(string) : MissionTaskUtil.StaticTaskInfo) : MissionInterface.GenericTas

base/content/mission/mission/mission_framework/mission_framework_react.tl:23

genericParams : MissionInterface.GenericTaskParams

Fields

Name	Type	Description
`isBonusTask`	`boolean`	Marks the task as a bonus mission (window title "Bonus Mission").
`medals`	`{string : boolean}`	Medal ids (from `info.mission.lua`) noted as earned in the user profile while the task exists.
`stars`	`{string : boolean}`	Star ids (from `info.mission.lua`) and their state, noted in the user profile.
`visibilityRules`	`{string : boolean}`	GUI element class -> visible flag, applied with `api.gui.byId.setVisibilityByClass` while the task is open.
`enableRules`	`{string : boolean}`	GUI element id/tag -> enabled flag while the task is open.
`highlightRules`	`{string : HighlightStyle}`	GUI element id/tag -> highlight style while the task is open.
`omitNotificationOnComplete`	`boolean`	Suppresses the "task complete" notification of a task shown in the history.
`startSoundtrack`	`string`	Music track started with `api.gui.musicPlayer.playTrack` when the task opens.
`soundtrack`	`MissionSoundtrack`	Tracklist put on the music player while the task is open.
`playlistOverride`	`ResName`	Playlist resource that replaces the music playlist while the task is open.
`disableGuideSystem`	`boolean`	Marks the task as one during which the guide system stays inactive (cutscene and dialogue tasks set it).
`allowBuyVehicles`	`{string : integer}`	todo, also enable accounting for existing vehicles Vehicle model -> maximum number the player may own. If any open task sets it, only listed models can be bought.
`allowBuyVehicleGroups`	`{string : {{string}, integer}}`	id, -> modelnames, count Group id -> `{ model names, count }`.
`lockedVehicles`	`{Engine.Entity}`	entity ids that may not be sold Vehicle entities that may not be sold.
`notificationFilter`	`{string : boolean}`	Notification types (script paths) hidden while the task is open.
`menuFilter`	`GameContext.Filters.MenuFilter`	Menu items enabled or disabled while the task is open.
`vehicleFilter`	`GameContext.Filters.VehicleFilter`	Vehicles enabled or disabled in the vehicle store while the task is open.
`selectorEntityFilter`	`{Engine.Entity : boolean}`	Entities that may (or may not) be selected in the world while the task is open.
`disableFeatures`	`{DisableFeatures : boolean}`	GUI features switched off while the task is open (e.g. `Layers`, `HudIconMaster`).
`spawnGuide`	`{string}`	Script events sent when the task is added; with an instruction voice-over they are delayed until it starts (at most 25 s).
`requiredTaskToComplete`	`string`	taskkey <- mission_task_util.makeTaskKey Unique key (`MissionTaskUtil.makeTaskKey`) of a task that must be complete before this one can complete.
`allowSimultaneousUiTasks`	`{string}`	taskkey <- mission_task_util.makeTaskKey Unique keys of tasks whose `onGuiKickOff` may run while this task's UI (cutscene, dialogue) is running.
`financialReward`	`integer`	Money booked as income when the task completes, in game currency; also shows a notification.
`showInHistory`	`boolean`	Keeps the task in the mission window after completion and sends a completion notification.
`showInGuiWithoutName`	`boolean`	Shows the task in the mission window even without a name.
`suppressAutoOpen`	`boolean`	Keeps the mission window from opening automatically for this task.

MissionInterface.GenericTaskState¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:145

record GenericTaskState

Notes

Framework-managed state of a task, saved with the mission.

Used in the base game: 1 time in 1 file

mods/release/urbangames_campaign_mission_05/content/mission/mission/tasks/drilling/observe_drilling.tl:8

local function hasInstructionsToBePlayed(taskState : MissionInterface.GenericTaskState) : boolean

Fields

Name	Type	Description
`uid`	`string`	Runtime id `"<taskScriptName>#<n>"`; also the event id under which the task receives its own events.
`config`	`TaskConfig`	Saved identification of the task.
`acceptedTime`	`number`
`spawnTime`	`number`	Game time (ms) at which the task was added.
`guiSpawnTime`	`number`	Mission GUI time (seconds) at which the task was added.
`completedTime`	`number`	Game time at which the task completed; `nil` while it is open.
`optionDecision`	`any`	decision in case getTaskInfo() offered options Key of the option button the player clicked (`Decision` event). A value of `"finish"`, or a string starting with `finish`, completes the task.
`progress`	`TaskProgressData`	Runtime progress shown in the mission window.
`subTasksProgress`	`{TaskProgressData}`	Runtime progress of the sub-tasks, in the order of `TaskInfo.subTasks`.
`instructionsQueue`	`{InstructionQueueEntry}`	Extra instructions queued by the task.
`taskInstructionState`	`InstructionQueueEntry.InstructionState`	the task's own TaskInfo.instructionData, which is played directly by the gui and never enters instructionsQueue
`guideQueue`	`{GuideQueueEntry}`	Pending `spawnGuide` events of the task.
`guideTimeoutTime`	`number`	gui time at which a pending guideQueue fires even though the task's instruction never started

MissionInterface.GenericTaskState.InstructionQueueEntry¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:160

record InstructionQueueEntry

Notes

An extra instruction (voice-over) queued by a task, with its playback state.

Used in the base game: 6 times in 5 files

base/content/mission/mission/tasks/wait/wait_ui_event.tl:67

local instruction : MissionInterface.GenericTaskState.InstructionQueueEntry = {

base/content/mission/mission/tasks/subsidies/guide_subsidies.tl:37

local instruction : MissionInterface.GenericTaskState.InstructionQueueEntry = {

base/content/mission/mission/tasks/guide/guide_collect_entity.tl:82

local instruction : MissionInterface.GenericTaskState.InstructionQueueEntry = {

base/content/mission/mission/tasks/guide/guide.tl:15

local instruction : MissionInterface.GenericTaskState.InstructionQueueEntry = {

mods/release/urbangames_campaign_mission_05/content/mission/mission/tasks/drilling/drilling.tl:209

local instruction : MissionInterface.GenericTaskState.InstructionQueueEntry = {

Fields

Name	Type	Description
`instructionKey`	`string`	Key passed to `TaskInfo.makeInstructionData` to get the instruction.
`param`	`any`	Extra argument passed to `TaskInfo.makeInstructionData`.
`state`	`InstructionState`	Playback state, updated from the GUI by the `updateDialogueState` event.

MissionInterface.GenericTaskState.InstructionQueueEntry.InstructionState¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:161

enum InstructionState

Notes

Playback state of an instruction.

Used in the base game: 6 times in 2 files

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

local function isLaterInstructionState(target : MissionInterface.GenericTaskState.InstructionQueueEntry.InstructionState, than : MissionInterface.GenericTaskSta

base/content/mission/mission/mission_react_util.tl:85

local state : MissionInterface.GenericTaskState.InstructionQueueEntry.InstructionState = "Playing"

Value	Description
`"Pending"`	Not started yet.
`"Playing"`	Playing.
`"Complete"`	Finished.

MissionInterface.GenericTaskState.GuideQueueEntry¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:177

record GuideQueueEntry

Notes

A spawnGuide event waiting for the task's instruction to start.

Used in the base game: 1 time in 1 file

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

local guideQueue : {MissionInterface.GenericTaskState.GuideQueueEntry} = {}

Fields

Name	Type	Description
`guideKey`	`string`	Name of the script event to send.
`state`	`GuideState`	Whether the event was sent.

MissionInterface.GenericTaskState.GuideQueueEntry.GuideState¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:178

enum GuideState

Notes

Whether the guide event was sent.

Value	Description
`"Pending"`	Not sent yet.
`"Triggered"`	Sent.

MissionInterface.TaskState¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:191

record TaskState<TaskSpecificState, TaskSpecificParams>

Notes

Saved state of one task, with its script-specific state and the framework state.

Used in the base game: 319 times in 25 files

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

local function commitCtx<TaskSpecificState, TaskSpecificParams>(data : MissionInterface.TaskState<TaskSpecificState, TaskSpecificParams>, ctx : MissionInterface

base/content/mission/mission/mission_boot_util.tl:58

local getTaskState = function(key : string) : MissionInterface.TaskState<any, any>

base/content/mission/mission/mission_framework/mission_framework_util.tl:24

function mission_framework_util.makeTaskContext<TaskSpecificState, TaskSpecificParams>(data : MissionInterface.TaskState<TaskSpecificState, TaskSpecificParams>,

base/content/mission/mission/mission_framework/mission_framework_react.tl:22

state : MissionInterface.TaskState<any, any>

base/content/mission/mission/tutorial/tutorial_story.tl:226

condition = function(_ctx : MissionInterface.TaskContext<any, any>, getTaskState : function(string) : MissionInterface.TaskState<any, any>) : boolean

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:46

local storeAny = task as MissionInterface.TaskState<MissionTaskStoreAny.State, MissionTaskStoreAny.Params>

… and 19 more files.

Fields

Name	Type	Description
`type`	`string`
`specific`	`TaskSpecificState`	genericParams : GenericTaskParams params : TaskSpecificParams Script-specific state, as returned by `TaskScript.onSpawn`.
`genericState`	`GenericTaskState`	Framework-managed state.

MissionInterface.MissionState¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:199

record MissionState

Notes

Saved state of the mission game script (::mission/mission.gs).

Used in the base game: 55 times in 11 files

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

local function initStateIfEmpty(missionState : MissionInterface.MissionState) : MissionInterface.MissionState

base/content/mission/mission/notification.script.tl:9

local makeState = function() : MissionInterface.MissionState

base/content/mission/mission/mission_framework/mission_framework_util.tl:53

local gameScript : Engine.Component.GameScript<MissionInterface.MissionState> = api.engine.getComponent(scriptEntity, api.type.ComponentType.GAME_SCRIPT)

base/content/mission/mission/mission_framework/mission_legacy_util.tl:8

mission_legacy_util.updateLegacyState = function(missionState : MissionInterface.MissionState)

base/content/mission/mission/mission_framework/mission_framework_react.tl:50

local gameScript : Engine.Component.GameScript<MissionInterface.MissionState> = api.engine.getComponent(scriptEntity, api.type.ComponentType.GAME_SCRIPT)

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:41

local gameScript : Engine.Component.GameScript<MissionInterface.MissionState> = api.engine.getComponent(scriptEntity, api.type.ComponentType.GAME_SCRIPT)

… and 5 more files.

Fields

Name	Type	Description
`tasks`	`{TaskState<any, any>}`	All tasks added so far, open and complete.
`nextUid`	`integer`	Counter used for the next task `uid`.
`version`	`integer`	Layout version of this state (see `MissionLegacyUtil`).
`bootTypes`	`{string : boolean}`	Bootstrap functions (`bootstrapScriptFn`) that already ran.
`nonBulldozableEntities`	`{Engine.Entity : boolean}`	Entities currently made non-bulldozable by open tasks.
`notificationFilter`	`{string : boolean}`	Notification types currently hidden by open tasks.
`needPauseNotifications`	`boolean`	Set on `initMission`; notifications are paused for one update.
`notificationsArePaused`	`boolean`	Notifications are currently paused by the mission.
`guiTimeSeconds`	`number`	Mission GUI clock in seconds, advanced by `dt / speedup` (wall-clock like, independent of game speed).
`isComplete`	`boolean`	Set when the mission was completed or aborted; the state is then cleared.
`lastCompletedTime`	`number`	GUI time (seconds) at which the last task completed.
`isTutorialActive`	`boolean`	The tutorial was started (`initNewGame` / `initTutorial` with a `tutorial_boot` present).

MissionInterface.MissionTaskApi¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:214

record MissionTaskApi

Notes

API passed to engine-side task callbacks (onComplete, handleEvent) and to bootstrap functions.

Used in the base game: 47 times in 40 files

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

local function makeApi(missionState : MissionInterface.MissionState) : MissionInterface.MissionTaskApi

base/content/mission/mission/mission_boot_util.tl:5

local type SpawnFn = function(taskKey : string, ctx : MissionInterface.TaskContext<any, any>, missionApi : MissionInterface.MissionTaskApi)

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

onComplete = function(ctx : MissionInterface.TaskContext<DecoratorState<S, GS>, DecoratorParam<P, GP>>, missionTaskApi : MissionInterface.MissionTaskApi)

base/content/mission/mission/tasks/transport_cargo/transport_cargo.tl:55

onComplete = function(ctx : TaskContext<S, P>, _missionTaskApi : MissionInterface.MissionTaskApi)

base/content/mission/mission/tasks/transport_cargo/transport_passengers.tl:28

onComplete = function(ctx : TaskContext<S, P>, _missionTaskApi : MissionInterface.MissionTaskApi)

base/content/mission/mission/tasks/transport_cargo/transport_cargo_faster.tl:95

onComplete = function(ctx : TaskContext<S, P>, _missionTaskApi : MissionInterface.MissionTaskApi)

… and 34 more files.

Functions

addTask(taskConfig : TaskConfig) base/tealdef/mission/mission_framework/mission_interface.d.tl:215

Notes

Spawns a task. Calls the script's onSpawn (a nil result prevents spawning) and then onStart.

Parameter	Type	Description
`taskConfig`	`TaskConfig`	Identification of the task to add.

sendTaskEvent(eventName : string, params : any) base/tealdef/mission/mission_framework/mission_interface.d.tl:216

Notes

Sends a script event to the calling task itself (id = the task's uid); it arrives in its handleEvent.

Parameter	Type	Description
`eventName`	`string`	Event name.
`params`	`any`	Event parameter.

getTaskState(uniqueTaskKey : string) : TaskState<any, any> base/tealdef/mission/mission_framework/mission_interface.d.tl:217

Notes

Looks up a task by its unique key.

Parameter	Type	Description
`uniqueTaskKey`	`string`	Key from `MissionTaskUtil.makeTaskKey`.

Returns TaskState<any, any>: The task's state, or nil if it was not added (yet).

MissionInterface.MissionTaskReadOnlyApi¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:220

record MissionTaskReadOnlyApi

Notes

Read-only API passed to TaskScript.onUpdate.

Used in the base game: 139 times in 57 files

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

local readOnlyApi : MissionInterface.MissionTaskReadOnlyApi = {

base/content/mission/mission/tutorial/tutorial_story.tl:199

storeFn = function(_readOnlyApi : MissionInterface.MissionTaskReadOnlyApi) : any

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:511

getMinCount = function(_readOnlyApi : MissionInterface.MissionTaskReadOnlyApi) : integer

base/content/mission/mission/tutorial/tutorial_story_branch_a.tl:413

getMinCount = function(_readOnlyApi : MissionInterface.MissionTaskReadOnlyApi) : integer

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

onUpdate = function(ctx : MissionInterface.TaskContext<DecoratorState<S, GS>, DecoratorParam<P, GP>>, readOnlyApi : MissionInterface.MissionTaskReadOnlyApi)

base/content/mission/mission/tasks/transport_cargo/transport_cargo.tl:62

onUpdate = function(ctx : TaskContext<S, P>, readOnlyApi : MissionInterface.MissionTaskReadOnlyApi)

… and 51 more files.

Functions

getTaskState(uniqueTaskKey : string) : TaskState<any, any> base/tealdef/mission/mission_framework/mission_interface.d.tl:221

Notes

Looks up a task by its unique key.

Parameter	Type	Description
`uniqueTaskKey`	`string`	Key from `MissionTaskUtil.makeTaskKey`.

Returns TaskState<any, any>: The task's state, or nil.

getLastCompletedTime() : number base/tealdef/mission/mission_framework/mission_interface.d.tl:222

Notes

Returns when the last task completed.

Returns number: GUI time in seconds (MissionState.lastCompletedTime).

hasPendingGuide() : boolean base/tealdef/mission/mission_framework/mission_interface.d.tl:223

Notes

Tells whether an open guide task has been triggered and is waiting to be shown or dismissed.

Returns boolean: true if a triggered guide is open.

MissionInterface.DeferredTaskApi¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:226

record DeferredTaskApi

Notes

API passed to GUI-side task callbacks; changes go through commands to the engine side.

Used in the base game: 41 times in 31 files

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

local function makeDeferredApi<TaskSpecificState, TaskSpecificParams>(task : MissionInterface.TaskState<TaskSpecificState, TaskSpecificParams>, missionState : M

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

missionTaskApi : MissionInterface.DeferredTaskApi

base/content/mission/mission/tasks/click_entity/click_entity.tl:70

guiHandleEvent = function(_src : string, id : string, name : string, param : any, ctx : TaskContext<S, P>, missionTaskApi : MissionInterface.DeferredTaskApi) :

base/content/mission/mission/tasks/buy_vehicle/buy_vehicle.tl:59

guiHandleEvent = function(_src : string, id : string, name : string, eventParam : any, ctx : TaskContext<S, P>, taskApi : MissionInterface.DeferredTaskApi) : an

base/content/mission/mission/tasks/buy_vehicle/clone_vehicle.tl:35

guiHandleEvent = function(_src : string, id : string, name : string, eventParam : any, ctx : TaskContext<S, P>, taskApi : MissionInterface.DeferredTaskApi) : an

base/content/mission/mission/tasks/finish/finish.tl:46

onGuiKickOff = function(_ctx : TaskContext<S, P>, taskApi : MissionInterface.DeferredTaskApi) : boolean

… and 25 more files.

Functions

sendTaskEvent(eventName : string, params : any) base/tealdef/mission/mission_framework/mission_interface.d.tl:227

Notes

Sends a script event to the calling task (id = its uid) via a command; it arrives in its engine-side handleEvent.

Parameter	Type	Description
`eventName`	`string`	Event name.
`params`	`any`	Event parameter.

getTaskState(uniqueTaskKey : string) : TaskState<any, any> base/tealdef/mission/mission_framework/mission_interface.d.tl:228

Notes

Looks up a task by its unique key.

Parameter	Type	Description
`uniqueTaskKey`	`string`	Key from `MissionTaskUtil.makeTaskKey`.

Returns TaskState<any, any>: The task's state, or nil.

MissionInterface.TaskDesc¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:231

record TaskDesc

No description in the game files yet.

Fields

Name	Type	Description
`scriptFile`	`string`

MissionInterface.PosRadius¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:235

record PosRadius

Notes

Circular area with a centre {x, y} (or {x, y, z}) and a radius in metres.

Used in the base game: 97 times in 17 files

base/content/mission/mission/mission_task_util.tl:24

function mission_task_util.locationButDistance(entity : Engine.Entity, distance : number) : MissionInterface.PosRadius

base/content/mission/mission/mission_outline.tl:5

function mission_outline.boundingCircle(positions: { { number, number, number } }, extension: number) : MissionInterface.PosRadius

base/content/mission/mission/mission_framework/mission_framework_util_line.tl:4

function mission_framework_util_line.getAllLinesBetweenStations(from : MissionInterface.PosRadius, to : MissionInterface.PosRadius) : {Engine.Entity}

base/content/mission/mission/mission_framework/mission_framework_react.tl:114

local boundingSpheres : {MissionInterface.PosRadius} = {}

base/content/mission/mission/tutorial/tutorial_story.tl:745

getAreas = function() : {MissionInterface.PosRadius}

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:152

getZonesToConnect = function() : {{MissionInterface.PosRadius, MissionInterface.PosRadius}}

… and 11 more files.

Fields

Name	Type	Description
`pos`	`{number}`	Centre position in world coordinates.
`radius`	`number`	Radius in metres.

MissionInterface.Marker¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:240

record Marker

Notes

Marker placed in the 3D world by a task (api.gui.mission.setMarkerAtEntity / setMarkerAtPosition).

Used in the base game: 32 times in 14 files

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

local scriptGetMarkers = taskScript.getMarkers as function(MissionInterface.TaskContext<any, any>) : {MissionInterface.Marker}

base/content/mission/mission/tutorial/tutorial_story.tl:103

local makeRailDepotMarkers = function() : {MissionInterface.Marker}

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:456

getMarkers = function() : {MissionInterface.Marker}

base/content/mission/mission/tutorial/tutorial_story_branch_a.tl:358

getMarkers = function() : {MissionInterface.Marker}

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

getMarkers = function(ctx : MissionInterface.TaskContext<DecoratorState<S, GS>, DecoratorParam<P, GP>>) : {MissionInterface.Marker}

base/content/mission/mission/tasks/click_entity/click_entity.tl:102

getMarkers = function(ctx : TaskContext<S, P>) : { MissionInterface.Marker }

… and 8 more files.

Fields

Name	Type	Description
`key`	`string`	Unique key of the marker; it is removed when no open task returns it any more.
`position`	`{number, number, number}`	World position, used when `entity` is not set.
`entity`	`Engine.Entity`	Entity to attach the marker to.
`type`	`string`	Marker type (e.g. `"arrow"`).
`scaling`	`number`	Size factor of the marker.
`isSelectable`	`boolean`	The marker can be clicked.
`fireSelectEntity`	`boolean`	Clicking the marker fires a select-entity event.

MissionInterface.Zone¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:250

record Zone

Notes

Area drawn on the terrain by a task, as a polygon or a circle (api.gui.mission.setZone / setZoneCircle).

Used in the base game: 35 times in 18 files

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

local scriptGetZones = taskScript.getZones as function(MissionInterface.TaskContext<any, any>) : {MissionInterface.Zone}

base/content/mission/mission/tutorial/tutorial_story.tl:622

getZones = function() : {MissionInterface.Zone}

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

getZones = function(ctx : MissionInterface.TaskContext<DecoratorState<S, GS>, DecoratorParam<P, GP>>) : {MissionInterface.Zone}

base/content/mission/mission/tasks/create_line/create_line.tl:91

getZones = function(ctx : TaskContext<S, P>) : {MissionInterface.Zone}

base/content/mission/mission/tasks/wait/wait_for.tl:63

getZones = function(ctx : MissionInterface.TaskContext<S, P>) : {MissionInterface.Zone}

base/content/mission/mission/tasks/utility/highlight.tl:20

getZones = function(ctx : TaskContext<nil, P>) : { MissionInterface.Zone }

… and 12 more files.

Fields

Name	Type	Description
`key`	`string`	Unique key of the zone; it is removed when no open task returns it any more.
`polygon`	`PolygonUtil.Polygon`	Polygon outline; takes precedence over `circle`.
`circle`	`MissionInterface.PosRadius`	Circular outline.
`draw`	`boolean`	Draws the zone.
`playAnimation`	`boolean`	Animates the zone outline.
`prohibitBuilding`	`boolean`	Forbids building inside the zone.
`zOffset`	`number`	Vertical offset of the drawn zone.

Functions

getDrawColor() : Vec4f base/tealdef/mission/mission_framework/mission_interface.d.tl:255

Notes

Returns the zone colour, typically a colour from MissionColors.

Returns Vec4f

MissionInterface.GuideInfo¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:261

record GuideInfo

Notes

Hint shown by the guide system for a guide task.

Used in the base game: 3 times in 2 files

base/content/mission/mission/mission_boot_util.tl:144

vtable.getGuideInfo = function(_ctx : MissionInterface.TaskContext<any, any>) : MissionInterface.GuideInfo

base/content/mission/mission/guide_system/guide_system_react.tl:11

info : MissionInterface.GuideInfo

Fields

Name	Type	Description
`name`	`string`	Title of the hint.
`text`	`string`	Hint text.
`textGamepad`	`string`	Hint text used in gamepad input mode.
`image`	`string`	Image shown in the hint.
`imageGamepad`	`string`	Image used in gamepad input mode.
`caption`	`string`	Caption passed to the guide spawn call.
`targets`	`{Target}`	GUI elements the hint points at.
`free`	`boolean`	Shows the hint at a free screen position instead of at a target.
`freePosition`	`FreePosition`	Screen position of a free hint.

MissionInterface.GuideInfo.Position¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:262

enum Position

Notes

Side of the target GUI element where the hint appears.

Used in the base game: 1 time in 1 file

base/content/mission/mission/guide_system/guide_system_react.tl:186

local PositionTable<total> : {MissionInterface.GuideInfo.Position : api.gui.guide.GuidePosition} = {

Value	Description
`"Above"`	Above the target.
`"Below"`	Below the target.
`"Right"`	Right of the target.
`"Left"`	Left of the target.

MissionInterface.GuideInfo.FreePosition¶

enum base/tealdef/mission/mission_framework/mission_interface.d.tl:269

enum FreePosition

Notes

Screen position of a free (untargeted) hint.

Used in the base game: 1 time in 1 file

base/content/mission/mission/guide_system/guide_system_react.tl:193

local FreePositionTable<total> : {MissionInterface.GuideInfo.FreePosition : api.gui.guide.FreeGuidePosition} = {

Value	Description
`"High"`	Upper position.
`"Low"`	Lower position (default).

MissionInterface.GuideInfo.Target¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:274

record Target

Notes

GUI element the hint points at.

Fields

Name	Type	Description
`idOrTag`	`string`	Id or tag of the GUI element (e.g. `"menu.construction.road"`).
`position`	`Position`	Side of the element where the hint appears.

MissionInterface.TaskInfo¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:290

record TaskInfo

Notes

What the mission window shows for a task (name, paragraphs, option buttons, progress, links, instruction voice-over).

Details

A task without a name (and without options or showTaskInGuiWithoutName) is not listed in the mission window. Paragraph texts may contain links to keys of links; clicking one moves the camera there.

Example

-- from urbangames_campaign_mission_01 mission_story.tl
taskInfo = {
    name = _("MISSION_01_TASK_BULLDOZE_NAME"),
    paragraphs = {
        { text = _("MISSION_01_TASK_BULLDOZE_PARAGRAPH") },
        { text = _("MISSION_01_TASK_BULLDOZE_HINT") },
    },
    links = { pos_street = { location = mission_task_util.mergeAreas({params.connectStreets_1_1_zone, params.connectStreets_1_2_zone }, 20) } },
    instructionData = {
        subtitle = _("MISSION_01_TASK_BULLDOZE_INSTRUCTION"),
        portrait = "urbangames_campaign_mission_01::/mission/dialogue/andrew_neutral.tga",
        voiceOver = "urbangames_campaign_mission_01::/audio/voice_over/MISSION_01_TASK_BULLDOZE_INSTRUCTION.wav",
        duration = 6,
    },
    progress = { text = _("Trees Removed") },
},

Used in the base game: 24 times in 20 files

base/content/mission/mission/mission_boot_util.tl:115

vtable.getTaskInfo = function(ctx : MissionInterface.TaskContext<any, any>) : MissionInterface.TaskInfo

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

local info = vtable.getTaskInfo(mission_framework_util.makeTaskContext(v)) as MissionInterface.TaskInfo

base/content/mission/mission/mission_task_util.tl:88

function mission_task_util.getTaskInfo(taskKey : string, ctx : MissionInterface.TaskContext<any, any>, getTaskData : function(string) : MissionTaskUtil.StaticTa

base/content/mission/mission/mission_framework/mission_framework_react_util.tl:232

function mission_framework_react_util.handleLinkClick(taskInfo : MissionInterface.TaskInfo, target : string)

base/content/mission/mission/mission_framework/mission_framework_react.tl:24

info : MissionInterface.TaskInfo

base/content/mission/mission/tutorial/tutorial_story.tl:49

local getDebugTaskInfo = function() : MissionInterface.TaskInfo

… and 14 more files.

Fields

Name	Type	Description
`links`	`{string : LinkDef}`	Link key -> camera target. Keys are referenced from paragraph texts; the locate button frames all of them.
`name`	`string`	Task title. Tasks without a name are hidden from the mission window.
`paragraphs`	`{Paragraph}`	Task description; the first paragraph is shown next to the instruction button. Later paragraphs are hints (wiki).
`options`	`{Option}`	Option buttons.
`camera`	`{LinkDef}`	Camera targets used by the locate button instead of `links`.
`progress`	`TaskProgressData`	Static progress fields (e.g. `text`, `cargoTypeRes`) merged with the runtime progress.
`subTasks`	`{SubTaskInfo}`	Sub-tasks with their own progress.
`instructionData`	`MissionDialogueData.InstructionData`	Voice-over instruction of the task (portrait, subtitle, sound file, duration).
`showTaskInGuiWithoutName`	`boolean`	Lists the task in the mission window even without a name.

Functions

makeInstructionData(instructionKey : string, param? : any) : MissionDialogueData.InstructionData base/tealdef/mission/mission_framework/mission_interface.d.tl:329

Notes

Returns the instruction for a key queued in GenericTaskState.instructionsQueue.

Parameter	Type	Description
`instructionKey`	`string`	Key of the queued instruction.
`param?`	`any`	Extra parameter of the queue entry.

Returns MissionDialogueData.InstructionData: Instruction to play.

MissionInterface.TaskInfo.NotificationInput¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:291

record NotificationInput

Notes

Params of the mission notification (::/mission/notification.script) sent when a task completes.

Used in the base game: 4 times in 2 files

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

local notificationParams : MissionInterface.TaskInfo.NotificationInput = { missionTaskKey = v.genericState.config.uniqueKey }

base/content/mission/mission/notification.script.tl:6

local data : NotificationType<MissionInterface.TaskInfo.NotificationInput> = {}

Fields

Name	Type	Description
`missionTaskKey`	`string`	Unique key of the completed task.
`financialReward`	`integer`	Reward paid, in game currency, if any.

MissionInterface.TaskInfo.Paragraph¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:296

record Paragraph

Notes

One paragraph of the task description.

Used in the base game: 1 time in 1 file

base/content/mission/mission/mission_framework/mission_framework_react_util.tl:244

local newParagraphs : {MissionInterface.TaskInfo.Paragraph} = {}

Fields

Name	Type	Description
`text`	`string`	Paragraph text, used for all input modes.
`textMouse`	`string`	Text used with mouse input when `text` is not set.
`textGamepad`	`string`	Text used with gamepad input when `text` is not set.

MissionInterface.TaskInfo.Option¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:301

record Option

Notes

Button in the task details; clicking it sends a Decision event with key.

Used in the base game: 19 times in 19 files

base/content/mission/mission/tutorial/tutorial_story.tl:46

local getDebugOptions = function() : { MissionInterface.TaskInfo.Option }

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:31

local getDebugOptions = function() : { MissionInterface.TaskInfo.Option }

base/content/mission/mission/tutorial/tutorial_story_branch_a.tl:31

local getDebugOptions = function() : { MissionInterface.TaskInfo.Option }

mods/release/urbangames_campaign_mission_03/content/mission/mission/mission_story_cutscenes_only.tl:36

local getDebugOptions = function() : { MissionInterface.TaskInfo.Option }

mods/release/urbangames_campaign_mission_03/content/mission/mission/mission_story.tl:44

local getDebugOptions = function() : { MissionInterface.TaskInfo.Option }

mods/release/urbangames_campaign_mission_07/content/mission/mission/mission_story_cutscenes_only.tl:32

local getDebugOptions = function() : { MissionInterface.TaskInfo.Option }

… and 13 more files.

Fields

Name	Type	Description
`text`	`string`	Button label.
`key`	`any`	Value stored as `GenericTaskState.optionDecision`; `"finish"` (or a string starting with `finish`) completes the task.

MissionInterface.TaskInfo.LinkDef¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:305

record LinkDef

Notes

Camera target of a link. It is an entity or an area, given directly or by a function.

Used in the base game: 7 times in 2 files

base/content/mission/mission/mission_framework/mission_framework_react_util.tl:222

function mission_framework_react_util.followLink(link : MissionInterface.TaskInfo.LinkDef)

base/content/mission/mission/mission_framework/mission_framework_react.tl:113

local createLocateLink = function(links : {MissionInterface.TaskInfo.LinkDef}) : MissionInterface.TaskInfo.LinkDef

Fields

Name	Type	Description
`entity`	`Engine.Entity`	Entity the camera focuses on.
`location`	`PosRadius`	Area the camera moves to.

Functions

getEntity() : Engine.Entity base/tealdef/mission/mission_framework/mission_interface.d.tl:308

Notes

Returns the entity at click time; takes precedence over entity.

Returns Engine.Entity

getLocation() : MissionInterface.PosRadius base/tealdef/mission/mission_framework/mission_interface.d.tl:309

Notes

Returns the area at click time; takes precedence over location.

Returns MissionInterface.PosRadius

MissionInterface.TaskInfo.SubTaskInfo¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:313

record SubTaskInfo

Notes

A sub-task listed under the task with its own progress.

Fields

Name	Type	Description
`name`	`string`	Sub-task label.
`description`	`string`	Sub-task description.
`progress`	`TaskProgressData`	Sub-task progress (filled from `GenericTaskState.subTasksProgress`).

MissionInterface.ProposalHandlerResult¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:333

record ProposalHandlerResult

Notes

Answer of a task to a build proposal (TaskScript.guiHandleProposal).

Used in the base game: 77 times in 7 files

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

local proposalHandlers : {{MissionInterface.TaskState<any, any>, function(id : string, name : string, param : ProposalEventData, isApply : boolean, state : Miss

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

) : MissionInterface.ProposalHandlerResult

base/content/mission/mission/tasks/bulldoze/bulldoze.tl:85

guiHandleProposal = function(id : string, _name : string, proposalEventData : ProposalEventData, isApply : boolean, ctx : TaskContext<S, P>, missionTaskApi : Mi

base/content/mission/mission/tasks/connect_nodes/connect_nodes.tl:56

guiHandleProposal = function(id : string, _name : string, proposalEventData : ProposalEventData, isApply : boolean, ctx : TaskContext<S, P>, taskApi : MissionIn

base/content/mission/mission/tasks/build_construction/mission_task_build_construction_util.tl:9

isWhitelist : boolean) : MissionInterface.ProposalHandlerResult

base/content/mission/mission/tasks/build_construction/build_construction.tl:29

taskApi : MissionInterface.DeferredTaskApi) : MissionInterface.ProposalHandlerResult

… and 1 more files.

Fields

Name	Type	Description
`error`	`string`	Error message; blocks the proposal.
`warning`	`string`	Warning message; the proposal stays possible.
`priority`	`number`	When several tasks answer, the message with the highest priority is shown.
`isWhitelist`	`boolean`	A whitelist result without message lets the proposal pass this handler.

MissionInterface.TaskContext¶

record base/tealdef/mission/mission_framework/mission_interface.d.tl:340

record TaskContext<TaskSpecificState, TaskSepcificParams>

Notes

Everything a task callback gets about its task.

Used in the base game: 567 times in 113 files

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

local function commitCtx<TaskSpecificState, TaskSpecificParams>(data : MissionInterface.TaskState<TaskSpecificState, TaskSpecificParams>, ctx : MissionInterface

base/content/mission/mission/mission_boot_util.tl:5

local type SpawnFn = function(taskKey : string, ctx : MissionInterface.TaskContext<any, any>, missionApi : MissionInterface.MissionTaskApi)

base/content/mission/mission/mission_task_util.tl:88

function mission_task_util.getTaskInfo(taskKey : string, ctx : MissionInterface.TaskContext<any, any>, getTaskData : function(string) : MissionTaskUtil.StaticTa

base/content/mission/mission/mission_framework/mission_framework_util.tl:24

function mission_framework_util.makeTaskContext<TaskSpecificState, TaskSpecificParams>(data : MissionInterface.TaskState<TaskSpecificState, TaskSpecificParams>,

base/content/mission/mission/tutorial/tutorial_story.tl:226

condition = function(_ctx : MissionInterface.TaskContext<any, any>, getTaskState : function(string) : MissionInterface.TaskState<any, any>) : boolean

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:607

condition = function(_ctx : MissionInterface.TaskContext<any, any>, getTaskState : function(string) : MissionInterface.TaskState<any, any>) : boolean

… and 107 more files.

Fields

Name	Type	Description
`state`	`TaskSpecificState`	Script-specific state; may be modified in place (or replaced, the framework commits it).
`genericState`	`GenericTaskState`	Framework-managed state.
`params`	`TaskSepcificParams`	Task-specific params from the story (read-only).
`guiTimeSeconds`	`number`	Current mission GUI time in seconds.

MissionInterface.TaskScript¶

interface base/tealdef/mission/mission_framework/mission_interface.d.tl:347

interface TaskScript<TaskSpecificState, TaskParams>

Notes

Implementation of a task type. All callbacks are optional; the built-in task types under mission/tasks/** implement this interface.

Details

Engine side (state can be changed): onSpawn, onStart, onUpdate, isComplete, onComplete, handleEvent. GUI side (state is read-only; use DeferredTaskApi.sendTaskEvent to change it): guiUpdate, guiHandleEvent, guiHandleProposal, onGuiKickOff, getMarkers, getZones, getProtectedEntities, getSelectorEntityFilter, getVisibilityRules, getEnableRules, getHighlightRules. getNonBulldozableEntities runs on the engine side for open tasks.

Example

-- base game: mission/tasks/wait/wait.tl (simplified)
local ret : MissionTaskWait = {
    taskScriptName = "wait",
    onSpawn = function(params : MissionTaskWait.Params, guiTimeSeconds : number) : MissionTaskWait.State
        return { endGuiTimeSeconds = params.guiTimeSeconds and guiTimeSeconds + params.guiTimeSeconds }
    end,
    isComplete = function(ctx : MissionInterface.TaskContext<MissionTaskWait.State, MissionTaskWait.Params>) : boolean
        return ctx.guiTimeSeconds >= ctx.state.endGuiTimeSeconds
    end,
}
return ret

Used in the base game: 1122 times in 38 files

base/content/mission/mission/mission_boot_util.tl:98

vtable.getTaskScript = function() : MissionInterface.TaskScript<any, any>

base/content/mission/mission/tutorial/tutorial_story.tl:18

local camera_movement = ug_require "::/mission/tutorial/tasks/camera_movement.tl" as MissionInterface.TaskScript<nil, any>

base/content/mission/mission/tutorial/tutorial_story_branch_b.tl:150

taskScript = build_path as MissionInterface.TaskScript<any, any>,

base/content/mission/mission/tutorial/tutorial_story_branch_a.tl:150

taskScript = build_path as MissionInterface.TaskScript<any, any>,

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

task : MissionInterface.TaskScript<S, P>,

base/content/mission/mission/tasks/subsidies/guide_subsidies.tl:3

local ret : MissionInterface.TaskScript<DecoratorState<MissionTaskSubsidies.State, MissionTaskGuideSubsidies.State>, DecoratorParam<MissionTaskSubsidies.Params,

… and 32 more files.

Fields

Name	Type	Description
`taskScriptName`	`string`	Type name of the task; prefix of task `uid`s. The name `"finish"` marks the mission-end task.
`disableGuideSystem`	`boolean`	Marks the task type as one during which the guide system stays inactive (set by the cutscene and dialogue scripts).

Functions

handleLegacy(ctx : TaskContext<TaskSpecificState, TaskParams>, oldVersion : integer) : TaskContext<TaskSpecificState, TaskParams> base/tealdef/mission/mission_framework/mission_interface.d.tl:352

apply legacy handling for the task (use return value in case state is not a table and thus cannot be updated inplace)

Notes

Upgrades the task's saved state from an older mission-state version.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context with the old state.
`oldVersion`	`integer`	Version of the saved mission state.

Returns TaskContext<TaskSpecificState, TaskParams>: A replacement context, or nil if the state was updated in place.

onSpawn(TaskParams, guiTimeSeconds : number) : TaskSpecificState | nil base/tealdef/mission/mission_framework/mission_interface.d.tl:355

prepare the initial state when attempting to spawn (return nil to prevent spawning)

Notes

Creates the initial script-specific state when the task is added.

Parameter	Type	Description
`#1`	`TaskParams`	Task params from the story.
`guiTimeSeconds`	`number`	Current mission GUI time in seconds.

Returns TaskSpecificState | nil: Initial state (an empty table is used when the callback is missing).

onStart(state : TaskContext<TaskSpecificState, TaskParams>) base/tealdef/mission/mission_framework/mission_interface.d.tl:356

Notes

Called once right after the task was added.

Parameter	Type	Description
`state`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the new task.

getInfo(state : TaskContext<TaskSpecificState, TaskParams>) : TaskInfo base/tealdef/mission/mission_framework/mission_interface.d.tl:358

Notes

Returns task info computed by the script. A task built with TaskDecorator.decorate uses the wrapped task's getInfo and ignores the decorator's.

Parameter	Type	Description
`state`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns TaskInfo: Task info.

isComplete(state : TaskContext<TaskSpecificState, TaskParams>) : boolean base/tealdef/mission/mission_framework/mission_interface.d.tl:360

Notes

Checked every update for open tasks; returning true completes the task (unless requiredTaskToComplete is still open).

Parameter	Type	Description
`state`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns boolean: true when the task is done.

onComplete(state : TaskContext<TaskSpecificState, TaskParams>, missionTaskApi : MissionTaskApi) base/tealdef/mission/mission_framework/mission_interface.d.tl:361

Notes

Called once when the task completes, before its follow-up tasks are added.

Parameter	Type	Description
`state`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.
`missionTaskApi`	`MissionTaskApi`	API to add tasks or look up other tasks.

onUpdate(ctx : TaskContext<TaskSpecificState, TaskParams>, readOnlyApi : MissionTaskReadOnlyApi) base/tealdef/mission/mission_framework/mission_interface.d.tl:363

Notes

Called every engine update while the task is open.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task; state changes are saved.
`readOnlyApi`	`MissionTaskReadOnlyApi`	Read-only API to look up other tasks.

handleEvent(src : string, id : string, name : string, param : any, ctx : TaskContext<TaskSpecificState, TaskParams>, missionTaskApi : MissionTaskApi) : any base/tealdef/mission/mission_framework/mission_interface.d.tl:364

Notes

Receives every script event on the engine side while the task is open. Events sent to the task itself have id equal to its uid.

Parameter	Type	Description
`src`	`string`	Event source.
`id`	`string`	Event id (target).
`name`	`string`	Event name.
`param`	`any`	Event parameter.
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task; state changes are saved.
`missionTaskApi`	`MissionTaskApi`	API to add tasks, send events to itself or look up tasks.

Returns any: Optional result of the event.

guiHandleEvent(src : string, id : string, name : string, param : any, ctx : TaskContext<TaskSpecificState, TaskParams>, taskApi : DeferredTaskApi) : any base/tealdef/mission/mission_framework/mission_interface.d.tl:365

Notes

Receives GUI events while the task is open.

Parameter	Type	Description
`src`	`string`	Event source.
`id`	`string`	Event id.
`name`	`string`	Event name.
`param`	`any`	Event parameter.
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task (read-only on this side).
`taskApi`	`DeferredTaskApi`	Deferred API to send events to the engine side.

Returns any: Optional result of the event.

guiUpdate(ctx : TaskContext<TaskSpecificState, TaskParams>, taskApi : DeferredTaskApi) base/tealdef/mission/mission_framework/mission_interface.d.tl:366

Notes

Called every GUI update while the task is open.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task (read-only on this side).
`taskApi`	`DeferredTaskApi`	Deferred API to send events to the engine side.

guiHandleProposal(id : string, name : string, param : ProposalEventData, isApply : boolean, ctx : TaskContext<TaskSpecificState, TaskParams>, taskApi : DeferredTaskApi) : ProposalHandlerResult base/tealdef/mission/mission_framework/mission_interface.d.tl:367

Notes

Checks a build proposal (builder.proposalCreate / builder.proposalApply) and can block it or warn.

Parameter	Type	Description
`id`	`string`	Event id.
`name`	`string`	Event name (`builder.proposalCreate` or `builder.proposalApply`).
`param`	`ProposalEventData`	Proposal, its data and, on apply, the resulting entities.
`isApply`	`boolean`	`true` for `builder.proposalApply`.
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.
`taskApi`	`DeferredTaskApi`	Deferred API to send events to the engine side.

Returns ProposalHandlerResult: Error or warning to show, or nil to accept.

onGuiKickOff(ctx : TaskContext<TaskSpecificState, TaskParams>, taskApi : DeferredTaskApi) : boolean base/tealdef/mission/mission_framework/mission_interface.d.tl:372

Opportunity to schedule UI things (i.e. cutscene/dialogue) on task "start", for which other tasks should wait. If you do so, return true to indicate no other onGuiKickOff shall be called in this frame. Exception: A new tasks's onGuiKickOff() can still be called if an already active task lists this inside its genericParams.allowSimultaneousUiTasks.

Notes

Lets the task start UI (cutscene, dialogue) when it opens; returning true stops other tasks from kicking off their UI in the same frame.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.
`taskApi`	`DeferredTaskApi`	Deferred API.

Returns boolean: true if the task started UI.

getMarkers(ctx : TaskContext<TaskSpecificState, TaskParams>) : {Marker} base/tealdef/mission/mission_framework/mission_interface.d.tl:374

Notes

Returns the world markers of the task.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {Marker}: Markers to show while the task is open.

getZones(ctx : TaskContext<TaskSpecificState, TaskParams>) : {Zone} base/tealdef/mission/mission_framework/mission_interface.d.tl:375

Notes

Returns the terrain zones of the task.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {Zone}: Zones to draw while the task is open.

getNonBulldozableEntities(ctx : TaskContext<TaskSpecificState, TaskParams>) : {Engine.Entity} base/tealdef/mission/mission_framework/mission_interface.d.tl:376

Notes

Returns entities that cannot be bulldozed while the task is open.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {Engine.Entity}: Entities (constructions are resolved from their parts).

getProtectedEntities(ctx : TaskContext<TaskSpecificState, TaskParams>) : {Engine.Entity : GameContext.Filters.ProtectionConfig | boolean} base/tealdef/mission/mission_framework/mission_interface.d.tl:377

Notes

Returns entities protected from player changes while the task is open.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {Engine.Entity : GameContext.Filters.ProtectionConfig | boolean}: Entity -> protection config, or true.

getSelectorEntityFilter(ctx : TaskContext<TaskSpecificState, TaskParams>) : {Engine.Entity : boolean} base/tealdef/mission/mission_framework/mission_interface.d.tl:378

Notes

Returns which entities may be selected while the task is open.

Parameter	Type	Description
`ctx`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {Engine.Entity : boolean}: Entity -> selectable flag.

getVisibilityRules(TaskContext<TaskSpecificState, TaskParams>) : {string : boolean} base/tealdef/mission/mission_framework/mission_interface.d.tl:380

Notes

Returns GUI visibility rules computed at runtime; merged over the static visibilityRules.

Parameter	Type	Description
`#1`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {string : boolean}: GUI class -> visible flag.

getEnableRules(TaskContext<TaskSpecificState, TaskParams>) : {string : boolean} base/tealdef/mission/mission_framework/mission_interface.d.tl:381

Notes

Returns GUI enable rules computed at runtime; merged over the static enableRules.

Parameter	Type	Description
`#1`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {string : boolean}: GUI id/tag -> enabled flag.

getHighlightRules(TaskContext<TaskSpecificState, TaskParams>) : {string : MissionInterface.HighlightStyle} base/tealdef/mission/mission_framework/mission_interface.d.tl:382

Notes

Returns GUI highlight rules computed at runtime; merged over the static highlightRules.

Parameter	Type	Description
`#1`	`TaskContext<TaskSpecificState, TaskParams>`	Context of the task.

Returns {string : MissionInterface.HighlightStyle}: GUI id/tag -> highlight style.