notification_util¶

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

Notes

Helpers that read notification type resources and change or read the notifications game-script state.

NotificationUtil¶

record global base/tealdef/game_mechanics/notifications/notification_util.d.tl:3

global record NotificationUtil

Load: local notification_util = ug_require "::/game_mechanics/notifications/notification_util.tl"

Notes

Helpers for notification type resources and the notifications game-script state.

Details

Functions that take a NotificationsState change that table; the game script uses them inside its own update and event handler. Scripts outside it should send the Notifications events instead (see Notification).

Fields

Name	Type	Description
`defaultAutoDismissDurationMs`	`integer`	Default `autoDismissDuration` of a notification, 60000 ms of game time. used 19× in the base game

Functions

getGuiTypeFromNotificationType(name : string) : NotificationGuiData.Type base/tealdef/game_mechanics/notifications/notification_util.d.tl:6

Call as notification_util.getGuiTypeFromNotificationType

Notes

Reads the GUI category of a notification type from its .res file.

Parameter	Type	Description
`name`	`string`	Notification type script, as in `Notification.type`.

Returns NotificationGuiData.Type: The guiType of the resource, or "Unknown" if there is no such notification resource or it has no guiType.

Used in the base game: 11 times in 6 files

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

local guiType = notification_util.getGuiTypeFromNotificationType(params.notification.type)

base/content/gui/gui/statistics/statistics_react_util.tl:276

local guiType = notification_util.getGuiTypeFromNotificationType(notificationType)

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

local guiType = notification_util.getGuiTypeFromNotificationType(params.notification.type)

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

local guiType = notification_util.getGuiTypeFromNotificationType(param.entry.notification.type)

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

local guiType = notification_util.getGuiTypeFromNotificationType(params.notification.type)

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

local guiType = notification_util.getGuiTypeFromNotificationType(params.notification.type)

getInitiallyIgnoredTypes() : {string : boolean} base/tealdef/game_mechanics/notifications/notification_util.d.tl:7

Call as notification_util.getInitiallyIgnoredTypes

Notes

Reads initiallyIgnoredType of all notification resources.

Returns {string : boolean}: Map from notification type script name to whether it is ignored in a new game.

Used in the base game: 2 times in 1 file

base/content/game_mechanics/game_mechanics/notifications/notification_legacy_util.tl:15

types = notification_util.getInitiallyIgnoredTypes(),

getNotificationType2Label() : {string : string} base/tealdef/game_mechanics/notifications/notification_util.d.tl:8

Call as notification_util.getNotificationType2Label

Notes

Reads the labels of all notification resources, as shown in the log filter.

Returns {string : string}: Map from notification type script name to its label; types without a label are left out.

Used in the base game: 1 time in 1 file

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

return notification_util.getNotificationType2Label()

getAllNotificationGuiTypes() : {NotificationGuiData.Type} base/tealdef/game_mechanics/notifications/notification_util.d.tl:9

Call as notification_util.getAllNotificationGuiTypes

Notes

Collects the GUI categories used by all notification resources.

Returns {NotificationGuiData.Type}: Distinct categories in no fixed order; "Unknown" stands for resources without guiType.

Used in the base game: 1 time in 1 file

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

local allTypes = notification_util.getAllNotificationGuiTypes()

getAllNotificationTypesForGuiType(guiType : NotificationGuiData.Type) : {string} base/tealdef/game_mechanics/notifications/notification_util.d.tl:10

Call as notification_util.getAllNotificationTypesForGuiType

Notes

Lists all notification types of one GUI category.

Parameter	Type	Description
`guiType`	`NotificationGuiData.Type`	The category.

Returns {string}: Notification type script names.

Used in the base game: 3 times in 2 files

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

local notificationTypes = notification_util.getAllNotificationTypesForGuiType(guiType)

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

local names =  notification_util.getAllNotificationTypesForGuiType(ignorableType)

getNotificationSimUpdateScript(type : string) : string base/tealdef/game_mechanics/notifications/notification_util.d.tl:11

Call as notification_util.getNotificationSimUpdateScript

Notes

Reads the simUpdateScript of a notification type.

Parameter	Type	Description
`type`	`string`	Notification type script, as in `Notification.type`.

Returns string: The function path, e.g. "::/game_mechanics/notifications/types/overcrowding.sim.script@updateData", or nil.

