A value that can notify listeners when it changes.
A signal lets a script react to changes without polling every frame. You can
read the current value, listen for changes, and combine signals with &, |
and ~.
Setting a signal to its current value does nothing: listeners do not run, and signals derived from it do not update. This keeps combined signals cheap to listen to. A combined signal fires only when its own result changes, not every time one of its inputs changes.
A derived signal is read like any other signal, so one expression can provide both the current result and change notifications.
Signals should carry numbers, strings or booleans, not handles. Handles are created fresh on each read, so two reads of the same handle do not compare equal and would make the signal report a change every frame. When a signal represents an engine-owned object, it carries the object's numeric id; listeners can then read the handle when they need it.
Signals stay idle until something uses them: a polled signal starts reading only when it is created.
trx.signal.tick (trx.signal.Signal). A signal that increments on every engine tick, regardless of what is on screen.
Anything listening to it runs every tick.
Use this when a script needs to poll state that has no dedicated signal, such as Lara's current position. A dedicated signal is cheaper when one exists, because this one wakes listeners even when the state they care about has not changed. (read-only)
A value that notifies listeners when it changes.
Operators:
signal & signal. Both signals are true. Fires when the result changes.~signal. The signal is not true: ~trx.cutscenes.signals.is_playing.signal | signal. Either signal is true. Fires when the result changes.Methods:
signal:above(amount)
Whether the signal holds more than this number.
Parameters:
Returns: trx.signal.Signal. The derived signal.
signal:eq(value)
Whether the signal holds this value.
Parameters:
Returns: trx.signal.Signal. The derived signal.
signal:get()
The value the signal holds now.
Returns: any. What it holds.
signal:map(fn)
Creates a signal by applying a function to this signal's value.
Use this for derived values that are not simple boolean combinations, such as a bar fill amount or resolved key text.
Parameters:
Returns: trx.signal.Signal. The derived signal.
signal:on(fn)
Calls the handler with the new value whenever the signal changes. Attaching a listener does not call it immediately; read the signal directly when you need its current value.
Parameters:
Returns: trx.signal.Listener. The listener handle used to detach later.
signal:set(value)
Sets the signal's value. Setting the current value again does nothing, so repeated writes are cheap.
Parameters:
Returns: boolean. Whether the value changed and listeners ran.
signal:stop()
Stops a derived signal from following its sources. It keeps its last value and will not update again. Signals made by level scripts stop when the level ends; global scripts can call this to stop one earlier.
Returns: boolean. Whether the signal was still following any sources.
A signal listener that can be detached later.
Methods:
trx.signal.polled(read)
Creates a signal by reading a value once per tick and notifying listeners only
when that value changes.
Use this for state that has no dedicated engine signal. The read function runs every tick, but listeners run only on changes, so several listeners on one polled signal share one read.
Parameters:
read (function). The function to read each tick. Tables compare by identity, so returning a fresh table every tick reports a change every tick.Returns: trx.signal.Signal. The polled signal.
trx.signal.config(key)
Returns a signal for a config setting.
The signal holds the setting's current value and updates whenever the player or a script changes it. Asking for the same setting twice returns the same signal.
Parameters:
key (string). Dotted setting path, as accepted by trx.config.get.Returns: trx.signal.Signal. The setting's signal.
trx.signal.combine(..., fn)
Creates a signal by applying a function to several source signals.
Pass the signals first and the function last. trx.signal.Signal:map is the
one-signal version. For boolean combinations, &, | and ~ are shorter.
Parameters:
... (trx.signal.Signal). The signals to read, in the order the function takes them.fn (function). The function that computes the derived value.Returns: trx.signal.Signal. The derived signal.
Example:
local fill = trx.signal.combine(
trx.lara.signals.hp,
trx.lara.signals.max_hp,
function(hp, max_hp)
return hp / max_hp
end
)
trx.signal.new(value)
Creates a script-owned signal with an initial value.
Parameters:
Returns: trx.signal.Signal. The new signal.