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. The step and timer hooks re-read the engine through a getFromEngine callback; the parallel hooks run a registered function (useFnName) in a worker thread and pass its result through finalize. The hooks update 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" as EngineReactUtil

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: 313 times in 82 files

base/content/game_mechanics/game_mechanics/company/company.tl:679 

local companyState = engine_react_util.useStepState(makeCompanyState)
base/content/game_mechanics/game_mechanics/company/explorations/exploration_plane_entity_window.script.tl:18 
local state = engine_react_util.useStepState(function() : State
base/content/game_mechanics/game_mechanics/emission/pollution_cleanup_facility_hud.script.tl:52 
local state = engine_react_util.useStepState(function() : State
base/content/game_mechanics/game_mechanics/finance/account.tl:18 
local loansEnabledState = engine_react_util.useStepState(makeLoansEnabledState)
base/content/game_mechanics/game_mechanics/finance/finances_assets.tl:216 
local currentGameTimeState = engine_react_util.useStepState(function() : integer
base/content/game_mechanics/game_mechanics/finance/finances_cargo_lifetime.tl:59 
local millisPerDayState = engine_react_util.useStepState(makeMillisPerDayState)
… 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/game_mechanics/game_mechanics/company/company_notification_greenify.script.tl:15 

local state = engine_react_util.useStepStateTimer(makeState)
base/content/game_mechanics/game_mechanics/company/company_notification_marketing.script.tl:28 
local progressState = engine_react_util.useStepStateTimer(makeProgressState)
base/content/game_mechanics/game_mechanics/company/company_notification_prospection.script.tl:14 
local progressState = engine_react_util.useStepStateTimer(function() : number
base/content/game_mechanics/game_mechanics/finance/finances_table.tl:578 
local tableState = engine_react_util.useStepStateTimer(makeTableState, nil, isTableEqual)
base/content/game_mechanics/game_mechanics/notifications/types/cargo_rtc_warning.script.tl:26 
local state = engine_react_util.useStepStateTimer(makeState)
base/content/game_mechanics/game_mechanics/notifications/types/industry_close.script.tl:51 
local state = engine_react_util.useStepStateTimer(makeState)
… 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/game_mechanics/game_mechanics/company/company.tl:943 

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)
base/content/gui/gui/entity_window/view_manager.tl:201 
local titleState, commitTitle = engine_react_util.useStepStateTimerWithCommit(function() : string
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)

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/game_mechanics/game_mechanics/towns/town_react_util.tl:170 

local reactState = engine_react_util.useStepStateParallel(
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

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

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

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

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.