diff --git a/docs/documentation.md b/docs/documentation.md
index e593f4d..e5c439c 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -12,7 +12,6 @@
[onExitUse](#onexituse)
[onCommand](#oncommand)
[onRequest](#onrequest)
- [onResponse](#onresponse)
[API references](#api-references)
Mucklet scripts are written in AssemblyScript, a strictly typed
@@ -107,8 +106,8 @@ export function onRoomEvent(
onMessage
_onMessage_ is called when another script sends a message to this script,
-using [Script.post](#function-script-post). [Script.listen](#function-script-listen) must have been called
-earlier to start listening to messages, usually in the
+using [Script.post](#function-script-post) or [Script.broadcast](#function-script-broadcast). [Script.listen](#function-script-listen)
+must have been called earlier to start listening to messages, usually in the
[onActivate](#onactivate) function.
Parameters
@@ -262,34 +261,6 @@ export function onRequest(
}
```
-onResponse
-
-_onResponse_ is called when another script sends a response to a request by
-calling [Request.reply](#method-request-reply).
-
-Parameters
-
-* `addr` _(string)_: Address of the script instance receiving the response.
-* `response` _([Response](#class-response))_: Response object.
-
-Examples
-
-```ts
-// Receive a response to an request
-export function onResponse(
- addr: string,
- response: Response,
-): void {
- response obn
- // Parse any data passed as arguments.
- const key = request.ParseData()
- const value = Store.getString(key);
- // Send a response to the request
- request.reply(value)
- }
-}
-```
-
API references
[Type aliases](#type-aliases)
@@ -509,6 +480,7 @@ export function onResponse(
Script namespace
[Script functions](#script-functions)
+ [function Script.broadcast](#function-script-broadcast)
[function Script.cancelPost](#function-script-cancelpost)
[function Script.getChar](#function-script-getchar)
[function Script.listen](#function-script-listen)
@@ -3575,6 +3547,27 @@ Detailed room information.
Script functions
+function Script.broadcast
+
+```ts
+Script.broadcast(topic: string, data: string | null = null): void
+```
+
+Broadcasts a message to all scripts listening to this script. Other room
+scripts in the same room listening to any message will also receive the
+message. The receiving script will get the message through the
+[onMessage](#onmessage) entry point.
+
+To get other scripts to listen for broadcast, see [Script.listen](#function-script-listen).
+
+Parameters
+
+* `topic` (string): Message topic. May be any kind of string.
+* `data` (string | null): Additional data. Must be valid JSON.
+
+
+---
+
function Script.cancelPost
```ts
@@ -3626,14 +3619,15 @@ To get character description or image info use Room.getChar instead.
Script.listen(addrs: Array | null = null): void
```
-Starts listening for posted messages and requests, sent with
-[Script.post](#function-script-post) and [Script.request](#function-script-request), from any of the given
-`addr` addresses. If an address is a non-instance room, it will also
-listen to posted messages from any instance of that room.
+Starts listening for messages and requests, sent with
+[Script.post](#function-script-post), [Script.broadcast](#function-script-broadcast), and
+[Script.request](#function-script-request), from any of the given `addr` addresses. If an
+address is a non-instance room, it will also listen to posted messages
+from any instance of that room.
If no `addr` is provided, the script will listen to posts and requests
from _any_ source, including scripts and bots controlled by other
-players.
+players, and also listen for broadcasts by scripts in the same room.
Posts from the current script does not require listening. A script can
always post to itself.
@@ -3689,8 +3683,15 @@ Script.request(addr: string, topic: string, data: string | null = null): Respons
Sends a request to another script with the address `addr`. The receiving
script will get the request through the [onRequest](#onrequest) entry
-point. Once replied, the requesting script will get the response together
-with provided context through the [onResponse](#onresponse) entry point
+point. The requesting script will wait and block until a response is
+received, or a timeout occurs.
+
+Errors will be returned as part of the response. The script should call
+[Response.isError](#method-response-iserror) to check if an error was returned. In case of
+errors, calling [Response.parseResult](#method-response-parseresult) will cause the script to
+abort. Requests to self, or circular requests (A -> B -> A) will always
+return with an error.
+
To get the address of a room script, use the `roomscript` command. For
more info, type:
diff --git a/lib/env.ts b/lib/env.ts
index 2c31a01..164d79d 100644
--- a/lib/env.ts
+++ b/lib/env.ts
@@ -81,6 +81,9 @@ export declare namespace Script {
@external("env", "script.request")
export function request(addr: string, topic: string, data: string | null): T
+
+ @external("env", "script.broadcast")
+ export function broadcast(topic: string, data: string | null): void
}
export declare namespace Store {
diff --git a/lib/host.ts b/lib/host.ts
index 6320653..d47dc55 100644
--- a/lib/host.ts
+++ b/lib/host.ts
@@ -91,8 +91,8 @@
* ## onMessage
*
* _onMessage_ is called when another script sends a message to this script,
- * using {@link Script.post}. {@link Script.listen} must have been called
- * earlier to start listening to messages, usually in the
+ * using {@link Script.post} or {@link Script.broadcast}. {@link Script.listen}
+ * must have been called earlier to start listening to messages, usually in the
* [onActivate](#onactivate) function.
*
* ### Parameters
@@ -246,34 +246,6 @@
* }
* ```
*
- * ## onResponse
- *
- * _onResponse_ is called when another script sends a response to a request by
- * calling {@link Request.reply}.
- *
- * ### Parameters
- *
- * * `addr` _(string)_: Address of the script instance receiving the response.
- * * `response` _({@link Response})_: Response object.
- *
- * ### Examples
- *
- * ```ts
- * // Receive a response to an request
- * export function onResponse(
- * addr: string,
- * response: Response,
- * ): void {
- * response obn
- * // Parse any data passed as arguments.
- * const key = request.ParseData()
- * const value = Store.getString(key);
- * // Send a response to the request
- * request.reply(value)
- * }
- * }
- * ```
- *
* @packageDocumentation
*/
@@ -1585,14 +1557,15 @@ export namespace Script {
}
/**
- * Starts listening for posted messages and requests, sent with
- * {@link Script.post} and {@link Script.request}, from any of the given
- * `addr` addresses. If an address is a non-instance room, it will also
- * listen to posted messages from any instance of that room.
+ * Starts listening for messages and requests, sent with
+ * {@link Script.post}, {@link Script.broadcast}, and
+ * {@link Script.request}, from any of the given `addr` addresses. If an
+ * address is a non-instance room, it will also listen to posted messages
+ * from any instance of that room.
*
* If no `addr` is provided, the script will listen to posts and requests
* from _any_ source, including scripts and bots controlled by other
- * players.
+ * players, and also listen for broadcasts by scripts in the same room.
*
* Posts from the current script does not require listening. A script can
* always post to itself.
@@ -1665,8 +1638,15 @@ export namespace Script {
/**
* Sends a request to another script with the address `addr`. The receiving
* script will get the request through the [onRequest](#onrequest) entry
- * point. Once replied, the requesting script will get the response together
- * with provided context through the [onResponse](#onresponse) entry point
+ * point. The requesting script will wait and block until a response is
+ * received, or a timeout occurs.
+ *
+ * Errors will be returned as part of the response. The script should call
+ * {@link Response.isError} to check if an error was returned. In case of
+ * errors, calling {@link Response.parseResult} will cause the script to
+ * abort. Requests to self, or circular requests (A -> B -> A) will always
+ * return with an error.
+ *
*
* To get the address of a room script, use the `roomscript` command. For
* more info, type:
@@ -1683,6 +1663,20 @@ export namespace Script {
return script_binding.request(addr, topic, data);
}
+ /**
+ * Broadcasts a message to all scripts listening to this script. Other room
+ * scripts in the same room listening to any message will also receive the
+ * message. The receiving script will get the message through the
+ * [onMessage](#onmessage) entry point.
+ *
+ * To get other scripts to listen for broadcast, see {@link Script.listen}.
+ * @param topic - Message topic. May be any kind of string.
+ * @param data - Additional data. Must be valid JSON.
+ */
+ export function broadcast(topic: string, data: string | null = null): void {
+ script_binding.broadcast(topic, data);
+ }
+
/**
* Gets info on an existing character.
*
diff --git a/lib/types/host/index.d.ts b/lib/types/host/index.d.ts
index 0f0e801..deb82de 100644
--- a/lib/types/host/index.d.ts
+++ b/lib/types/host/index.d.ts
@@ -91,8 +91,8 @@
* ## onMessage
*
* _onMessage_ is called when another script sends a message to this script,
- * using {@link Script.post}. {@link Script.listen} must have been called
- * earlier to start listening to messages, usually in the
+ * using {@link Script.post} or {@link Script.broadcast}. {@link Script.listen}
+ * must have been called earlier to start listening to messages, usually in the
* [onActivate](#onactivate) function.
*
* ### Parameters
@@ -246,34 +246,6 @@
* }
* ```
*
- * ## onResponse
- *
- * _onResponse_ is called when another script sends a response to a request by
- * calling {@link Request.reply}.
- *
- * ### Parameters
- *
- * * `addr` _(string)_: Address of the script instance receiving the response.
- * * `response` _({@link Response})_: Response object.
- *
- * ### Examples
- *
- * ```ts
- * // Receive a response to an request
- * export function onResponse(
- * addr: string,
- * response: Response,
- * ): void {
- * response obn
- * // Parse any data passed as arguments.
- * const key = request.ParseData()
- * const value = Store.getString(key);
- * // Send a response to the request
- * request.reply(value)
- * }
- * }
- * ```
- *
* @packageDocumentation
*/
/** ID for in game entities such as characters, rooms, and areas. */
@@ -1128,14 +1100,15 @@ declare namespace Script {
rp: RPState;
}
/**
- * Starts listening for posted messages and requests, sent with
- * {@link Script.post} and {@link Script.request}, from any of the given
- * `addr` addresses. If an address is a non-instance room, it will also
- * listen to posted messages from any instance of that room.
+ * Starts listening for messages and requests, sent with
+ * {@link Script.post}, {@link Script.broadcast}, and
+ * {@link Script.request}, from any of the given `addr` addresses. If an
+ * address is a non-instance room, it will also listen to posted messages
+ * from any instance of that room.
*
* If no `addr` is provided, the script will listen to posts and requests
* from _any_ source, including scripts and bots controlled by other
- * players.
+ * players, and also listen for broadcasts by scripts in the same room.
*
* Posts from the current script does not require listening. A script can
* always post to itself.
@@ -1193,8 +1166,15 @@ declare namespace Script {
/**
* Sends a request to another script with the address `addr`. The receiving
* script will get the request through the [onRequest](#onrequest) entry
- * point. Once replied, the requesting script will get the response together
- * with provided context through the [onResponse](#onresponse) entry point
+ * point. The requesting script will wait and block until a response is
+ * received, or a timeout occurs.
+ *
+ * Errors will be returned as part of the response. The script should call
+ * {@link Response.isError} to check if an error was returned. In case of
+ * errors, calling {@link Response.parseResult} will cause the script to
+ * abort. Requests to self, or circular requests (A -> B -> A) will always
+ * return with an error.
+ *
*
* To get the address of a room script, use the `roomscript` command. For
* more info, type:
@@ -1208,6 +1188,17 @@ declare namespace Script {
* @returns Response to the request.
*/
function request(addr: string, topic: string, data?: string | null): Response;
+ /**
+ * Broadcasts a message to all scripts listening to this script. Other room
+ * scripts in the same room listening to any message will also receive the
+ * message. The receiving script will get the message through the
+ * [onMessage](#onmessage) entry point.
+ *
+ * To get other scripts to listen for broadcast, see {@link Script.listen}.
+ * @param topic - Message topic. May be any kind of string.
+ * @param data - Additional data. Must be valid JSON.
+ */
+ function broadcast(topic: string, data?: string | null): void;
/**
* Gets info on an existing character.
*
diff --git a/scripts/index.ts b/scripts/index.ts
index 2fffd54..23355f1 100644
--- a/scripts/index.ts
+++ b/scripts/index.ts
@@ -3,12 +3,12 @@
/**
* onActivate is called each time a script is activated or updated. It is
- * primarily used to call `Room.listen` or `Script.listen`, to have the script
- * listening for events or messages.
+ * primarily used to call `Script.listen`, `Room.listen`, or `Room.addCommand`,
+ * to have the script listening for events, messages, or commands.
*
- * When a script is updated, previous listeners (e.g. `Room.listen` or
- * `Script.listen`) or scheduled posts (`Script.post` with delay), will be
- * removed, and `onActivate()` will be called again on the new script version.
+ * When a script is updated, previous listeners, (e.g. `Room.listen`), commands
+ * (`Room.addCommand`), or scheduled posts (`Script.post` with delay), will be
+ * removed, and `onActivate` will be called again on the new script version.
*
* Not required. Can be remove if not used.
*/
@@ -19,8 +19,8 @@ export function onActivate(): void {
/**
* onRoomEvent is called when an event occurs in the room, such as a 'say',
- * 'arrive', or 'sleep'. It requires that `Room.listen()` has been called
- * earlier, usually in the `onActivate()` function.
+ * 'arrive', or 'sleep'. `Room.listen` must have been called earlier to start
+ * listening to room events, usually in the `onActivate()` function.
*
* Not required. Can be remove if not used.
*
@@ -47,12 +47,23 @@ export function onRoomEvent(
}
/**
- * onMessage is called when another script sends a message to this script, using
- * `Script.post()`. It requires that `Script.listen()` has been called earlier,
- * usually in the `onActivate()` function.
+ * onMessage is called when another script sends a message to this script,
+ * using `Script.post` or `Script.broadcast`. `Script.listen`
+ * must have been called earlier to start listening to messages, usually in the
+ * `onActivate()` function.
*
* Not required. Can be remove if not used.
*
+ * @example
+ * Receive a message from another script to change room profile:
+ * ```
+ * export function onMessage(addr: string, topic: string, data: string | null, sender: string): void {
+ * if (topic == "changeProfile") {
+ * Room.setProfile(JSON.parse(data))
+ * }
+ * }
+ * ```
+ *
* @param addr - Address of this script instance receiving the message.
* @param topic - Topic of the message. Determined by the sender.
* @param data - JSON encoded data of the message or null. Determined by the sender.
@@ -166,3 +177,34 @@ export function onCommand(
): void {
// Handle the command
}
+
+/**
+ * onRequest is called when another script sends a request to this script, using
+ * `Script.request`. `Script.listen` must have been called earlier to start
+ * listening to requests, usually in the `onActivate()` function.
+ *
+ * Not required. Can be remove if not used.
+ *
+ * @example
+ * Receive a request from another script and send a response:
+ * ```
+ * export function onRequest(addr: string, request: Request): void {
+ * if (request.topic == "getValue") {
+ * // Parse any data passed as arguments.
+ * const key = request.parseData()
+ * const value = Store.getString(key)
+ * // Send a response to the request
+ * request.reply(value)
+ * }
+ * }
+ * ```
+ *
+ * @param addr - Address of this script instance receiving the request.
+ * @param request - Request object.
+ */
+export function onRequest(
+ addr: string,
+ request: Request,
+): void {
+ // Handle the request
+}