Used in the base game: 1 time in 1 file

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

local updateScript = notification_util.getNotificationSimUpdateScript(notificationEntry.notification.type)

removeNotification(NotificationsState, integer) base/tealdef/game_mechanics/notifications/notification_util.d.tl:13

Call as notification_util.removeNotification

Notes

Deletes a notification from the state and the history.

Parameter	Type	Description
`#1`	`NotificationsState`	Notifications state to change.
`#2`	`integer`	Id of the notification. Unknown ids are ignored.

Used in the base game: 2 times in 1 file

base/content/game_mechanics/game_mechanics/notifications/notification_legacy_util.tl:404

notification_util.removeNotification(notificationsState, id)

addNotification(NotificationsState, Notification) : integer base/tealdef/game_mechanics/notifications/notification_util.d.tl:14

Call as notification_util.addNotification

Notes

Stores a new notification, runs its sim update script and trims the history to 100 entries.

Parameter	Type	Description
`#1`	`NotificationsState`	Notifications state to change.
`#2`	`Notification`	The notification.

Returns integer: Id of the new notification; nil if its type is fully ignored, -1 if no free id was found.

Details

It does not check paused; the add event handler does.

Used in the base game: 1 time in 1 file

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

notification_util.addNotification(notificationsState, notification)

enlistNotification(state : NotificationsState, notificationId : integer) base/tealdef/game_mechanics/notifications/notification_util.d.tl:15

Call as notification_util.enlistNotification

Notes

Clears the dismissed flag so the notification shows in the pop-ups again.

Parameter	Type	Description
`state`	`NotificationsState`	Notifications state to change.
`notificationId`	`integer`	Id of the notification.

Used in the base game: 1 time in 1 file

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

notification_util.enlistNotification(notificationsState, (param as DismissNotification).id)

dismissNotification(state : NotificationsState, notificationId : integer) base/tealdef/game_mechanics/notifications/notification_util.d.tl:16

Call as notification_util.dismissNotification

Notes

Sets the dismissed flag, which hides the notification from the pop-ups.

Parameter	Type	Description
`state`	`NotificationsState`	Notifications state to change.
`notificationId`	`integer`	Id of the notification.

Used in the base game: 1 time in 1 file

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

notification_util.dismissNotification(notificationsState, (param as DismissNotification).id)

updatePersistentNotifications(NotificationsState, {string : {integer}}, PersistentNotifications) base/tealdef/game_mechanics/notifications/notification_util.d.tl:17

Call as notification_util.updatePersistentNotifications

Notes

Applies a PersistentNotifications update; the updatePersistent event calls it.

Parameter	Type	Description
`#1`	`NotificationsState`	Notifications state to change.
`#2`	`{string : {integer}}`	Persistent notification ids by type, from `getPersistentHistoryByType`.
`#3`	`PersistentNotifications`	The update.

Used in the base game: 19 times in 1 file

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

notification_util.updatePersistentNotifications(notificationsState, historyByType, persistentNotifications)

removePersistentNotifications(NotificationsState, {string : {integer}}, RemovePersistentNotifications) base/tealdef/game_mechanics/notifications/notification_util.d.tl:18

Call as notification_util.removePersistentNotifications

Notes

Expires the persistent notifications that match a RemovePersistentNotifications; the removePersistent event calls it.

Parameter	Type	Description
`#1`	`NotificationsState`	Notifications state to change.
`#2`	`{string : {integer}}`	Persistent notification ids by type, from `getPersistentHistoryByType`.
`#3`	`RemovePersistentNotifications`	Type and entities to match.

Used in the base game: 1 time in 1 file

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

notification_util.removePersistentNotifications(notificationsState, historyByType, persistentNotifications)

externalGetNotificationsState() : NotificationsState base/tealdef/game_mechanics/notifications/notification_util.d.tl:19

Call as notification_util.externalGetNotificationsState

Notes

Reads the state of the notifications game script from its GAME_SCRIPT component.

Returns NotificationsState: The state as a Lua table.

getPersistentHistoryByType(state : NotificationsState) : {string : {integer}} base/tealdef/game_mechanics/notifications/notification_util.d.tl:20

Call as notification_util.getPersistentHistoryByType

Notes

