Defold C

Defold C++

dmGameObject

dmGameSystem

dmGraphics

dmResource

dmScript

Defold Lua

Extension

firebase

Version

Messaging API documentation

Functions for passing messages and constructing URL objects.

Version: alpha

RECORDS
url	Component URL

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

Records

url

A URL identifies a message endpoint in Defold. Its string form is [socket:][path][#fragment]: the socket identifies a collection, the path identifies a game object, and the fragment identifies a component. Missing parts are resolved relative to the script that creates the URL. Create URLs with msg.url. The socket, path, and fragment components are exposed as hash values and can be inspected or replaced individually. URLs are commonly passed to msg.post and to functions that address game objects or components.

FIELDS

`socket`	`hash`	socket component
`path`	`hash`	path component
`fragment`	`hash`	fragment component

EXAMPLES

Create a relative URL for a component on the current game object:

local sprite_url = msg.url("#sprite")
msg.post(sprite_url, "disable")
print(sprite_url.fragment) --> hash: [sprite]

Create an absolute URL by specifying all three components:

local controller_url = msg.url("main:/player#controller")
print(controller_url) --> url: [main:/player#controller]

Functions

msg.post()

msg.post(receiver:string|url|hash, message_id:string|hash, [message:table<any, any>|nil])

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<any, any>` `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)

msg.url()

msg.url()→url:url

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

PARAMETERS

None

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:string)→url:url

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:string|hash], [path:string|hash], [fragment:string|hash])→url:url

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]