gamescript¶

Quelle: base/tealdef/scripts/gamescript.d.tl

Hinweise

Typen für Game-Scripts (*.gs.lua-Dateien, deren Einträge updateScript, postUpdateScript, handleEventScript und guiHandleEventScript auf Funktionen der Form "file.script@functionName" zeigen), für ihren dauerhaft gespeicherten Zustand und für die Nutzdaten von Engine-Events wie OnCalcTicketPrice.

Beispiel

-- base/content/game_mechanics/game_mechanics/company/company.gs.lua
function data()
    return {
        updateScript = { fileName = "company.script@update" },
        postUpdateScript = { fileName = "company.script@postUpdate" },
        handleEventScript = { fileName = "company.script@handleEvent" },
        guiHandleEventScript = { fileName = "company.script@guiHandleEvent" },
    }
end

CalcTicketPriceEvent¶

record global base/tealdef/scripts/gamescript.d.tl:3

global record CalcTicketPriceEvent

Hinweise

Ein Element der Liste param des Events OnCalcTicketPrice, das SimEntityAtVehicleSystem für Passagiere sendet. Ein Handler kann eine Tabelle {index : multiplier} zurückgeben und damit den Ticketpreis einzelner Elemente skalieren (Index 0 gilt für alle).

Felder

Name	Typ	Beschreibung
`vehicleEntity`	`Engine.Entity`	Das Fahrzeug, in dem der Passagier fährt.
`lineEntity`	`Engine.Entity`	Die Linie, die das Fahrzeug bedient.
`simEntity`	`Engine.Entity`	Die simulierte Person, die das Ticket bezahlt.
`basePrice`	`number`	Ticketpreis vor den Multiplikatoren der Skripte.
`distance`	`number`	Zurückgelegte Strecke, nach der sich der Preis richtet.

CalcTicketPriceCargoEvent¶

record global base/tealdef/scripts/gamescript.d.tl:11

global record CalcTicketPriceCargoEvent

Hinweise

Ein Element der Liste param des Events OnCalcTicketPrice, das TransportVehicleSystem für Güter sendet. Ein Handler kann eine Tabelle {index : multiplier} zurückgeben und damit den Preis einzelner Elemente skalieren.

Felder

Name	Typ	Beschreibung
`vehicleEntity`	`Engine.Entity`	Das Fahrzeug, das die Güter transportiert.
`lineEntity`	`Engine.Entity`	Die Linie, die das Fahrzeug bedient.
`simEntity`	`Engine.Entity`	Die simulierte Gütereinheit.
`stockListEntity`	`Engine.Entity`	Lagerliste, aus der die Güter kommen (die Liefer-Subventionen des Basisspiels vergleichen sie mit der Lagerliste einer Industrie).
`basePrice`	`number`	Preis vor den Multiplikatoren der Skripte.
`distance`	`number`	Zurückgelegte Strecke, nach der sich der Preis richtet.

StartedLineUsage¶

record global base/tealdef/scripts/gamescript.d.tl:24

global record StartedLineUsage

Hinweise

Nutzdaten des Events OnStartedLineUsage, das SimPersonSystem sendet, wenn Personen eine Fahrt auf einer Linie beginnen.

Felder

Name	Typ	Beschreibung
`entities`	`{{Engine.Entity, Engine.Entity}}`	Liste von Paaren. Das erste Element jedes Paars ist die Entität der simulierten Person.

ArriveAtStop¶

record global base/tealdef/scripts/gamescript.d.tl:28

global record ArriveAtStop

Hinweise

Nutzdaten des Events, wenn ein Fahrzeug an einer Haltestelle ankommt.

Felder

Name	Typ	Beschreibung
`vehicleEntity`	`Engine.Entity`	Das ankommende Fahrzeug.
`lineEntity`	`Engine.Entity`	Die Linie des Fahrzeugs.
`stopIndex`	`integer`	Index der Haltestelle, an der das Fahrzeug angekommen ist.
`lastStopIndex`	`integer`

