notifications¶

Source: base/tealdef/game_mechanics/notifications/notifications.d.tl

Notes

Records of the notification system, the state of its game script and the event params for adding, dismissing and ignoring notifications.

Globals¶

Types

Name	Definition	Description
`GameContext`	`declared here, defined in GameContext`	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.

NotificationGuiData¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:5

global record NotificationGuiData

Notes

What a notification type's useDataState returns; the pop-up, the log, entity windows and the HUD display it.

Fields

Name	Type	Description
`title`	`string`	Title of the notification.
`description`	`string`	Body text of the notification.
`icon`	`string`	Path of the icon image, e.g. `"::/game_mechanics/notifications/gui/icons/terminal_full.tga"`.
`hudIcon`	`string`	optional, if specified, for persistent notifications, a hud icon will be displayed above the according component carrying the entity
`lvmIcon`	`string`	optional, if specified, for persistent notifications, the issue will be displayed in the lvm for the according line/vehicle/...
`iconExplainTooltip`	`string`	optional, used to explain when hovering potential hud- or lvm icon
`previewImage`	`string`	optional
`soundOnMount`	`{FilePath}`	optional, one of the provided will be played randomly
`status`	`Status`	optional
`progress`	`Progress`	optional
`progresses`	`{Progress}`	Several progress bars. A set `progress` takes precedence.

Functions

wouldClick() : boolean base/tealdef/game_mechanics/notifications/notifications.d.tl:28

optional

Returns boolean

onClick(stack : boolean, dryRun? : boolean) : boolean base/tealdef/game_mechanics/notifications/notifications.d.tl:29

optional

Returns boolean

NotificationGuiData.Type¶

enum base/tealdef/game_mechanics/notifications/notifications.d.tl:6

enum Type

Notes

GUI category of a notification type, set with guiType in its .res file. It picks the color and the filter group in the notification log.

Used in the base game: 20 times in 7 files

base/content/gui/gui/line_vehicle_mgmt/line_react_util.tl:72

