Signals
A signal
is a way to send a notification from one function to another when something happens.
One function calls the signal to send the notification,
and zero or more other functions listen for the signal using await
.
pub signal owner.Celebrate
pub field owner.NumCelebrations
pub game fn World.Main() {
SpawnEachPlayer owner {
NumCelebrations = 0
Transmission {
P { "Press X to celebrate!" }
}
on ButtonDown(BtnX) {
Celebrate
}
on Celebrate {
NumCelebrations += 1
Transmission {
P { "You celebrated " + NumCelebrations + " times!" }
}
}
}
}
A signal may include values.
Below is an example of a signal that passes a message
and a color
value.
The color
parameter can be taken from context and so is in square brackets.
pub signal owner.PayRespects(message, [color])
pub game fn World.Main() {
use color=#8800ff
SpawnEachPlayer owner {
Transmission {
P { "Press F to pay respects" }
}
on ButtonDown(BtnF) {
PayRespects("F")
}
on PayRespects message color {
Transmission {
P(color=) { "You paid respects: " + message }
}
}
}
}
Declaration
Every signal must have an object parameter.
The object parameter designates the entity that the signal will occur on.
The object parameter can be any identifier beginning with a lowercase letter, or World
to make a global signal.
The signal's name must begin with an uppercase letter.
signal owner.Celebrate
Signals can be declared as public using the pub
keyword,
which allows them to be accessed from all files in the program.
Otherwise, they are private and can only be accessed from within the same file.
If two private signals have the same name but are in different files,
they are not the same signal and will not interfere with each other.
pub signal owner.Celebrate
Like other functions, signals may take a comma-separated parameter list.
This list may include parameters surrounded in square brackets ([
and ]
)
to indicate parameters that will be found implicitly from context
if they are not passed explicitly. See Context for more information.
pub signal owner.PayRespects(message, [color])
Working with signals
Call a signal to send a notification to all listeners.
Celebrate // implicit object (recommended)
owner.Celebrate // or explicit object
PayRespects("F") // implicit object (recommended)
owner.PayRespects("F") // or explicit object
Listen for a signal using await
.
await Celebrate // implicit object (recommended)
await owner.Celebrate // or explicit object
let respects = await PayRespects // implicit object (recommended)
let respects = await owner.PayRespects // or explicit object
Like all other await
functions, it is possible to use with
, on
or once
to handle the signal.
with Celebrate {
Transmission {
P { "You celebrated!" }
}
}
on PayRespects message {
Transmission {
P { "You paid respects: " + message }
}
}
IDs
A signal can be declared with an ID. This means that the signal will only be triggered for listeners with the same ID. This enables code to be more generic.
The ID may be optional, which makes the ID default to null
unless otherwise specified.
pub signal Attacked<Id>
pub symbol PrimaryWeapon
pub symbol SecondaryWeapon
pub fn World.Example() {
on Attacked<PrimaryWeapon> {
Transmission { "Attacked by the primary weapon!" }
}
on Attacked<SecondaryWeapon> {
Transmission { "Attacked by the secondary weapon!" }
}
Attacked<PrimaryWeapon> // Displays "Attacked by the primary weapon!"
}