EventData¶

record global base/tealdef/scripts/gamescript.d.tl:35

global record EventData<T, U>

Hinweise

Allgemeines Paar aus einem Event-Parameter param und dem Ergebnis result des Handlers.

Felder

Name	Typ	Beschreibung
`param`	`T`	Der Event-Parameter.
`result`	`U`	Das Ergebnis des Handlers.

GameScriptState¶

record global base/tealdef/scripts/gamescript.d.tl:40

global record GameScriptState<T>

Hinweise

Dauerhaft gespeicherter Zustand eines Game-Scripts, den update, postUpdate und handleEvent bekommen. Die Zustandstabelle wird mit dem Spielstand gespeichert. Um sie zu ändern, liest du sie mit get, änderst sie und schreibst sie mit set zurück.

Funktionen

get(GameScriptState<T>) : T base/tealdef/scripts/gamescript.d.tl:41

Aufruf: gameScriptState:get(…) (Methode)

Hinweise

Gibt die aktuelle Zustandstabelle des Skripts zurück.

Rückgabe T

Im Basisspiel verwendet: 78-mal in 26 Dateien

base/content/game_mechanics/game_mechanics/achievements/achievements.script.tl:496

local achievementGuiState : AchievementGuiState = guiState:get()

base/content/game_mechanics/game_mechanics/arrival_tracker/arrivaltracker.script.tl:79

local trackerState : ArrivalTracker.TrackerState = state:get()

base/content/game_mechanics/game_mechanics/celebrations/celebrations.script.tl:296

local celebrationGuiState : CelebrationGuiState = guiState:get()

base/content/game_mechanics/game_mechanics/company/company.script.tl:530

local guiStateData = guiState:get()

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

local scriptState : CompaniesGrowthState = state:get()

base/content/game_mechanics/game_mechanics/company/explorations/exploration_plane.script.tl:284

local explorationPlaneGuiState : ExplorationPlaneGuiState = guiState:get()

… und 20 weitere Dateien.

get_native(GameScriptState<T>) : NativeLuaTable base/tealdef/scripts/gamescript.d.tl:42

Hinweise

Gibt den Zustand als native Lua-Tabelle ohne Teal-Typen zurück.

Rückgabe NativeLuaTable

set(GameScriptState<T>, T) base/tealdef/scripts/gamescript.d.tl:43

Aufruf: gameScriptState:set(…) (Methode)

Hinweise

Ersetzt den Zustand des Skripts durch die übergebene Tabelle.

Beispiel

local scriptState : CompaniesGrowthState = state:get()
applyLevel(scriptState, api.engine.util.getPlayer(), (param as table).level as integer)
state:set(scriptState)

Im Basisspiel verwendet: 87-mal in 27 Dateien

base/content/game_mechanics/game_mechanics/achievements/achievements.script.tl:781

guiState:set(achievementGuiState)

base/content/game_mechanics/game_mechanics/arrival_tracker/arrivaltracker.script.tl:87

state:set(trackerState)

base/content/game_mechanics/game_mechanics/celebrations/celebrations.script.tl:357

guiState:set(celebrationGuiState)

base/content/game_mechanics/game_mechanics/company/company.script.tl:550

guiState:set(guiStateData)

base/content/game_mechanics/game_mechanics/company/company_growth.script.tl:112

state:set(scriptState)

base/content/game_mechanics/game_mechanics/company/explorations/exploration_plane.script.tl:306

guiState:set(explorationPlaneGuiState)

… und 21 weitere Dateien.

set_native(GameScriptState<T>, NativeLuaTable) base/tealdef/scripts/gamescript.d.tl:44

Hinweise

Ersetzt den Zustand durch eine native Lua-Tabelle.

hasEventSubscriptions(GameScriptState<T>) : boolean base/tealdef/scripts/gamescript.d.tl:45

Aufruf: gameScriptState:hasEventSubscriptions(…) (Methode)

