mission_task_util¶

Source: base/tealdef/mission/mission_task_util.d.tl

Notes

Declarative task description (StaticTaskInfo) used by mission stories, plus helpers for task keys and areas.

Globals¶

Types

Name	Definition	Description
`MissionLocalization`	`{{Engine.Entity, string}}`	List of `{ entity, name }` pairs used to rename the entities of a mission savegame (see `NameUtil.setName`).

MissionTaskUtil¶

record global base/tealdef/mission/mission_task_util.d.tl:5

global record MissionTaskUtil

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

Notes

Declarative task description used by stories, plus helpers for task keys and areas.

Functions

makeTaskKey(taskKey : string, root : string) : string base/tealdef/mission/mission_task_util.d.tl:49

Call as mission_task_util.makeTaskKey

Notes

Builds the unique key of a task.

Parameter	Type	Description
`taskKey`	`string`	Task key local to the story.
`root`	`string`	Script key of the story (e.g. `"urbangames_campaign_mission_01::/mission/mission.script"`).

Returns string: root .. "||" .. taskKey.

Used in the base game: 254 times in 21 files

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

uniqueKey = mission_task_util.makeTaskKey(key, scriptKey)

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

local taskState = readOnlyApi.getTaskState(mission_task_util.makeTaskKey("road_depot", "::/mission/tutorial/tutorial.script"))

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

local key = mission_task_util.makeTaskKey("b_store_fishing_grounds", "::/mission/tutorial/tutorial.script")

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

local key = mission_task_util.makeTaskKey("a_store_oil_platform", "::/mission/tutorial/tutorial.script")

base/content/mission/mission/tutorial/tutorial_story_util.tl:20

local key = mission_task_util.makeTaskKey("store_capital", "::/mission/tutorial/tutorial.script")

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

taskParams = mission_task_util.makeTaskKey("missionEnd", "urbangames_campaign_mission_03::/mission/mission.script"),

… and 15 more files.

makeJoinParams(keys : {string}, root : string, showProgress? : boolean) : MissionTaskJoin.Params base/tealdef/mission/mission_task_util.d.tl:50

Call as mission_task_util.makeJoinParams

Notes

Builds the params of a join task that waits for several tasks of the same story.

Parameter	Type	Description
`keys`	`{string}`	Local task keys to wait for.
`root`	`string`	Script key of the story.
`showProgress?`	`boolean`	Shows progress of the join.

Returns MissionTaskJoin.Params: Params for MissionTaskJoin.

Used in the base game: 37 times in 19 files

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

taskParams = mission_task_util.makeJoinParams( { "road_stop_2_1", "road_stop_2_2" }, "::/mission/tutorial/tutorial.script", true),

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

taskParams = mission_task_util.makeJoinParams( { "b_line_industrial_1", "b_line_industrial_2" }, "::/mission/tutorial/tutorial.script", true),

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

taskParams = mission_task_util.makeJoinParams( { "a_line_commercial_assign_1", "a_line_commercial_assign_2" }, "::/mission/tutorial/tutorial.script", true),

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

taskParams = mission_task_util.makeJoinParams( { "excavation_dialogue" }, "urbangames_campaign_mission_03::/mission/mission.script"),

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

taskParams = mission_task_util.makeJoinParams( { "excavation_dialogue" }, "urbangames_campaign_mission_03::/mission/mission.script"),

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

taskParams = mission_task_util.makeJoinParams( { "missionEnd" }, "urbangames_campaign_mission_07::/mission/mission.script"),

… and 13 more files.

locationButDistance(entity : Engine.Entity, distance : number) : MissionInterface.PosRadius base/tealdef/mission/mission_task_util.d.tl:51

Call as mission_task_util.locationButDistance

Notes

Builds a circle around an entity's position.

Parameter	Type	Description
`entity`	`Engine.Entity`	Entity at the centre.
`distance`	`number`	Radius in metres.

Returns MissionInterface.PosRadius: 2D circle.

disallowAllVehicles(models : {any : string}) : {string : {integer, integer}} base/tealdef/mission/mission_task_util.d.tl:52

