Zum Inhalt

notifications

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

Hinweise

Records des Benachrichtigungssystems, der Zustand seines Game-Scripts und die Event-Parameter zum Hinzufügen, Ausblenden und Ignorieren von Benachrichtigungen.

Globale Namen

Typen

Name Definition Beschreibung
GameContext hier deklariert, definiert in GameContext Gemeinsamer Kontext der GUI im Spiel. Enthält Referenzen auf die Haupt-Renderer-Komponente, den Fenster-Container und den Werkzeug-Stack, dazu Missionsfilter, deaktivierte Funktionen und einige gemeinsame Zustände.

NotificationGuiData

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

global record NotificationGuiData

Hinweise

Rückgabewert von useDataState eines Benachrichtigungstyps. Pop-up, Protokoll, Infofenster und HUD zeigen diese Daten an.

Felder

Name Typ Beschreibung
title string Titel der Benachrichtigung.
description string Text der Benachrichtigung.
icon string Pfad des Icon-Bildes, z. B. "::/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} Mehrere Fortschrittsbalken. Ist progress gesetzt, hat es Vorrang.

Funktionen

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

optional

Rückgabe boolean

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

optional

Rückgabe boolean

NotificationGuiData.Type

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

enum Type

Hinweise

GUI-Kategorie eines Benachrichtigungstyps, gesetzt mit guiType in seiner .res-Datei. Sie bestimmt die Farbe und die Filtergruppe im Benachrichtigungsprotokoll.

Im Basisspiel verwendet: 20-mal in 7 Dateien

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
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/notifications.script.tl:762
for __, guiType in ipairs((param as table).ignoredGuiTypes as {NotificationGuiData.Type}) do
base/content/game_mechanics/game_mechanics/notifications/types/notification_react_util.tl:12
local type2class <total>: {NotificationGuiData.Type:string} = {
base/content/gui/gui/entity_window/entity_window_util.tl:2072
local type2class <total> : {NotificationGuiData.Type : string} = {
… und 1 weitere Dateien.

Wert Beschreibung
"Info" Neuigkeiten, z. B. neue Fahrzeuge oder Konstruktionen, eine gegründete Industrie, ein neuer Güterbedarf.
"Caution" Warnungen, z. B. eine überfüllte Station, eine schließende Industrie, ein Fahrzeug in schlechtem Zustand.
"Problem" Probleme, z. B. mit Linien, Stationen, Fahrzeugen oder der Anbindung von Städten.
"Opportunity" Subventionen (verfügbar, laufend, aktiv, gescheitert).
"Achievement" Erfolge, z. B. ein neuer Unternehmensrang, Stadtbenachrichtigungen, erledigte Missionsaufgaben, Wahrzeichen.
"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

Hinweise

Optionaler Zustand einer Opportunity-Benachrichtigung. Er ändert das Icon und den Stil des Fortschrittsbalkens.

Im Basisspiel verwendet: 1-mal in 1 Datei

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

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

Wert Beschreibung
"Pending" Die Subvention ist vorgeschlagen und noch nicht gestartet.
"Failed" Die Subvention ist gescheitert.

NotificationGuiData.Progress

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

record Progress

Hinweise

Ein Fortschrittsbalken in der Benachrichtigung.

Im Basisspiel verwendet: 5-mal in 4 Dateien

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/industry_close.script.tl:17
progress : NotificationGuiData.Progress
base/content/game_mechanics/game_mechanics/notifications/types/subvention_notification.script.tl:16
progresses : {NotificationGuiData.Progress}
base/content/landmarks/landmarks_notification.script.tl:12
progress : NotificationGuiData.Progress

Felder

Name Typ Beschreibung
percentage number Fortschritt von 0 bis 1.
text string Beschriftung des Balkens. Fehlt sie, zeigt die GUI die Restzeit aus remainingDurationMs.
remainingDurationMs number optional

NotificationSimType

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

global record NotificationSimType<T>

Hinweise

Sim-Update-Skript eines Benachrichtigungstyps. Die .res-Datei des Typs verweist mit simUpdateScript darauf (z. B. "::/game_mechanics/notifications/types/overcrowding.sim.script@updateData").

Details

Das Benachrichtigungs-Game-Script ruft updateData auf, wenn eine Benachrichtigung hinzukommt, und danach für jede Benachrichtigung etwa jeden 30. Tick. Kopiere hier Daten, die die GUI später nicht mehr lesen kann, etwa den Namen einer Entität, die entfernt werden könnte.

Beispiel

-- Basisspiel, 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

Funktionen

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

Hinweise

Berechnet die simParams der Benachrichtigung.

Parameter Typ Beschreibung
#1 T Die params der Benachrichtigung.
#2 any Die bisherigen simParams (beim ersten Aufruf eine leere Tabelle).

Rückgabe any: Die neuen simParams.

NotificationType

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

global record NotificationType<T>

Hinweise

GUI-Skript eines Benachrichtigungstyps. Das Skript, das Notification.type nennt, gibt es zurück.

Beispiel

-- Basisspiel, notifications/types/overcrowding.script.tl (gekürzt)
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

Funktionen

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

Rückgabe NotificationGuiData

Notification

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

global record Notification

Hinweise

Eine Benachrichtigung, wie sie mit dem Script-Event Notifications/add gesendet und in NotificationsState gespeichert wird.

Details

type nennt das Skript eines Benachrichtigungstyps. Die .res-Datei mit demselben Basisnamen (type = "notification") enthält guiType, label, simUpdateScript und initiallyIgnoredType. Das Skript selbst gibt einen NotificationType zurück, dessen useDataState(params, simParams) den GUI-Text und die Icons erzeugt.

Eine Benachrichtigung läuft ab (und erscheint nicht mehr als Pop-up), wenn autoDismissDuration verstrichen ist oder wenn params.entities eine nicht leere Liste von EntityUtil.EntityAndRevision ist und sich jede dieser Entitäten geändert hat oder nicht mehr existiert.

Solange der Benachrichtigungszustand pausiert ist, werden add-Events verworfen. Benachrichtigungen eines vollständig ignorierten Typs werden gar nicht erst gespeichert (siehe NotificationsState.Ignored).

Beispiel

-- 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,
}))