local type2class <total> : {NotificationGuiData.Type : string} = {

base/content/gui/gui/entity_window/entity_window_util.tl:2069

local type2class <total> : {NotificationGuiData.Type : string} = {

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:752

for __, guiType in ipairs((param as table).ignoredGuiTypes as {NotificationGuiData.Type}) do

base/content/game_mechanics/game_mechanics/notifications/notification_util.tl:12

notificationUtil.getGuiTypeFromNotificationType = function(name : string) : NotificationGuiData.Type

base/content/game_mechanics/game_mechanics/notifications/gui/notification_log.tl:13

local type2class <total>: {NotificationGuiData.Type:string} = {

base/content/game_mechanics/game_mechanics/notifications/gui/notification_popups.tl:13

local NotificationPopupContent = react.RegisterRecipe("NotificationPopupContent", function(params : NotificationGuiData, guiType : NotificationGuiData.Type) : T

… and 1 more files.

Value	Description
`"Info"`	News, e.g. new vehicles or constructions, a founded industry, a new cargo demand.
`"Caution"`	Warnings, e.g. an overcrowded station, a closing industry, a vehicle in bad condition.
`"Problem"`	Problems, e.g. line, station, vehicle or town connection issues.
`"Opportunity"`	Subsidies (available, in progress, active, failed).
`"Achievement"`	Successes, e.g. company rank-up, town notifications, completed mission tasks, landmarks.
`"Unknown"`	NOTE: fall-back value to avoid modding issues, should not be used on purpose

NotificationGuiData.Status¶

enum base/tealdef/game_mechanics/notifications/notifications.d.tl:15

enum Status

Notes

Optional state of an Opportunity notification that changes its icon and progress-bar style.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/notifications/types/notification_react_util.tl:21

local status2class <total>: {NotificationGuiData.Status:string} = {

Value	Description
`"Pending"`	The subsidy is proposed and not yet started.
`"Failed"`	The subsidy failed.

NotificationGuiData.Progress¶

record base/tealdef/game_mechanics/notifications/notifications.d.tl:32

record Progress

Notes

One progress bar in the notification.

Used in the base game: 5 times in 4 files

base/content/landmarks/landmarks_notification.script.tl:12

progress : NotificationGuiData.Progress

base/content/game_mechanics/game_mechanics/company/company_notification_marketing.script.tl:12

local makeProgressState = function() : NotificationGuiData.Progress

base/content/game_mechanics/game_mechanics/notifications/types/subvention_notification.script.tl:16

progresses : {NotificationGuiData.Progress}

base/content/game_mechanics/game_mechanics/notifications/types/industry_close.script.tl:17

progress : NotificationGuiData.Progress

Fields

Name	Type	Description
`percentage`	`number`	Progress from 0 to 1.
`text`	`string`	Label of the bar. Without it the GUI shows the remaining time from `remainingDurationMs`.
`remainingDurationMs`	`number`	optional

NotificationSimType¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:41

global record NotificationSimType<T>

Notes

Sim update script of a notification type, referenced by simUpdateScript in the type's .res file (e.g. "::/game_mechanics/notifications/types/overcrowding.sim.script@updateData").

Details

The notifications game script calls updateData when a notification is added and afterwards for each notification about every 30th tick. Use it to copy data that the GUI cannot read later, such as the name of an entity that may be removed.

Example

-- base game, notifications/types/overcrowding.sim.script.tl
local data : NotificationSimType<OvercrowdingNotificationParams> = {}

data.updateData = function(notificationParams : OvercrowdingNotificationParams, old : StationBusyNotificationSimParams) : StationBusyNotificationSimParams
    if old.mapping == nil then
        old.mapping = {}
    end
    if not entity_util.entityChanged0(notificationParams.entity) then
        old.mapping[notificationParams.entity.entity] = entity_util.getEntityName(notificationParams.entity.entity)
    end
    return old
end

return data

Functions

updateData(T, any) : any base/tealdef/game_mechanics/notifications/notifications.d.tl:42

Notes

Computes the notification's simParams.

Parameter	Type	Description
`#1`	`T`	The notification's `params`.
`#2`	`any`	The previous `simParams` (an empty table on the first call).

Returns any: The new simParams.

NotificationType¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:45

global record NotificationType<T>

Notes

GUI script of a notification type; the script named by Notification.type returns it.

Example

-- base game, notifications/types/overcrowding.script.tl (shortened)
local data : NotificationType<OvercrowdingNotificationParams> = {}

data.useDataState = function(notificationParams : OvercrowdingNotificationParams, simParams : StationBusyNotificationSimParams) : NotificationGuiData
    local icon = "::/game_mechanics/notifications/gui/icons/terminal_full.tga"
    local state = engine_react_util.useStepStateTimer(function() : string
        return simParams.mapping[notificationParams.entity.entity]
    end)
    return {
        title = _("Station Overcrowded"),
        description = lang_util.format(_("{stationName} is overcrowded, passengers will be leaving."), { stationName = state:old() }),
        icon = icon,
        hudIcon = icon,
        lvmIcon = icon,
        wouldClick = notification_util.makeDefaultWouldClick({notificationParams.entity}),
        onClick = notification_util.makeDefaultOnClick({notificationParams.entity}),
    }
end

return data

Functions

useDataState(T, ?any) : NotificationGuiData base/tealdef/game_mechanics/notifications/notifications.d.tl:49

only use in recipe WITHOUT another DEPENDENT state (as *THIS provides already one or more!) use as last state in recipe, as the number of states provided might differ use localKey in parent recipe to ensure proper update

Returns NotificationGuiData

Notification¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:52

global record Notification

Notes

A notification as sent with the Notifications/add script event and stored in NotificationsState.

Details

type names a notification type script. The .res file with the same base name (type = "notification") holds its guiType, label, simUpdateScript and initiallyIgnoredType; the script itself returns a NotificationType whose useDataState(params, simParams) builds the GUI text and icons.

A notification expires (and is hidden from pop-ups) when autoDismissDuration has passed, or when params.entities is a non-empty list of EntityUtil.EntityAndRevision and every one of those entities has changed or is gone.

add events are dropped while the notifications state is paused, and notifications of a fully ignored type are not stored at all (see NotificationsState.Ignored).

Example

-- urbangames_deluxe_upgrade_pack, fun_elements/balloon.script.tl
api.cmd.sendCommand(api.cmd.makeScriptingSendEventCmd("", "Notifications", "add", {
    type = resolve("balloon_notification.script"),
    params = {
        entity = entity_util.makeEntityAndRevision0(balloon.entity),
        townEntity = entity_util.makeEntityAndRevision0(townEntity),
    },
    autoDismissDuration = notification_util.defaultAutoDismissDurationMs,
}))

Fields

Name	Type	Description
`type`	`string`	Name of the notification type script, e.g. `"::/game_mechanics/notifications/types/subvention.script"` (the resource path with `.script` instead of `.res`).
`params`	`table`	Type-specific params, passed to the type's `useDataState` and to its sim update script. A list of entities in `params.entities` makes the notification expire once all of them have changed.
`notificationId`	`integer`	Id of the notification. It is not stored in the state (the id is the key of `NotificationsState.notifications`); the function from `NotificationReactUtil.createNotificationCacheAccessFn` fills it in.
`autoDismissDuration`	`integer`	NOTE: THIS IS NOT THE SAME AS "dismiss", this is basically a "hide" after a certain time
`simParams`	`any`	Data computed on the simulation side by the type's `simUpdateScript` (for example entity names), passed to `useDataState` as the second argument. `addNotification` overwrites it.

PersistentNotifications¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:60

global record PersistentNotifications

Notes

Param of the Notifications/updatePersistent event. Sets the complete list of persistent notifications of one type.

Details

Existing persistent notifications of type whose entities and params are not in the new list expire; entries that are new get added. A persistent notification stays in the history beyond the 100-entry limit and is shown in entity windows, the line and vehicle manager and as a HUD icon (if its GUI data has hudIcon / lvmIcon).

Example

-- urbangames_campaign_mission_05, mission/tasks/drilling/drilling.tl
local persistentNotifications : PersistentNotifications = {
    type = "urbangames_campaign_mission_05::/mission/tasks/drilling/mission_drilling_notification.script",
    entitiesAndParam = {{
        entities = entity_util.makeEntityAndRevision0Array(getEntititesForNotification(entity)),
        param = notificationParams,
    }},
    passOnlyParam = true,
}
api.cmd.sendCommand(api.cmd.makeScriptingSendEventCmd("", "Notifications", "updatePersistent", persistentNotifications))

Fields

Name	Type	Description
`entitiesAndParam`	`{EntitiesAndParam}`	All persistent notifications of this type that should exist now.
`type`	`string`	Notification type script, as in `Notification.type`.
`passOnlyParam`	`boolean`	If true, `param` becomes the notification's `params`; otherwise `params` is `{ entities = ..., param = ... }`.

PersistentNotifications.EntitiesAndParam¶

record base/tealdef/game_mechanics/notifications/notifications.d.tl:61

record EntitiesAndParam

Notes

One persistent notification.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/notifications/notification_util.tl:211

local makeNotificationParam = function(entitiesAndParam : PersistentNotifications.EntitiesAndParam) : table

Fields

Name	Type	Description
`entities`	`{EntityUtil.EntityAndRevision}`	Entities the notification sticks to; it is matched by these and shown for them.
`param`	`any`	Type-specific param of the notification.

RemovePersistentNotifications¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:70

global record RemovePersistentNotifications

Notes

Param of the Notifications/removePersistent event. Expires the persistent notifications of type whose entities equal entities.

Example

-- urbangames_campaign_mission_05, mission/tasks/drilling/drilling.tl
local persistentNotifications : RemovePersistentNotifications = {
    type = "urbangames_campaign_mission_05::/mission/tasks/drilling/mission_drilling_notification.script",
    entities = entity_util.makeEntityAndRevision0Array(getEntititesForNotification(entity)),
}
api.cmd.sendCommand(api.cmd.makeScriptingSendEventCmd("", "Notifications", "removePersistent", persistentNotifications))

Fields

Name	Type	Description
`entities`	`{EntityUtil.EntityAndRevision}`	Entity list to match, compared deeply with the stored entities.
`type`	`string`	Notification type script, as in `Notification.type`.

DismissNotification¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:75

global record DismissNotification

Notes

Param of the Notifications/dismiss event (hides a notification from the pop-ups) and of the enlist event (shows it again).

Fields

Name	Type	Description
`id`	`integer`	Id of the notification (key in `NotificationsState.notifications`).

NotificationsState¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:79

global record NotificationsState

Notes

State of the game script ::/game_mechanics/notifications/notifications.gs. Read it with NotificationUtil.externalGetNotificationsState().

Details

The script handles these events (id "Notifications"): add (Notification), updatePersistent (PersistentNotifications), removePersistent (RemovePersistentNotifications), dismiss and enlist (DismissNotification), updateIgnoredTypes ({ ignoredTypes = {[type] = true}, ignoredGuiTypes = {...}, ignoreFully = boolean }), pause (boolean) and initialSound ({ notificationId = id }).

Besides stored notifications it creates persistent notifications itself for line, station, town, vehicle, industry, subsidy and company issues.

Example

-- base game, mission/mission_sim.script.tl: hide some types completely during a mission
api.cmd.sendCommand(api.cmd.makeScriptingSendEventCmd("", "Notifications", "updateIgnoredTypes", {
    ignoredTypes = newNotificationFilter,
    ignoreFully = true,
}))

Fields

Name	Type	Description
`notifications`	`{integer : Entry}`	Stored notifications by id.
`history`	`{integer}`	Notification ids, oldest first. Adding trims it to 100 entries; persistent notifications are kept.
`maxId`	`integer`	Last id handed out. Ids wrap around at 1000000.
`version`	`integer`	Version of the state layout, compared with `NotificationLegacyUtil.CurrentVersion` when a save game is loaded.
`ignored`	`Ignored`	Ignored notification types; initially the types with `initiallyIgnoredType = true` in their `.res` file, with `fully = false`.
`paused`	`boolean`	While true, the script skips its update and drops `add` events.
`noRoadConnectionUpdateTimestamp`	`integer`	Game time (ms) of the last check for stations without road connection. The check runs again after `75 * api.util.getDefaultDayDuration()`.
`vehicle2problem`	`{Engine.Entity : VehicleProblem}`	Player vehicles that are en route, not stopped by the user, and have speed 0. After 5 minutes of game time (300000 ms) they get a "Vehicle Stuck" notification.
`line2problemTimestamp`	`{Engine.Entity : integer}`	Game time (ms) when a problem of each line was first seen; lines without a problem are removed.
`stationGroup2overflowResolvedTimestamp`	`{Engine.Entity : integer}`	Game time (ms) when each station group was first seen without overflow. The cooldown that read it is commented out in the base game.
`wastedVehicles`	`{Engine.Entity : boolean}`	Vehicles that have a "Vehicle Condition" notification. A vehicle is added at maintenance state 0.2 or less and stays until the state rises above 0.3.

NotificationsState.Entry¶

record base/tealdef/game_mechanics/notifications/notifications.d.tl:80

record Entry

Notes

One stored notification with its display state.

Used in the base game: 11 times in 3 files

base/content/game_mechanics/game_mechanics/notifications/notification_util.tl:103

local notificationEntry : NotificationsState.Entry = state.notifications[notificationId]

base/content/game_mechanics/game_mechanics/notifications/gui/notification_log.tl:24

entry : NotificationsState.Entry

base/content/game_mechanics/game_mechanics/notifications/gui/notification_popups.tl:240

entry : NotificationsState.Entry

Fields

Name	Type	Description
`timestamp`	`integer`	Game time (ms) when the notification was added.
`notification`	`Notification`	The notification.
`persisting`	`{EntityUtil.EntityAndRevision}`	if #> 0, the notification will not be deleted with the history entry
`dismissed`	`boolean`	user input: dismiss via right mouse click on pop-up or toggle in log to hide it in popups
`expired`	`boolean`	not "active" anymore, (maximal, ie only iff tracked) visible in history log
`tracked`	`boolean`	if not ignored for popups/log then it is tracked for log and also shown there
`playedInitialSound`	`boolean`	The pop-up has played its sound; set by the `initialSound` event so the sound plays only once.

NotificationsState.Ignored¶

record base/tealdef/game_mechanics/notifications/notifications.d.tl:96

record Ignored

Notes

Which notification types are ignored and how. Set by the updateIgnoredTypes event and by the filter in the notification log.

Used in the base game: 2 times in 1 file

base/content/game_mechanics/game_mechanics/notifications/gui/notification_log.tl:328

ignored : NotificationsState.Ignored

Fields

Name	Type	Description
`fully`	`boolean`	Controls how the notification types in "types" are ignored (types not in the set are unaffected): true: no notification entry is created at all, so they are completely unobserved the filter in the notification log is disabled in this mode, as it controls the case below false: entries are still created, but dismissed and untracked, so they are hidden in the log and popup ridge while still showing up in EOWs, LVM and as HUD icons the log's filter can be used to change types with this level of ignorance Defaults to true when "updateIgnoredTypes" is sent without "ignoreFully". Note that whenver Ignored changes, that fully is set for the whole current state. It is advised to usually go with either strategy per "game". (I.e. default game is usually false, while missions might go with true.)
`types`	`{string : boolean}`	set of notification type names to ignore (see "fully" for how)

NotificationsState.VehicleProblem¶

record base/tealdef/game_mechanics/notifications/notifications.d.tl:119

record VehicleProblem

Notes

Tracking data for a vehicle that stands still.

Used in the base game: 1 time in 1 file

base/content/game_mechanics/game_mechanics/notifications/notifications.script.tl:539

local newVehicle2Problem : { Engine.Entity : NotificationsState.VehicleProblem } = {}

Fields

Name	Type	Description
`problemSince`	`integer`	Game time (ms) since which the vehicle stands still.

NotificationButtonParam¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:129

global record NotificationButtonParam

Notes

Params of the NotificationButton recipe (notifications/gui/notification_button.tl), the game-bar button that opens and closes the notification log.

Fields

Name	Type	Description
`gameCtx`	`GameContext`	Game GUI context; its tool stack holds the log window.

NotificationLogToolParam¶

record global base/tealdef/game_mechanics/notifications/notifications.d.tl:133

global record NotificationLogToolParam is ToolReactUtil.IToolParam

Notes

Params of the notification log tool window, pushed by the notification button.

Fields

Name	Type	Description
`gameCtx`	`GameContext`	Game GUI context.
`initialFilterState`	`FilterState`	Filter settings to start with; `nil` opens the history view with no category filter.

Functions

onClose() base/tealdef/game_mechanics/notifications/notifications.d.tl:140

Notes

Closes the log window.

storeFilterState(FilterState) base/tealdef/game_mechanics/notifications/notifications.d.tl:141

Notes

Receives the current filter settings so the next opening can restore them.

NotificationLogToolParam.FilterState¶

record base/tealdef/game_mechanics/notifications/notifications.d.tl:134

record FilterState

Notes

Filter settings of the log window. The button keeps them between openings.

Used in the base game: 9 times in 2 files

base/content/game_mechanics/game_mechanics/notifications/gui/notification_log.tl:350

local filterState : ReactStateT<NotificationLogToolParam.FilterState> = react.useStateLazy(function() : NotificationLogToolParam.FilterState

base/content/game_mechanics/game_mechanics/notifications/gui/notification_button.tl:2

local NotificationLogTool = ug_require "/game_mechanics/notifications/gui/notification_log.tl" as ReactToolDefinition<NotificationLogToolParam.FilterState>

Fields

Name	Type	Description
`category`	`NotificationGuiData.Type`	GUI category shown in the log; `nil` shows all.
`displayIndex`	`integer`	1 = history, 2 = active