Hinweise

True, wenn das Skript mindestens ein Event abonniert hat.

Rückgabe boolean

Im Basisspiel verwendet: 12-mal in 12 Dateien

base/content/game_mechanics/game_mechanics/arrival_tracker/arrivaltracker.script.tl:70

if not state:hasEventSubscriptions() then

base/content/game_mechanics/game_mechanics/emission/emissions.script.tl:30

if not state:hasEventSubscriptions() then

base/content/game_mechanics/game_mechanics/finance/loan.script.tl:38

if not state:hasEventSubscriptions() then

base/content/game_mechanics/game_mechanics/fun_elements/fun_elements.script.tl:61

if not state:hasEventSubscriptions() then

base/content/game_mechanics/game_mechanics/game_time/game_time.script.tl:177

if not state:hasEventSubscriptions() then

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

if not state:hasEventSubscriptions() then

… und 6 weitere Dateien.

subscribeToAllEvents(GameScriptState<T>) base/tealdef/scripts/gamescript.d.tl:46

Aufruf: gameScriptState:subscribeToAllEvents(…) (Methode)

Hinweise

Lässt handleEvent jedes Event empfangen.

Im Basisspiel verwendet: 1-mal in 1 Datei

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

scriptState:subscribeToAllEvents()

subscribeToNoEvents(GameScriptState<T>) base/tealdef/scripts/gamescript.d.tl:47

Hinweise

Entfernt alle Event-Abonnements.

subscribeToEvent(GameScriptState<T>, string) base/tealdef/scripts/gamescript.d.tl:48

Aufruf: gameScriptState:subscribeToEvent(…) (Methode)

Hinweise

Abonniert für handleEvent die Events mit dem angegebenen Namen.

Details

Das Basisspiel abonniert in handleEvent, sobald es initNewGame oder handleLegacy empfängt (beide kommen mit leerem src und id).

Beispiel

-- from base/content/game_mechanics/game_mechanics/company/company_growth.script.tl
if src == "" and id == "" then
    if name == "initNewGame" or name == "handleLegacy" then
        state:subscribeToEvent("applyLevel")
        state:subscribeToEvent("OnCalcTicketPrice")
    end
end

Im Basisspiel verwendet: 42-mal in 15 Dateien

base/content/game_mechanics/game_mechanics/arrival_tracker/arrivaltracker.script.tl:71

state:subscribeToEvent("onDeleteState")

base/content/game_mechanics/game_mechanics/company/company_growth.script.tl:118

state:subscribeToEvent("_debugAddExperience")

base/content/game_mechanics/game_mechanics/emission/emissions.script.tl:31

state:subscribeToEvent("MakeGreen")

base/content/game_mechanics/game_mechanics/finance/loan.script.tl:39

state:subscribeToEvent("Obtain")

base/content/game_mechanics/game_mechanics/fun_elements/fireworks.script.tl:96

state:subscribeToEvent("addFirework")

base/content/game_mechanics/game_mechanics/fun_elements/fun_elements.script.tl:62

state:subscribeToEvent("startMarketingCampaign")

… und 9 weitere Dateien.

GameScriptStateReadOnly¶

record global base/tealdef/scripts/gamescript.d.tl:51

global record GameScriptStateReadOnly<T>

Hinweise

Schreibgeschützte Sicht auf den Zustand eines Game-Scripts, die die GUI-Funktionen bekommen.

Funktionen

get(GameScriptStateReadOnly<T>) : T base/tealdef/scripts/gamescript.d.tl:52

Hinweise

Gibt die aktuelle Zustandstabelle des Skripts zurück.

Rückgabe T

GameScript¶

record global base/tealdef/scripts/gamescript.d.tl:55

global record GameScript<T>

Hinweise

Die Funktionen, die eine Game-Script-Datei exportiert. Die *.gs.lua nennt sie in der Form "file.script@functionName".

Funktionen

update(userParams : table, state : GameScriptState<T>, dt : number) : any base/tealdef/scripts/gamescript.d.tl:56