Call as mission_task_util.disallowAllVehicles

Notes

Maps every given model name to {0, nil}.

Parameter	Type	Description
`models`	`{any : string}`	Model names.

Returns {string : {integer, integer}}: Model name -> {0, nil}.

makeBoundingSphereFromEntity(entity : Engine.Entity) : MissionInterface.PosRadius base/tealdef/mission/mission_task_util.d.tl:54

Call as mission_task_util.makeBoundingSphereFromEntity

Notes

Builds a sphere around an entity's bounding box (for vehicles, around the first carriage).

Parameter	Type	Description
`entity`	`Engine.Entity`	Entity to enclose.

Returns MissionInterface.PosRadius: Sphere, or nil if the entity has no bounding volume.

Used in the base game: 1 time in 1 file

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

s = mission_task_util.makeBoundingSphereFromEntity(entity)

mergeBoundingVolumes(entities : {Engine.Entity}, radiusOffset? : number) : MissionInterface.PosRadius base/tealdef/mission/mission_task_util.d.tl:55

Call as mission_task_util.mergeBoundingVolumes

Notes

Builds a sphere that encloses the bounding boxes of several entities.

Parameter	Type	Description
`entities`	`{Engine.Entity}`	Entities to enclose; missing ones are skipped.
`radiusOffset?`	`number`	Extra radius in metres.

Returns MissionInterface.PosRadius: Sphere, or an empty table if no entity has a bounding volume.

Used in the base game: 5 times in 2 files

mods/release/urbangames_campaign_mission_02/content/mission/mission/mission_story.tl:1502

signals2_pos = { location = mission_task_util.mergeBoundingVolumes(getValidEdges(convertToSet(params.entityList_signalsPart1)), 80) },

mods/release/urbangames_campaign_mission_05/content/mission/mission/mission_story.tl:1425

oil_area = { location = mission_task_util.mergeBoundingVolumes(table_util.concatenate(params.entityList_red, params.entityList_yellow)) }

mergeAreas(areas : {MissionInterface.PosRadius}, radiusOffset? : number) : MissionInterface.PosRadius base/tealdef/mission/mission_task_util.d.tl:56

Call as mission_task_util.mergeAreas

Notes

Builds a sphere that encloses several areas.

Parameter	Type	Description
`areas`	`{MissionInterface.PosRadius}`	Areas to enclose.
`radiusOffset?`	`number`	Extra radius in metres.

Returns MissionInterface.PosRadius: Enclosing sphere, or nil for an empty list.

Used in the base game: 6 times in 3 files

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

result.location = mission_task_util.mergeAreas(boundingSpheres, 200.0)

mods/release/urbangames_campaign_mission_02/content/mission/mission/mission_story.tl:1074

entity_tunnel_loop = { location = mission_task_util.mergeAreas(table_util.concatenate(params.zonesToConnect1, params.zonesToConnect2), 40) },

mods/release/urbangames_campaign_mission_01/content/mission/mission/mission_story.tl:626

links = { pos_street = { location = mission_task_util.mergeAreas({params.connectStreets_1_1_zone, params.connectStreets_1_2_zone }, 20) } },

extractGenericParams(taskKey : string, getTaskData : function(string) : StaticTaskInfo) : MissionInterface.GenericTaskParams base/tealdef/mission/mission_task_util.d.tl:58

Call as mission_task_util.extractGenericParams

Notes

Converts a task's static description into its generic params (rule lists become maps).

Parameter	Type	Description
`taskKey`	`string`	Local task key.
`getTaskData`	`function(string) : StaticTaskInfo`	Task-data lookup of the story.

Returns MissionInterface.GenericTaskParams: Generic params, or nil for an unknown task.

Used in the base game: 1 time in 1 file

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

local insert = mission_task_util.extractGenericParams(taskKey, getTaskData)

getTaskInfo(taskKey : string, ctx : MissionInterface.TaskContext<any, any>, getTaskData : function(string) : StaticTaskInfo) : MissionInterface.TaskInfo base/tealdef/mission/mission_task_util.d.tl:59

Call as mission_task_util.getTaskInfo

Notes