Felder

Name Typ Beschreibung
type string Name des Skripts des Benachrichtigungstyps, z. B. "::/game_mechanics/notifications/types/subvention.script" (der Ressourcenpfad mit .script statt .res).
params table Typspezifische Parameter. Sie gehen an useDataState des Typs und an sein Sim-Update-Skript. Steht in params.entities eine Liste von Entitäten, läuft die Benachrichtigung ab, sobald sich alle davon geändert haben.
notificationId integer Id der Benachrichtigung. Sie wird nicht im Zustand gespeichert (die Id ist der Schlüssel in NotificationsState.notifications). Die Funktion aus NotificationReactUtil.createNotificationCacheAccessFn trägt sie ein.
autoDismissDuration integer NOTE: THIS IS NOT THE SAME AS "dismiss", this is basically a "hide" after a certain time
simParams any Daten, die das simUpdateScript des Typs auf der Simulationsseite berechnet (zum Beispiel Namen von Entitäten). Sie gehen als zweites Argument an useDataState. addNotification überschreibt sie.

PersistentNotifications

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

global record PersistentNotifications

Hinweise

Parameter des Events Notifications/updatePersistent. Setzt die vollständige Liste der dauerhaften Benachrichtigungen eines Typs.

Details

Vorhandene dauerhafte Benachrichtigungen von type, deren Entitäten und Parameter nicht in der neuen Liste stehen, laufen ab. Neue Einträge kommen hinzu. Eine dauerhafte Benachrichtigung bleibt über die Grenze von 100 Einträgen hinaus in der Historie. Sie erscheint in Infofenstern, im Linien- und Fahrzeug-Manager und als HUD-Icon (wenn ihre GUI-Daten hudIcon bzw. lvmIcon haben).

Beispiel

-- 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))

Felder

Name Typ Beschreibung
entitiesAndParam {EntitiesAndParam} Alle dauerhaften Benachrichtigungen dieses Typs, die jetzt existieren sollen.
type string Skript des Benachrichtigungstyps, wie in Notification.type.
passOnlyParam boolean Bei true wird param zu den params der Benachrichtigung, sonst ist params gleich { entities = ..., param = ... }.

