Skip to content

engine_react_util

Source: base/tealdef/gui/main/engine_react_util.d.tl

Notes

React hooks that mirror engine data into React state. Each hook re-reads the engine through a getFromEngine callback (every step, on a timer or in a worker thread), updates the state only when the value changed, and most of them also return a commit function that sets the state and sends engine commands.

EngineReactUtil

record global base/tealdef/gui/main/engine_react_util.d.tl:3

global record EngineReactUtil

Load: local engine_react_util = ug_require "/gui/main/engine_react_util.tl"

Notes

React hooks that keep a React state in sync with engine data and send commands to change it.

Details

Hooks must be called from a recipe function, like all React hooks, and always in the same order.

The commit function returned by most hooks has the form commit(newState, cmd?, callback?): it calls onChange(newState, old, true), sets the state, then sends cmd (or the commands built by makeCommand/makeCommands when cmd is nil) with api.cmd.sendCommand. While commands are pending, the engine is not re-read, so the state does not jump back before the command has been applied. The default comparison is table_util.deepEquals.

Functions

useStepStateMulti<StateTypeT, CommandDataT is ICommandData>(getFromEngine : (function(old? : StateTypeT) : StateTypeT), makeCommands? : (function(StateTypeT) : {{Command<CommandDataT>, function(cmdData : CommandDataT, success : boolean, affectedEntities : {{Engine.Entity, Engine.Revision}})}}), stateEqualsFn? : (function(StateTypeT, StateTypeT) : boolean), onChange? : function(now : StateTypeT, old : StateTypeT, commit : boolean), once? : boolean) : ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})) base/tealdef/gui/main/engine_react_util.d.tl:4

Call as engine_react_util.useStepStateMulti

react state, commit fn

Notes

Like useStepState, but makeCommands returns a list of {command, callback} pairs that are all sent on commit.

Returns ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}}))

Used in the base game: 3 times in 2 files

base/content/gui/gui/debug_panel/make_entity_debug_panel.tl:621 

local state, commit = engine_react_util.useStepStateMulti(makeState, makeCommands)
base/content/gui/gui/line_vehicle_mgmt/manager_window.tl:2254 
local deleteState, commitDelete : ReactStateT<integer>, function(integer) = engine_react_util.useStepStateMulti(makeDeleteState, makeDeleteCommands, nil, nil, t

useStepState<StateTypeT, CommandDataT is ICommandData>(getFromEngine : (function(old? : StateTypeT) : StateTypeT), makeCommand? : (function(StateTypeT) : Command<CommandDataT>, (function(CommandDataT, boolean, {{Engine.Entity, Engine.Revision}}))), stateEqualsFn? : (function(typeA : StateTypeT, typeB : StateTypeT) : boolean), onChange? : function(now : StateTypeT, old : StateTypeT, commit : boolean), once? : boolean) : ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})) base/tealdef/gui/main/engine_react_util.d.tl:12

Call as engine_react_util.useStepState

react state, commit fn

Notes

Creates a React state that is re-read from the engine every step and can be committed back with a command.

Parameter Type Description
getFromEngine (function(old? : StateTypeT) : StateTypeT) Reads the current value from the engine; receives the previous value (or nil the first time).
makeCommand? (function(StateTypeT) : Command<CommandDataT>, (function(CommandDataT, boolean, {{Engine.Entity, Engine.Revision}}))) Optional; builds the command (and optionally a result callback as second return value) used by commit when no command is passed to it.
stateEqualsFn? (function(typeA : StateTypeT, typeB : StateTypeT) : boolean) Optional comparison of old and new value; defaults to table_util.deepEquals.
onChange? function(now : StateTypeT, old : StateTypeT, commit : boolean) Optional; called before the state changes, with commit = true when the change comes from the commit function.
once? boolean Optional; when true, the commit function only works while no command has been sent yet (avoids double clicks).

Returns ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})): The React state and the commit function commit(newState, cmd?, callback?).

Used in the base game: 315 times in 82 files

base/content/mission/mission/mission_framework/mission_framework_react.tl:780 