Returns the static task info of a task, with runtime progress and sub-task progress copied in.

Parameter	Type	Description
`taskKey`	`string`	Local task key.
`ctx`	`MissionInterface.TaskContext<any, any>`	Context of the task.
`getTaskData`	`function(string) : StaticTaskInfo`	Task-data lookup of the story.

Returns MissionInterface.TaskInfo: Task info, or nil if the task has none.

Used in the base game: 1 time in 1 file

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

return mission_task_util.getTaskInfo(taskKey, ctx, getTaskData)

getNonBulldozableEntitiesFromParams(params : table) : {Engine.Entity} base/tealdef/mission/mission_task_util.d.tl:61

Call as mission_task_util.getNonBulldozableEntitiesFromParams

Notes

Collects entities from a mission params table by key prefix (entity_* values, entityList_* lists, entityMap_* map keys).

Parameter	Type	Description
`params`	`table`	Mission params table.

Returns {Engine.Entity}: Collected entities.

Used in the base game: 8 times in 8 files

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

nonBulldozableEntities = mission_task_util.getNonBulldozableEntitiesFromParams(params as table),

mods/release/urbangames_campaign_mission_07/content/mission/mission/mission_story.tl:78

nonBulldozableEntities = mission_task_util.getNonBulldozableEntitiesFromParams(params as table),

mods/release/urbangames_campaign_mission_02/content/mission/mission/mission_story.tl:264

nonBulldozableEntities = mission_task_util.getNonBulldozableEntitiesFromParams(params as table),

mods/release/urbangames_campaign_mission_06/content/mission/mission/mission_story.tl:456

nonBulldozableEntities = mission_task_util.getNonBulldozableEntitiesFromParams(params as table),

mods/release/urbangames_campaign_mission_01/content/mission/mission/mission_story.tl:129

local nonBulldozableEntities = mission_task_util.getNonBulldozableEntitiesFromParams(params as table)

mods/release/urbangames_campaign_mission_05/content/mission/mission/mission_story.tl:115

nonBulldozableEntities = mission_task_util.getNonBulldozableEntitiesFromParams(params as table),

… and 2 more files.

MissionTaskUtil.FollowupDef¶

record base/tealdef/mission/mission_task_util.d.tl:7

record FollowupDef

Notes

A task to add after another task completed (or at boot), optionally only when a condition holds.

Example

followup = {
    { taskKey = "find_alligators_end" },
    {
        taskKey = "task_alligators_medal",
        condition = function(ctx : MissionInterface.TaskContext<any, any>) : boolean
            return (ctx.guiTimeSeconds - ctx.genericState.guiSpawnTime) < 30
        end,
    },
},

Used in the base game: 2 times in 1 file

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

bootTasks : { MissionTaskUtil.FollowupDef },

Fields

Name	Type	Description
`taskKey`	`string`	Task key local to the story.

Functions

condition(MissionInterface.TaskContext<any, any>, function(string) : MissionInterface.TaskState<any, any>) base/tealdef/mission/mission_task_util.d.tl:9

Notes

Optional condition; the task is only added when it returns true.

Parameter	Type	Description
`#1`	`MissionInterface.TaskContext<any, any>`	Context of the completed task.
`#2`	`function(string) : MissionInterface.TaskState<any, any>`	Function that returns the state of another task by its local task key.

MissionTaskUtil.StaticTaskInfo¶

record base/tealdef/mission/mission_task_util.d.tl:12

record StaticTaskInfo

Notes

Static description of one task in a story. It names the script that runs the task, its params, what the GUI shows and which tasks follow.

Details

Returned by the story's task-data factory for each task key. The fields other than taskScript, taskParams, taskInfo, guideInfo and followup become the task's MissionInterface.GenericTaskParams (visible/invisible/enabled/disabled are converted to rule maps).

Example