PersistentNotifications.EntitiesAndParam

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

record EntitiesAndParam

Hinweise

Eine dauerhafte Benachrichtigung.

Im Basisspiel verwendet: 1-mal in 1 Datei

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

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

Felder

Name Typ Beschreibung
entities {EntityUtil.EntityAndRevision} Entitäten, an denen die Benachrichtigung hängt. Über sie wird sie zugeordnet, und bei ihnen wird sie angezeigt.
param any Typspezifischer Parameter der Benachrichtigung.

RemovePersistentNotifications

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

global record RemovePersistentNotifications

Hinweise

Parameter des Events Notifications/removePersistent. Lässt die dauerhaften Benachrichtigungen von type ablaufen, deren Entitäten gleich entities sind.

Beispiel

-- 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))

Felder

Name Typ Beschreibung
entities {EntityUtil.EntityAndRevision} Liste der Entitäten, nach der gesucht wird. Sie wird tief mit den gespeicherten Entitäten verglichen.
type string Skript des Benachrichtigungstyps, wie in Notification.type.

DismissNotification

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

global record DismissNotification

Hinweise

Parameter des Events Notifications/dismiss (blendet eine Benachrichtigung in den Pop-ups aus) und des Events enlist (zeigt sie wieder an).

Felder

Name Typ Beschreibung
id integer Id der Benachrichtigung (Schlüssel in NotificationsState.notifications).

NotificationsState

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

global record NotificationsState

Hinweise

Zustand des Game-Scripts ::/game_mechanics/notifications/notifications.gs. Lies ihn mit NotificationUtil.externalGetNotificationsState().

Details

Das Skript verarbeitet diese Events (Id "Notifications"): add (Notification), updatePersistent (PersistentNotifications), removePersistent (RemovePersistentNotifications), dismiss und enlist (DismissNotification), updateIgnoredTypes ({ ignoredTypes = {[type] = true}, ignoredGuiTypes = {...}, ignoreFully = boolean }), pause (boolean) und initialSound ({ notificationId = id }).

Neben den gespeicherten Benachrichtigungen erzeugt es selbst dauerhafte Benachrichtigungen für Probleme mit Linien, Stationen, Städten, Fahrzeugen, Industrien, Subventionen und dem Unternehmen.

Beispiel

-- Basisspiel, mission/mission_sim.script.tl: einige Typen während einer Mission ganz ausblenden
api.cmd.sendCommand(api.cmd.makeScriptingSendEventCmd("", "Notifications", "updateIgnoredTypes", {
    ignoredTypes = newNotificationFilter,
    ignoreFully = true,
}))

Felder

Name Typ Beschreibung
notifications {integer : Entry} Gespeicherte Benachrichtigungen nach Id.
history {integer} Ids der Benachrichtigungen, die älteste zuerst. Beim Hinzufügen wird die Liste auf 100 Einträge gekürzt; dauerhafte Benachrichtigungen bleiben erhalten.
maxId integer Zuletzt vergebene Id. Bei 1.000.000 beginnen die Ids wieder von vorn.
version integer Version des Zustandsaufbaus. Beim Laden eines Spielstands wird sie mit NotificationLegacyUtil.CurrentVersion verglichen.
ignored Ignored Ignorierte Benachrichtigungstypen. Anfangs sind das die Typen mit initiallyIgnoredType = true in ihrer .res-Datei, mit fully = false.
paused boolean Solange das Flag true ist, überspringt das Skript sein Update und verwirft add-Events.
noRoadConnectionUpdateTimestamp integer Spielzeit (ms) der letzten Prüfung auf Stationen ohne Straßenanbindung. Die nächste Prüfung läuft nach 75 * api.util.getDefaultDayDuration().
vehicle2problem {Engine.Entity : VehicleProblem} Fahrzeuge des Spielers, die unterwegs sind, nicht vom Spieler angehalten wurden und Geschwindigkeit 0 haben. Nach 5 Minuten Spielzeit (300.000 ms) bekommen sie die Benachrichtigung „Fahrzeug steckt fest“.
line2problemTimestamp {Engine.Entity : integer} Spielzeit (ms), zu der für jede Linie zuerst ein Problem gesehen wurde. Linien ohne Problem werden entfernt.
stationGroup2overflowResolvedTimestamp {Engine.Entity : integer} Spielzeit (ms), zu der jede Stationsgruppe zuerst ohne Überlauf gesehen wurde. Die Abklingzeit, die den Wert gelesen hat, ist im Basisspiel auskommentiert.
wastedVehicles {Engine.Entity : boolean} Fahrzeuge mit einer Benachrichtigung „Fahrzeugzustand“. Ein Fahrzeug kommt bei einem Wartungszustand von 0,2 oder weniger hinzu und bleibt, bis der Zustand über 0,3 steigt.