Groups the ids of persistent notifications in the history by type.

Parameter	Type	Description
`state`	`NotificationsState`	Notifications state.

Returns {string : {integer}}: Map from notification type to ids, in history order.

Used in the base game: 3 times in 1 file

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

local historyByType = notification_util.getPersistentHistoryByType(notificationsState)

removeUnavailableAvailabilityNotifications(state : NotificationsState) base/tealdef/game_mechanics/notifications/notification_util.d.tl:21

Call as notification_util.removeUnavailableAvailabilityNotifications

Notes

Deletes "new vehicle" notifications whose models or multiple units no longer exist, e.g. after a mod was removed. Runs when a save game is loaded.

Parameter	Type	Description
`state`	`NotificationsState`	Notifications state to change.

Used in the base game: 1 time in 1 file

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

notification_util.removeUnavailableAvailabilityNotifications(notificationsState)

externalGetNotificationsStateNative() : NativeLuaTable base/tealdef/game_mechanics/notifications/notification_util.d.tl:23

Call as notification_util.externalGetNotificationsStateNative

Notes

Reads the notifications game-script state without converting it to a Lua table (state_native of the GAME_SCRIPT component).

Returns NativeLuaTable: The native state; read it with the ...FromNative functions.

Used in the base game: 19 times in 13 files

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

local notificationStateNative : NativeLuaTable = notification_util.externalGetNotificationsStateNative()

base/content/gui/gui/main/game_tooltips.tl:172

local notificationStateNative : NativeLuaTable = notification_util.externalGetNotificationsStateNative()

base/content/gui/gui/statistics/statistic_warehouses.tl:311

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

base/content/gui/gui/statistics/statistic_lines.tl:384

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

base/content/gui/gui/statistics/statistic_stations.tl:272

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

base/content/gui/gui/statistics/statistics_react_util.tl:267

local stateNative = notification_util.externalGetNotificationsStateNative()

… and 7 more files.

getPersistingEntity2NotificationFromNative(nativeState : NativeLuaTable) : {Engine.Entity : {integer}} base/tealdef/game_mechanics/notifications/notification_util.d.tl:24

Call as notification_util.getPersistingEntity2NotificationFromNative

Notes

Maps each entity to the persistent notifications that stick to it.

Parameter	Type	Description
`nativeState`	`NativeLuaTable`	State from `externalGetNotificationsStateNative`.

Returns {Engine.Entity : {integer}}: Map from entity to notification ids.

Used in the base game: 12 times in 10 files

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

local persistingEntity2Notification = notification_util.getPersistingEntity2NotificationFromNative(notificationStateNative)

base/content/gui/gui/main/game_tooltips.tl:173

local persistingEntity2Notification = notification_util.getPersistingEntity2NotificationFromNative(notificationStateNative)

base/content/gui/gui/statistics/statistic_warehouses.tl:311

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

base/content/gui/gui/statistics/statistic_lines.tl:384

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

base/content/gui/gui/statistics/statistic_stations.tl:272

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

base/content/gui/gui/statistics/statistic_industries.tl:395

notificationsState = notification_util.getPersistingEntity2NotificationFromNative(notification_util.externalGetNotificationsStateNative()),

… and 4 more files.

getHistoryFromNative(nativeState : NativeLuaTable) : {integer} base/tealdef/game_mechanics/notifications/notification_util.d.tl:25

Call as notification_util.getHistoryFromNative

Notes

Copies the history from the native state.

Parameter	Type	Description
`nativeState`	`NativeLuaTable`	State from `externalGetNotificationsStateNative`.

Returns {integer}: Notification ids, oldest first.

Used in the base game: 2 times in 2 files

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

local history = notification_util.getHistoryFromNative(notificationsState)

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

local history = notification_util.getHistoryFromNative(notificationsStateNative)

getNotificationFromNative(nativeState : NativeLuaTable, notificationId : integer) : Notification base/tealdef/game_mechanics/notifications/notification_util.d.tl:26

Call as notification_util.getNotificationFromNative

Notes

Copies one notification from the native state.

Parameter	Type	Description
`nativeState`	`NativeLuaTable`	State from `externalGetNotificationsStateNative`.
`notificationId`	`integer`	Id of the notification.

Returns Notification: The notification as a Lua table.