-- urbangames_campaign_mission_01 mission_story.tl
if taskKey == "find_alligators_end" then
    return {
        taskScript = page as MissionInterface.TaskScript<any, any>,
        taskInfo = {
            name = _("MISSION_01_TASK_FIND_ALLIGATORS_END_NAME"),
            options = { { text = _("MISSION_01_TASK_FIND_ALLIGATORS_END_BUTTON_1"), key = "finish" } },
        },
        followup = {
            { taskKey = "build_path_task" },
            { taskKey = "build_path_task_cutscene" },
        },
        highlightRules = { {"menu.mission.task-button", "Square"} },
        notificationFilter = { ["::/landmarks/landmarks_notification.script"] = true },
    }
end

Used in the base game: 58 times in 42 files

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

local type GetTaskDataFn = function(taskKey : string) : MissionTaskUtil.StaticTaskInfo

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/tutorial/tutorial_story.tl:36

local taskDataFactoryA = ug_require "tutorial_story_branch_a.tl" as function(taskKey : string) : MissionTaskUtil.StaticTaskInfo

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

return function(taskKey : string) : MissionTaskUtil.StaticTaskInfo

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

local taskDataFactory = ug_require "tutorial_story.tl" as function(taskKey : string) : MissionTaskUtil.StaticTaskInfo

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

return function(taskKey : string) : MissionTaskUtil.StaticTaskInfo

… and 36 more files.

Fields

Name	Type	Description
`isBonusTask`	`boolean`	Marks the task as a bonus mission.
`taskScript`	`MissionInterface.TaskScript<any, any>`	Script implementing the task (one of the task types under `mission/tasks/**` or a custom one).
`taskKey`	`string`	Task key.
`taskParams`	`any`	Params of the task script (its `Params` record).
`medals`	`{string : boolean}`	Medal ids awarded while this task exists (e.g. `{ MISSION_01_MEDAL_1 = true }`).
`stars`	`{string : boolean}`	Star ids and their state.
`visible`	`{string}`	GUI classes made visible while the task is open.
`invisible`	`{string}`	GUI classes hidden while the task is open.
`enabled`	`{string}`	GUI ids/tags enabled while the task is open.
`disabled`	`{string}`	GUI ids/tags disabled while the task is open (e.g. `"menu.construction.rail"`).
`highlightRules`	`{{string, MissionInterface.HighlightStyle}}`	List of `{ GUI id/tag, highlight style }` pairs.
`taskInfo`	`MissionInterface.TaskInfo`	Only to be used in a mission
`guideInfo`	`MissionInterface.GuideInfo`	Only to be used in the guide system
`omitNotificationOnComplete`	`boolean`	Suppresses the completion notification.
`disableGuideSystem`	`boolean`	Keeps the guide system inactive while the task is open.
`startSoundtrack`	`string`	Music track started when the task opens.
`soundtrack`	`MissionInterface.MissionSoundtrack`	Tracklist played while the task is open.
`playlistOverride`	`ResName`	Playlist used while the task is open.
`allowBuyVehicles`	`{string : integer}`	(modelname -> count, minCount)
`allowBuyVehicleGroups`	`{string : {{string}, integer}}`	id, -> modelnames, count
`lockedVehicles`	`{Engine.Entity}`	entity ids that may not be sold
`followup`	`{FollowupDef}`	Tasks added when this task completes.
`vehicleFilter`	`GameContext.Filters.VehicleFilter`	Vehicle store filter while the task is open.
`notificationFilter`	`{string : boolean}`	Notification types hidden while the task is open.
`menuFilter`	`GameContext.Filters.MenuFilter`	Menu items enabled or disabled while the task is open.
`selectorEntityFilter`	`{Engine.Entity : boolean}`	Entity selection filter while the task is open.
`disableFeatures`	`{DisableFeatures : boolean}`	GUI features switched off while the task is open.
`requiredTaskToComplete`	`string`	taskkey <- mission_task_util.makeTaskKey
`allowSimultaneousUiTasks`	`{string}`	taskkey <- mission_task_util.makeTaskKey
`spawnGuide`	`{string}`	Script events sent when the task is added (e.g. `"spawn-camera-guide"`).
`showInHistory`	`boolean`	Keeps the task listed after completion and sends a completion notification.
`suppressAutoOpen`	`boolean`	Keeps the mission window from opening automatically for this task.
`financialReward`	`integer`	Money paid when the task completes, in game currency.