gamescript¶

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

Notes

Types for game scripts (*.gs.lua files whose updateScript, postUpdateScript, handleEventScript and guiHandleEventScript entries point to functions as "file.script@functionName"), their persistent state object and the payloads of engine events such as OnCalcTicketPrice.

Example

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

Notes

One element of the param list of the OnCalcTicketPrice event sent by SimEntityAtVehicleSystem for passengers. A handler can return a table {index : multiplier} to scale the ticket price of selected elements (index 0 applies to all).

Fields

Name	Type	Description
`vehicleEntity`	`Engine.Entity`	The vehicle the passenger travels in.
`lineEntity`	`Engine.Entity`	The line the vehicle serves.
`simEntity`	`Engine.Entity`	The simulated person paying the ticket.
`basePrice`	`number`	Ticket price before script multipliers.
`distance`	`number`	Travelled distance the price is based on.

CalcTicketPriceCargoEvent¶

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

global record CalcTicketPriceCargoEvent

Notes

One element of the param list of the OnCalcTicketPrice event sent by TransportVehicleSystem for cargo. A handler can return a table {index : multiplier} to scale the price of selected elements.

Fields

Name	Type	Description
`vehicleEntity`	`Engine.Entity`	The vehicle carrying the cargo.
`lineEntity`	`Engine.Entity`	The line the vehicle serves.
`simEntity`	`Engine.Entity`	The simulated cargo item.
`stockListEntity`	`Engine.Entity`	Stock list the cargo comes from (the base game's delivery subsidies match it against an industry's stock list).
`basePrice`	`number`	Price before script multipliers.
`distance`	`number`	Travelled distance the price is based on.

StartedLineUsage¶

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

global record StartedLineUsage

Notes

Payload of the OnStartedLineUsage event sent by SimPersonSystem when persons start a trip on a line.

Fields

Name	Type	Description
`entities`	`{{Engine.Entity, Engine.Entity}}`	List of pairs; the first element of each pair is the sim person entity.

ArriveAtStop¶

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

global record ArriveAtStop

Notes

Payload of a vehicle-arrives-at-stop event.

Fields

Name	Type	Description
`vehicleEntity`	`Engine.Entity`	The arriving vehicle.
`lineEntity`	`Engine.Entity`	The vehicle's line.
`stopIndex`	`integer`	Index of the stop the vehicle arrived at.
`lastStopIndex`	`integer`

EventData¶

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

global record EventData<T, U>

Notes

Generic pair of an event parameter param and the handler's result.

Fields

Name	Type	Description
`param`	`T`	The event parameter.
`result`	`U`	The handler's result.

GameScriptState¶

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

global record GameScriptState<T>

Notes

Persistent state object of a game script, passed to update, postUpdate and handleEvent. The state table is saved with the game; change it by reading with get, modifying and writing back with set.

Functions

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

Call as gameScriptState:get(…) (method)

Notes

Returns the script's current state table.

Returns T

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

Call as gameScriptState:get_native(…) (method)

Notes

Returns the state as a native Lua table without Teal typing.

Returns NativeLuaTable

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

Call as gameScriptState:set(…) (method)

Notes

Replaces the script's state with the given table.

Example

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

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

Call as gameScriptState:set_native(…) (method)

Notes

Replaces the state with a native Lua table.

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

Call as gameScriptState:hasEventSubscriptions(…) (method)

Notes

True if the script has subscribed to at least one event.

Returns boolean

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

Call as gameScriptState:subscribeToAllEvents(…) (method)

Notes

Makes handleEvent receive every event.

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

Call as gameScriptState:subscribeToNoEvents(…) (method)

Notes

Removes all event subscriptions.

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

Call as gameScriptState:subscribeToEvent(…) (method)

Notes

Subscribes handleEvent to events with the given name.

Details

The base game subscribes in handleEvent when it receives initNewGame or handleLegacy (sent with empty src and id).

Example

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

GameScriptStateReadOnly¶

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

global record GameScriptStateReadOnly<T>

Notes

Read-only view of a game script's state, given to the GUI functions.

Functions

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

Call as gameScriptStateReadOnly:get(…) (method)

Notes

Returns the script's current state table.

Returns T

GameScript¶

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

global record GameScript<T>

Notes

The functions a game script file exports; *.gs.lua names them as "file.script@functionName".

Functions

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

Notes

Called regularly by the game script system.

Parameter	Type	Description
`userParams`	`table`	User parameters of the game script.
`state`	`GameScriptState<T>`	The script's persistent state.
`dt`	`number`	Time step of this update.

Returns any: Any value; it is passed to postUpdate as updateResult.

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

Notes

Called after update with its result; the base game sends commands from here (for example building proposals).

Parameter	Type	Description
`userParams`	`table`
`state`	`GameScriptState<T>`
`dt`	`number`
`updateResult`	`any`	The value returned by `update`.

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

Notes

Receives events the script subscribed to.

Parameter	Type	Description
`userParams`	`table`
`state`	`GameScriptState<T>`
`src`	`string`	Source of the event; empty for game lifecycle events such as `initNewGame`.
`id`	`string`	Receiver/system id, e.g. `"TransportVehicleSystem"` or the id used in `api.cmd.makeScriptingSendEventCmd`.
`name`	`string`	Event name, e.g. `"OnCalcTicketPrice"`.
`param`	`any`	Event payload.

Returns any: Event-specific result, e.g. ticket price multipliers for OnCalcTicketPrice or metadata for storeSavegameMetadata.

GameScriptWithGui¶

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

global record GameScriptWithGui<StateT, GuiStateT>

Notes

A game script that also exports GUI-side functions, with separate engine state StateT and GUI state GuiStateT.

Functions

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

Notes

Called regularly by the game script system; the result is passed to postUpdate.

Returns any

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

Notes

Called after update with its result.

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

Notes

Receives events the script subscribed to (see GameScript.handleEvent).

Returns any

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

Notes

GUI-side update; reads the engine state read-only and may write its own GUI state.

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

Notes

GUI-side event handler; reads the engine state read-only and may write its own GUI state.

Returns any