NotificationsState.Entry

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

record Entry

Hinweise

Eine gespeicherte Benachrichtigung mit ihrem Anzeigezustand.

Im Basisspiel verwendet: 11-mal in 3 Dateien

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
base/content/game_mechanics/game_mechanics/notifications/notification_util.tl:103
local notificationEntry : NotificationsState.Entry = state.notifications[notificationId]

Felder

Name Typ Beschreibung
timestamp integer Spielzeit (ms), zu der die Benachrichtigung hinzukam.
notification Notification Die Benachrichtigung.
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 Das Pop-up hat seinen Sound schon abgespielt. Das Event initialSound setzt das Flag, damit der Sound nur einmal kommt.

NotificationsState.Ignored

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

record Ignored

Hinweise

Welche Benachrichtigungstypen ignoriert werden und wie. Gesetzt vom Event updateIgnoredTypes und vom Filter im Benachrichtigungsprotokoll.

Im Basisspiel verwendet: 2-mal in 1 Datei

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

ignored : NotificationsState.Ignored

Felder

Name Typ Beschreibung
fully boolean Controls how the notification types in "types" are ignored (types not in the set are unaffected): the filter in the notification log is disabled in this mode, as it controls the case below 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

Hinweise

Daten zu einem Fahrzeug, das stillsteht.

Im Basisspiel verwendet: 1-mal in 1 Datei

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

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

Felder

Name Typ Beschreibung
problemSince integer Spielzeit (ms), seit der das Fahrzeug stillsteht.

NotificationButtonParam

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

global record NotificationButtonParam

Hinweise

Parameter des Recipes NotificationButton (notifications/gui/notification_button.tl). Das ist der Knopf in der Spielleiste, der das Benachrichtigungsprotokoll öffnet und schließt.

Felder

Name Typ Beschreibung
gameCtx GameContext GUI-Kontext des Spiels. Sein Werkzeug-Stack enthält das Protokollfenster.

NotificationLogToolParam

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

global record NotificationLogToolParam is ToolReactUtil.IToolParam

Hinweise

Parameter des Fensters für das Benachrichtigungsprotokoll. Der Benachrichtigungsknopf legt es auf den Werkzeug-Stack.

Felder

Name Typ Beschreibung
gameCtx GameContext GUI-Kontext des Spiels.
initialFilterState FilterState Filtereinstellungen beim Start. Bei nil öffnet sich die Historie ohne Kategoriefilter.

Funktionen

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

Hinweise

Schließt das Protokollfenster.

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

Hinweise

Bekommt die aktuellen Filtereinstellungen, damit das nächste Öffnen sie wiederherstellen kann.

NotificationLogToolParam.FilterState

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

record FilterState

Hinweise

Filtereinstellungen des Protokollfensters. Der Knopf behält sie zwischen zwei Öffnungen.

Im Spiel Historie · Aktiv · AlleIm Code: History · Active · All

Im Basisspiel verwendet: 9-mal in 2 Dateien

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>
base/content/game_mechanics/game_mechanics/notifications/gui/notification_log.tl:350
local filterState : ReactStateT<NotificationLogToolParam.FilterState> = react.useStateLazy(function() : NotificationLogToolParam.FilterState

Felder

Name Typ Beschreibung
category NotificationGuiData.Type GUI-Kategorie, die das Protokoll zeigt. nil zeigt alle.
displayIndex integer 1 = history, 2 = active