Messages

In S2Engine every object into the scene or widget of GUI can comunicate with all the other ones through messages. A message has a name and a content. The content format of a message is the following:

data1^data2^data3^... 

where data1, data2, data3, etc.. are the data to send inside the message, their number, their values and their type depends on the message itself, they could be string,integer,floats,vectors depending on the message you want the object must send/receive.

For example the format of a message that contains informations about the 'hit' of the player could be like that:

• name of the message: Hit
• content data: "EnergyLoss^EnemyType" (for example "5.0^Monster", that means the player has been hitted by a monster and has lost 5.0 energy points)

Messages can be handled and sent by script, othewise objects of certain classes already automatically send/receive messages of various name/format.

Sending messages

There are various types of message an object or widget can send using defined actions:

• SingleCast: The message is sent to only one object identified by its name. The function used to send this message is: SendMessageSingle, see also SendMessageSingleStatic, SendMessageNode.
• MultiCast: The message is sent to a number of objects that belong to a certain class or are inside a certain range or both cases. The function used to send this message is: SendMessageMulti, see also SendMessageMultiPoint, SendMessageMultiStatic .
• BroadCast: The message is sent to all objects. The function used to send this message is: SendMessageBroad.
• GUI: The message is sent to GUI. The function used to send this message is: SendMessageGUI.
• HUD: The message is sent to HUD. The function used to send this message is: SendMessageHUD.
• AI: The message is sent to AI system, the function used to do it is: SendMessageAI.
• SubWidget: The message is sent by a widget to one of its childs. The function used to send this message is: SendMessageSubWidget, see also SendMessageWidget, SendMessageWidgetHUD.
• ParentWidget: The message is sent by a Widget to its parent. The function used to send this message is: SendMessageParentWidget.

Receiving messages

Every Object/widget receive messages inside the Message() entry point function. To handle a message you must call the ReceivedMessage function inside the Message() entry point. This function has a single param that is the message name, it returns true if the message in input is received. The following is an example of message handling:

/* message entry point */
function void message()
{
  /* check if Hit message has been received */
  if(ReceivedMessage("hit"))
  {
     /* Do something */
     /* ... */
  }
}

That means "If message name is 'hit' then perform some action".

To retreive message data you must use the word 'message' followed by simbol '#' followed by the number of the received message datum, starting from 0: You can use message data as an input param to a function. For example:

/* message entry point */
function void message()
{
  /* check if Hit message has been received */
  if(ReceivedMessage("hit"))
  {
     /* declare a float type variable energyLoss */ 
     var float energyLoss;
     
     /* assign energyLoss variable the value of the first datum of 'hit' message content */
     energyLoss = Float(message#0);
  }
}

Attention

NOTE that message#0 is a string, so to assign it to a float type variable we have used the float() casting function.

In our example ("5.0^Monster"), message#0 is 5.0, message#1 is Monster. You can also know the name of the sender object and use it as an input param of an action. The name of the sender is stored inside a variable which value you can retreive calling the keyword sender. For example:

/* message entry point */
function void message()
{
  /* check if Hit message has been received */
  if(ReceivedMessage("hit"))
  {
     /* write into LOG file the name of the message sender */
     LOG(sender);
  }
}

In this example we write the name of the message sender into the LOG file.

Delayed messages

Starting from version 1.03.01 messages can be sent in delayed mode.

/* message entry point */
function void update()
{
  /* Do something */
  /* ... */
   
  /* sending "hide" message to an object called "gun" after 3 seconds (no parameters) */
  SendMessageSingle("gun", "hide", "", 3.0)
}

Exposing messages

S2Engine HD scene editor can send messages to objects. You can tell the editor what messages you want to send to the scripted object, i.e. we say you have exposed (to the editor) the messages. This is very useful to instantly test scripted behaviour of the object when it receive a message. To expose a message you have to use the #message directive at start of your script. In the previous example we have made our object to process the "hit" message, to expose the hit message we write:

/* expose hit message */
#message "hit"

/* message entry point */
function void message()
{
  /* check if Hit message has been received */
  if(ReceivedMessage("hit"))
  {
     /* write into LOG file the name of the message sender */
     LOG(sender);
  }
}

So, when inside the editor, we select the scripted object, press "class" tab button to show object class properties and exposed message list, then we can select the message to send and finally press the send... button. If message has some params (the data in the message content) you can insert them, separated by space character, into the params input box showed in figure.

See also

ClassInspector