local stepState = engine_react_util.useStepState(function() : {{string : boolean}, {string : boolean}}
base/content/mission/mission/guide_system/guide_system_react.tl:135 
local guideData : ReactStateT<{CombinedGuideData}> = engine_react_util.useStepState(getSortedGuideData)
base/content/gui/gui/music_player/music_player.tl:50 
local musicPlayerState = engine_react_util.useStepState(readMusicPlayerState)
base/content/gui/gui/layers/layer_hud_filter.tl:36 
local hudFilterState = engine_react_util.useStepState(function() : BaseGUISaveData.HUDFilter
base/content/gui/gui/layers/layer_react_util.tl:168 
local reactState = engine_react_util.useStepState(getCurrentState)
base/content/gui/gui/layers/layer_cargo_flow.tl:220 
local hasResidentialCargoNeeds = engine_react_util.useStepState(function() : boolean
… and 76 more files.

useStepStateTimer<StateTypeT>(getFromEngine : (function(old? : StateTypeT) : StateTypeT), interval? : number, stateEqualsFn? : (function(typeA : StateTypeT, typeB : StateTypeT) : boolean)) : ReactStateT<StateTypeT> base/tealdef/gui/main/engine_react_util.d.tl:20

Call as engine_react_util.useStepStateTimer

react state

Notes

Creates a read-only React state that is re-read from the engine at a fixed interval instead of every step.

Parameter Type Description
getFromEngine (function(old? : StateTypeT) : StateTypeT) Reads the current value from the engine; receives the previous value (or nil the first time).
interval? number Optional interval between reads, in seconds; defaults to 0.5.
stateEqualsFn? (function(typeA : StateTypeT, typeB : StateTypeT) : boolean) Optional comparison of old and new value; defaults to table_util.deepEquals.

Returns ReactStateT<StateTypeT>: The React state.

Used in the base game: 124 times in 58 files

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

local state = engine_react_util.useStepStateTimer(makeState)
base/content/mission/mission/notification.script.tl:14 
local state = engine_react_util.useStepStateTimer(makeState)
base/content/gui/gui/layers/layer_react_util.tl:114 
local reactState = engine_react_util.useStepStateTimer(getCurrentState, nil, nil)
base/content/gui/gui/layers/layer_cargo_flow.tl:122 
local state = engine_react_util.useStepStateTimer(makeState)
base/content/gui/gui/layers/layer_public_transport.tl:80 
local state = engine_react_util.useStepStateTimer(function() : State
base/content/gui/gui/layers/layer_cargo.tl:53 
local state = engine_react_util.useStepStateTimer(function() : State
… and 52 more files.

useStepStateTimerWithCommit<StateTypeT, CommandDataT is ICommandData>(getFromEngine : (function(old? : StateTypeT) : StateTypeT), interval? : number, makeCommand? : (function(StateTypeT) : Command<CommandDataT>, (function(CommandDataT, boolean, {{Engine.Entity, Engine.Revision}}))), stateEqualsFn? : (function(typeA : StateTypeT, typeB : StateTypeT) : boolean), onChange? : function(now : StateTypeT, old : StateTypeT, commit : boolean), once? : boolean) : ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})) base/tealdef/gui/main/engine_react_util.d.tl:26

Call as engine_react_util.useStepStateTimerWithCommit

react state, commit fn

Notes

Like useStepStateTimer (re-read at an interval, default 0.5 seconds), but also returns a commit function as in useStepState.

Returns ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}}))

Used in the base game: 7 times in 6 files

base/content/gui/gui/line_vehicle_mgmt/line_manager_panel.tl:768 

local nameState, commitName = engine_react_util.useStepStateTimerWithCommit(makeNameState, 0, makeNameCommand)
base/content/gui/gui/line_vehicle_mgmt/manager_window.tl:2041 
local nameState, commitName : ReactStateT<string>, function(string) = engine_react_util.useStepStateTimerWithCommit(makeNameState, 0, makeNameCommand)
base/content/gui/gui/line_vehicle_mgmt/vehicle_list_react_util.tl:222 
local nameState, commitName = engine_react_util.useStepStateTimerWithCommit(makeNameState, 0, makeNameCommand)
base/content/gui/gui/entity_window/view_manager.tl:201 
local titleState, commitTitle = engine_react_util.useStepStateTimerWithCommit(function() : string
base/content/game_mechanics/game_mechanics/company/company.tl:940 
local playerNameState, commitName = engine_react_util.useStepStateTimerWithCommit(makePlayerNameState, 0, makeNameCommand)
base/content/game_mechanics/game_mechanics/notifications/gui/notification_popups.tl:277 
local guiNotificationsState, commit = engine_react_util.useStepStateTimerWithCommit(makeGuiNotificationsState)

useStepStateParallel<StateTypeT, ParamT, WorkItemResultT, CommandDataT is ICommandData>(useFnName : string, useFnParams : ParamT, finalize : (function(result : WorkItemResultT, useFnParams : ParamT, old? : StateTypeT) : StateTypeT), makeCommand? : (function(StateTypeT) : Command<CommandDataT>, (function(CommandDataT, boolean, {{Engine.Entity, Engine.Revision}}))), stateEqualsFn? : (function(StateTypeT, StateTypeT) : boolean), onChange? : (function(now : StateTypeT, old : StateTypeT, commit : boolean)), once? : boolean) : ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})) base/tealdef/gui/main/engine_react_util.d.tl:36

