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 a subject parameter. The subject designates the entity that the signal will occur on. The subject 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 subject (recommended)
owner.Celebrate // or explicit subject

PayRespects("F") // implicit subject (recommended)
owner.PayRespects("F") // or explicit subject

Listen for a signal using await.

await Celebrate // implicit subject (recommended)
await owner.Celebrate // or explicit subject

let respects = await PayRespects // implicit subject (recommended)
let respects = await owner.PayRespects // or explicit subject

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!"
}