Messaging in TypeScript

TypeScript components can both send and receive messages. The way messages can be sent, posted and received, and how messages are routed is identical to the behavior on the C++ side. Please read the chapter about messaging to familiarize yourself with the general concepts.

The main difference in TypeScript is, that messages that have been declared in C++ can be sent and received in TypeScript, but messages that have been declared in TypeScript can only be sent and received by TypeScript code.

Sending Messages

You can either send a message directly to a specific component (through pl.Component) or to a game object hierarchy (through pl.GameObject). Contrary to the C++ API, there are no functions on pl.World to send messages.

The SendMessage() functions on pl.Component and pl.GameObject take an additional boolean parameter expectResultData. If this is set to true, that means that the sender of the message expects the receiver(s) to write back result data into the sent message, and intends to read those results afterwards. If it is set to false, the message sender does either not expect result data in the message, or doesn't intend to read it. This is an optimization, if you need any result data, set the parameter to true, which means additional work is necessary to synchronize the message back to the caller. Otherwise keep this set to the default value (false).

Sending Event Messages

TypeScript components can raise event messages on themselves through pl.TypescriptComponent.BroadcastEvent().

Handling Messages

To handle messages of a specific type, a component needs a function that takes that message type as its only parameter, and it must register that function as a message handler:

static RegisterMessageHandlers()
{
    pl.TypescriptComponent.RegisterMessageHandler(pl.MsgSetColor, "OnMsgSetColor");
}

OnMsgSetColor(msg: pl.MsgSetColor): void
{
    pl.Log.Info("MsgSetColor: " + msg.Color.r + ", " + msg.Color.g + ", " + msg.Color.b + ", " + msg.Color.a);
}

The static function RegisterMessageHandlers() is the only place where your code may call pl.TypescriptComponent.RegisterMessageHandler(). It is an error to call this from anywhere else.

Declaring a Message in TypeScript

You declare a custom message in TypeScript by extending pl.Message:

export class MsgShowText extends pl.Message {

    PL_DECLARE_MESSAGE_TYPE;
    
    text: string;
}

If you need to send a message from one component and handle it in other component types, you should put the message declaration into a separate .ts file and import that file from both component files. See Importing Files (require) for details.

2.0 Help