Call as engine_react_util.useStepStateParallel

make state that will update each step but in another thread. The result is finalize()d in the main thread and the resulting dirty state is applied next frame.

react state, commit fn

Notes

Creates a React state computed each step in a worker thread by a named function, finalized on the main thread.

Parameter Type Description
useFnName string Name of the function to run, as accepted by util.useFn (a script reference such as "::/path/file.script@fnName").
useFnParams ParamT Parameter passed to that function (and to finalize).
finalize (function(result : WorkItemResultT, useFnParams : ParamT, old? : StateTypeT) : StateTypeT) Turns the worker result into the state value on the main thread; receives the result, useFnParams and the previous state.
makeCommand? (function(StateTypeT) : Command<CommandDataT>, (function(CommandDataT, boolean, {{Engine.Entity, Engine.Revision}}))) Optional; builds the command used by the commit function.
stateEqualsFn? (function(StateTypeT, StateTypeT) : boolean) Optional comparison; defaults to table_util.deepEquals.
onChange? (function(now : StateTypeT, old : StateTypeT, commit : boolean)) Optional; called before a committed change.
once? boolean Optional; allow only one commit.

Returns ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<CommandDataT>, callback? : function(cmdData : CommandDataT, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})): The React state and the commit function.

Details

The initial value is computed synchronously on the main thread. Afterwards the function is enqueued with react.enqueueParallel every step while no command is pending.

Used in the base game: 3 times in 2 files

base/content/gui/gui/entity_window/town/town_eow.script.tl:1110 

local dataState = engine_react_util.useStepStateParallel("::/game_mechanics/towns/town_util_parallel.script@town_util_parallel.getTownDistrictCountsState", para
base/content/game_mechanics/game_mechanics/towns/town_react_util.tl:170 
local reactState = engine_react_util.useStepStateParallel(

useStepStateParallelSimple<StateTypeT, ParamT>(useFnName : string, useFnParams : ParamT, stateEqualsFn? : (function(StateTypeT, StateTypeT))) : ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<ICommandData>, callback? : function(cmdData : ICommandData, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}})) base/tealdef/gui/main/engine_react_util.d.tl:47

Call as engine_react_util.useStepStateParallelSimple

make state that will update each step but in another thread. The resulting dirty state is applied next frame.

react state, commit fn

Notes

useStepStateParallel without a finalize step and without a command: the worker result is the state.

Returns ReactStateT<StateTypeT>, function(type : StateTypeT, cmd? : Command<ICommandData>, callback? : function(cmdData : ICommandData, success : boolean, affectedEntites : {{Engine.Entity, Engine.Revision}}))

Used in the base game: 11 times in 2 files

base/content/gui/gui/entity_window/town/town_eow.script.tl:27 

local stepState = engine_react_util.useStepStateParallelSimple("::/game_mechanics/towns/town_util_parallel.script@town_util_parallel.getTownLevelWidgetState", p
base/content/game_mechanics/game_mechanics/towns/town_react_util.tl:264 
local state = engine_react_util.useStepStateParallelSimple("::/game_mechanics/towns/town_util_parallel.script@town_util_parallel.getDeliveriesState", params.ent

useDummyStepState() base/tealdef/gui/main/engine_react_util.d.tl:50

Call as engine_react_util.useDummyStepState

Notes

Calls the same hooks as useStepStateMulti (a ref and a state) without doing anything.

Details

Use it in a branch where the real step-state hook is skipped, so that the order of hook calls in the recipe stays the same between renders.