Messages
The second communication mechanism that Game Maker supports is the sending and receiving of messages. A player can send messages to one or all other players. Players can see whether messages have arrived and take action accordingly. Messages can be sent in a guaranteed mode in which you are sure they arrive (but this can be slow) or in a non-guaranteed mode, which is faster.The following messaging routines exist:
mplay_message_send(player,id,val) sends a message to the indicated player (either an identifier or a name; use 0 to send the message to all players). id is an integer message identifier and val is the value (either a real or a string). The message is sent in non-guaranteed mode. If val contains a string the maximal string length allowed is 30000 characters.
mplay_message_send_guaranteed(player,id,val) sends a message to the indicated player (either an identifier or a name; use 0 to send the message to all players). id is an integer message identifier and val is the value (either a real or a string). This is a guaranteed send. If val contains a string the maximal string length allowed is 30000 characters.
mplay_message_receive(player) receives the next message from the message queue that came from the indicated player (either an identifier or a name). Use 0 for messages from any player. The routine returns whether there was indeed a new message. If so you can use the following routines to get its contents:
mplay_message_id() Returns the identifier of the last received message.
mplay_message_value() Returns the value of the last received message.
mplay_message_player() Returns the player who sent the last received message.
mplay_message_name() Returns the name of the player who sent the last received message.
mplay_message_count(player) Returns the number of messages left in the queue from the player (use 0 to count all message).
mplay_message_clear(player) Removes all messages left in the queue from the player (use 0 to remove all message).
A few remarks are pertinent here. First of all, if you want to send a message to a particular player only, you will need to know the player's unique id. As indicated earlier you can obtain this with the function mplay_player_id(). This player identifier is also used when receiving messages from a particular player. Alternatively, you can give the name of the player as a string. If multiple players have the same name, only the first will get the message.
Secondly, you might wonder why each message has an integer identifier. The reason is that this helps your application to send different types of messages. The receiver can check the type of message using the id and take appropriate actions. (Because messages are not guaranteed to arrive, sending id and value in different messages would cause serious problems.)