Used in the base game: 5 times in 5 files

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

local notification = notification_util.getNotificationFromNative(notificationStateNative, notificationId)

base/content/gui/gui/main/game_tooltips.tl:178

local notification = notification_util.getNotificationFromNative(notificationStateNative, notificationId)

base/content/gui/gui/statistics/statistics_react_util.tl:360

notification = notification_util.getNotificationFromNative(nativeState, warningState:old()[1])

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

local notification = notification_util.getNotificationFromNative(notificationStateNative, notificationId)

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

local notification = notification_util.getNotificationFromNative(notificationStateRef:get(), notificationId)

getNotificationEntryFromNative(nativeState : NativeLuaTable, notificationId : integer) : NotificationsState.Entry base/tealdef/game_mechanics/notifications/notification_util.d.tl:27

Call as notification_util.getNotificationEntryFromNative

Notes

Copies one state entry (notification with display flags) from the native state.

Parameter	Type	Description
`nativeState`	`NativeLuaTable`	State from `externalGetNotificationsStateNative`.
`notificationId`	`integer`	Id of the notification.

Returns NotificationsState.Entry: The entry as a Lua table.

Used in the base game: 2 times in 1 file

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

local notification = notification_util.getNotificationEntryFromNative(notificationStateNative, params.notificationId)

makeDefaultWouldClick(entityAndRevision : {EntityUtil.EntityAndRevision}) : function() : boolean base/tealdef/game_mechanics/notifications/notification_util.d.tl:29

Call as notification_util.makeDefaultWouldClick

Notes

Makes a wouldClick function for NotificationGuiData.

Parameter	Type	Description
`entityAndRevision`	`{EntityUtil.EntityAndRevision}`	Entities of the notification.

Returns function() : boolean: Function that returns true if one of the entities still exists unchanged.

Used in the base game: 20 times in 20 files

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

wouldClick = notification_util.makeDefaultWouldClick({notificationParams.entity}),

base/content/landmarks/landmarks_notification_nonpersistent.script.tl:11

wouldClick = notification_util.makeDefaultWouldClick({notificationParams.entity}),

base/content/game_mechanics/game_mechanics/company/company_notification_prospection.script.tl:87

wouldClick = notification_util.makeDefaultWouldClick({notificationParams.resultEntity, notificationParams.townEntity}),

base/content/game_mechanics/game_mechanics/company/company_notification_greenify.script.tl:34

wouldClick = notification_util.makeDefaultWouldClick({notificationParams.constructionEntity}),

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

wouldClick = notification_util.makeDefaultWouldClick({notificationParams.townEntity}),

base/content/game_mechanics/game_mechanics/towns/town_notification.script.tl:26

wouldClick = notification_util.makeDefaultWouldClick({notificationParams.townEntity}),

… and 14 more files.

makeDefaultOnClick(entityAndRevision : {EntityUtil.EntityAndRevision}) : function(stack : boolean) : boolean base/tealdef/game_mechanics/notifications/notification_util.d.tl:30

Call as notification_util.makeDefaultOnClick

Notes

Makes an onClick function for NotificationGuiData that moves the camera to the first entity that still exists unchanged and selects it.

Parameter	Type	Description
`entityAndRevision`	`{EntityUtil.EntityAndRevision}`	Entities of the notification.

Returns function(stack : boolean) : boolean: Function that takes stack (passed with the selectEntity GUI event) and returns true if it found an entity.

Used in the base game: 20 times in 20 files

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

onClick = notification_util.makeDefaultOnClick({notificationParams.entity}),

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

onClick = notification_util.makeDefaultOnClick({notificationParams.entity}),

base/content/game_mechanics/game_mechanics/company/company_notification_prospection.script.tl:88

onClick = notification_util.makeDefaultOnClick({notificationParams.resultEntity, notificationParams.townEntity}),

base/content/game_mechanics/game_mechanics/company/company_notification_greenify.script.tl:35

onClick = notification_util.makeDefaultOnClick({notificationParams.constructionEntity}),

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

onClick = notification_util.makeDefaultOnClick({notificationParams.townEntity}),

base/content/game_mechanics/game_mechanics/towns/town_notification.script.tl:27

onClick = notification_util.makeDefaultOnClick({notificationParams.townEntity}),

… and 14 more files.