msg
Functions for passing messages and constructing URL objects.
Functions
msg.post(2 overloads): void<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>)(receiver: SceneAddress | Url | Hash, message_id: Hash, message?: Record<string | number, unknown>)
msg.url(6 overloads)(): Url(urlstring: SceneAddress | Hash | Url | undefined): Url(socket: string | Hash | undefined, path: string | Hash | undefined, fragment: string | Hash | undefined): Url<M extends object>(): ReceiverUrl<M><M extends object>(urlstring: SceneAddress | Hash | Url | undefined): ReceiverUrl<M><M extends object>(socket: string | Hash | undefined, path: string | Hash | undefined, fragment: string | Hash | undefined): ReceiverUrl<M>
msg.post(2 overloads): void
<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.
(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)
(): UrlConstruct 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](urlstring: SceneAddress | Hash | Url | undefined): UrlThe format of the string must be
[socket:][path][#fragment], which is similar to a HTTP URL. When addressing instances:socketis the name of a valid world (a collection)pathis the id of the instance, which can either be relative the instance of the calling script or globalfragmentwould 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
(socket: string | Hash | undefined, path: string | Hash | undefined, fragment: string | Hash | undefined): Urlcreates 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 URLpath:string | Hash | undefined— path of the URLfragment:string | Hash | undefined— fragment of the URL
<M extends object>(): ReceiverUrl<M>This is equivalent to
msg.url(nil)ormsg.url("#"), which creates an url to the current script component.<M extends object>(urlstring: SceneAddress | Hash | Url | undefined): ReceiverUrl<M>Same description as form 2.
Parameters
urlstring:string— string to create the url from
<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 URLpath:string | Hash | undefined— path of the URLfragment:string | Hash | undefined— fragment of the URL
Returns
url:Url— a new URL