Hinweise

Wird vom Game-Script-System regelmäßig aufgerufen.

Parameter	Typ	Beschreibung
`userParams`	`table`	Benutzerparameter des Game-Scripts.
`state`	`GameScriptState<T>`	Der dauerhaft gespeicherte Zustand des Skripts.
`dt`	`number`	Zeitschritt dieses Updates.

Rückgabe any: Ein beliebiger Wert. Er geht als updateResult an postUpdate.

postUpdate(userParams : table, state : GameScriptState<T>, dt : number, updateResult : any) base/tealdef/scripts/gamescript.d.tl:57

Hinweise

Wird nach update mit dessen Ergebnis aufgerufen. Das Basisspiel sendet von hier aus Befehle (zum Beispiel Bauvorschläge).

Parameter	Typ	Beschreibung
`userParams`	`table`
`state`	`GameScriptState<T>`
`dt`	`number`
`updateResult`	`any`	Der Rückgabewert von `update`.

handleEvent(userParams : table, state : GameScriptState<T>, src : string, id : string, name : string, param : any) : any base/tealdef/scripts/gamescript.d.tl:58

Hinweise

Empfängt die Events, die das Skript abonniert hat.

Parameter	Typ	Beschreibung
`userParams`	`table`
`state`	`GameScriptState<T>`
`src`	`string`	Quelle des Events. Bei Lebenszyklus-Events des Spiels wie `initNewGame` ist sie leer.
`id`	`string`	ID des Empfängers oder Systems, z. B. `"TransportVehicleSystem"` oder die ID, die in `api.cmd.makeScriptingSendEventCmd` angegeben wurde.
`name`	`string`	Name des Events, z. B. `"OnCalcTicketPrice"`.
`param`	`any`	Nutzdaten des Events.

Rückgabe any: Ein Ergebnis, das vom Event abhängt, z. B. Multiplikatoren für den Ticketpreis bei OnCalcTicketPrice oder Metadaten bei storeSavegameMetadata.

GameScriptWithGui¶

record global base/tealdef/scripts/gamescript.d.tl:61

global record GameScriptWithGui<StateT, GuiStateT>

Hinweise

Ein Game-Script, das auch Funktionen für die GUI-Seite exportiert, mit getrenntem Engine-Zustand StateT und GUI-Zustand GuiStateT.

Funktionen

update(userParams : table, state : GameScriptState<StateT>, dt : number) : any base/tealdef/scripts/gamescript.d.tl:62

Hinweise

Wird vom Game-Script-System regelmäßig aufgerufen. Das Ergebnis geht an postUpdate.

Rückgabe any

postUpdate(userParams : table, state : GameScriptState<StateT>, dt : number, updateResult : any) base/tealdef/scripts/gamescript.d.tl:63

Hinweise

Wird nach update mit dessen Ergebnis aufgerufen.

handleEvent(userParams : table, state : GameScriptState<StateT>, src : string, id : string, name : string, param : any) : any base/tealdef/scripts/gamescript.d.tl:64

Hinweise

Empfängt die Events, die das Skript abonniert hat (siehe GameScript.handleEvent).

Rückgabe any

guiUpdate(userParams : table, state : GameScriptStateReadOnly<StateT>, guiState : GameScriptState<GuiStateT>) base/tealdef/scripts/gamescript.d.tl:66

Hinweise

Update auf der GUI-Seite. Liest den Engine-Zustand schreibgeschützt und darf den eigenen GUI-Zustand schreiben.

guiHandleEvent(userParams : table, state : GameScriptStateReadOnly<StateT>, guiState : GameScriptState<GuiStateT>, src : string, id : string, name : string, param : any) : any base/tealdef/scripts/gamescript.d.tl:67

Hinweise

Event-Handler auf der GUI-Seite. Liest den Engine-Zustand schreibgeschützt und darf den eigenen GUI-Zustand schreiben.

Rückgabe any