Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

msg

Functions for passing messages and constructing URL objects.

Functions

msg.post(2 overloads): void

  1. <R extends SceneAddress | Hash | Url, K extends (keyof ReceiverMessages<R> & string) | MessageId | (string & {})>(receiver: R, message_id: K, message?: K extends BuiltinMessageId ? MessagePayload<K> : K extends keyof ReceiverMessages<R> ? ReceiverMessages<R>[K] : MessagePayload<K>)

    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.

  2. (receiver: SceneAddress | Url | Hash, message_id: Hash, message?: Record<string | number, unknown>)

    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.

Send "enable" to the sprite "my_sprite" in "my_gameobject":

msg.post("my_gameobject#my_sprite", "enable");
msg.post("my_gameobject#my_sprite", "enable")

Send a "my_message" to an url with some additional data:

const my_url = msg.url("my_gameobject#my_script");
const params = { my_parameter: "my_value" };
msg.post(my_url, "my_message", params);
local params = {my_parameter = "my_value"}
msg.post(my_url, "my_message", params)

msg.url(6 overloads)

  1. (): Url

    Construct a URL. A URL is [socket:][path][#fragment].

    // Create a new URL which will address the current script:
    const my_url = msg.url();
    print(my_url); // => url: [current_collection:/my_instance#my_component]
    local my_url = msg.url()
    print(my_url) --> url: [current_collection:/my_instance#my_component]
  2. (urlstring: SceneAddress | Hash | Url | undefined): 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
    const my_url = msg.url("#my_component");
    print(my_url); // => url: [current_collection:/my_instance#my_component]
    
    const my_collection_url = msg.url("my_collection:/my_sub_collection/my_instance#my_component");
    print(my_collection_url); // => url: [my_collection:/my_sub_collection/my_instance#my_component]
    
    const my_socket_url = msg.url("my_socket:");
    print(my_socket_url); // => url: [my_collection:]
    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:]

    Parameters

    • urlstring: string — string to create the url from
  3. (socket: string | Hash | undefined, path: string | Hash | undefined, fragment: string | Hash | undefined): Url

    creates a new URL from separate arguments

    const my_socket = "main"; // specify by valid name
    const my_path = hash("/my_collection/my_gameobject"); // specify as string or hash
    const my_fragment = "component"; // specify as string or hash
    const 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]
    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]

    Parameters

    • socket: string | Hash | undefined — socket of the URL
    • path: string | Hash | undefined — path of the URL
    • fragment: string | Hash | undefined — fragment of the URL
  4. <M extends object>(): ReceiverUrl<M>

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

  5. <M extends object>(urlstring: SceneAddress | Hash | Url | undefined): ReceiverUrl<M>

    Same description as form 2.

    Parameters

    • urlstring: string — string to create the url from
  6. <M extends object>(socket: string | Hash | undefined, path: string | Hash | undefined, fragment: string | Hash | undefined): ReceiverUrl<M>

    Same description as form 3.

    Parameters

    • socket: string | Hash | undefined — socket of the URL
    • path: string | Hash | undefined — path of the URL
    • fragment: string | Hash | undefined — fragment of the URL

Returns

  • url: Url — a new URL

On this page