Messaging API documentation

Version: stable

FUNCTION
msg.url() creates a new URL
msg.url() creates a new URL from a string
msg.url() creates a new URL from separate arguments
msg.post() posts a message to a receiving URL

Functions

msg.url()

msg.url()

This is equivalent to msg.url(nil) or msg.url("#"), which creates an url to the current script component.

PARAMETERS

RETURNS

url url a new URL

EXAMPLES

Create a new URL which will address the current script: 
local my_url = msg.url()
print(my_url) --> url: [current_collection:/my_instance#my_component]

msg.url()

msg.url(urlstring)

The format of the string must be [socket:][path][#fragment], which is similar to a HTTP URL. When addressing instances:

  • socket is the name of a valid world (a collection)
  • path is the id of the instance, which can either be relative the instance of the calling script or global
  • fragment would be the id of the desired component
In addition, the following shorthands are available:
  • "." the current game object
  • "#" the current component

PARAMETERS

urlstring string string to create the url from

RETURNS

url url a new URL

EXAMPLES

local my_url = msg.url("#my_component")
print(my_url) --> url: [current_collection:/my_instance#my_component]

local my_url = msg.url("my_collection:/my_sub_collection/my_instance#my_component")
print(my_url) --> url: [my_collection:/my_sub_collection/my_instance#my_component]

local my_url = msg.url("my_socket:")
print(my_url) --> url: [my_collection:]

msg.url()

msg.url([socket],[path],[fragment])

creates a new URL from separate arguments

PARAMETERS

[socket] string, hash socket of the URL
[path] string, hash path of the URL
[fragment] string, hash fragment of the URL

RETURNS

url url a new URL

EXAMPLES

local my_socket = "main" -- specify by valid name
local my_path = hash("/my_collection/my_gameobject") -- specify as string or hash
local my_fragment = "component" -- specify as string or hash
local my_url = msg.url(my_socket, my_path, my_fragment)

print(my_url) --> url: [main:/my_collection/my_gameobject#component]
print(my_url.socket) --> 786443 (internal numeric value)
print(my_url.path) --> hash: [/my_collection/my_gameobject]
print(my_url.fragment) --> hash: [component]

msg.post()

msg.post(receiver,message_id,[message])

Post a message to a receiving URL. The most common case is to send messages to a component. If the component part of the receiver is omitted, the message is broadcast to all components in the game object. The following receiver shorthands are available:

  • "." the current game object
  • "#" the current component
There is a 2 kilobyte limit to the message parameter table size.

PARAMETERS

receiver string, url, hash The receiver must be a string in URL-format, a URL object or a hashed string.
message_id string, hash The id must be a string or a hashed string.
[message] table, nil a lua table with message parameters to send.

EXAMPLES

Send "enable" to the sprite "my_sprite" in "my_gameobject": 
msg.post("my_gameobject#my_sprite", "enable")
Send a "my_message" to an url with some additional data: 
local params = {my_parameter = "my_value"}
msg.post(my_url, "my_message", params)