From 4e9b7f891c7c7b1811faccbdffd752ff88437d05 Mon Sep 17 00:00:00 2001 From: Accipiter Nisus Date: Thu, 25 Sep 2025 12:14:22 +0200 Subject: [PATCH 1/2] GH-29: Added script.broadcast. --- docs/documentation.md | 44 ++++++++++++++++++++++++++++++++------- lib/env.ts | 3 +++ lib/host.ts | 36 +++++++++++++++++++++++++------- lib/types/host/index.d.ts | 33 ++++++++++++++++++++++------- 4 files changed, 95 insertions(+), 21 deletions(-) diff --git a/docs/documentation.md b/docs/documentation.md index e593f4d..b2ff3c5 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -509,6 +509,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 +3576,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 +3648,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 +3712,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..18b81c8 100644 --- a/lib/host.ts +++ b/lib/host.ts @@ -1585,14 +1585,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 +1666,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 +1691,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..da813e4 100644 --- a/lib/types/host/index.d.ts +++ b/lib/types/host/index.d.ts @@ -1128,14 +1128,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 +1194,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 +1216,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. * From c6eb8da111d3cf96c16aebc9ff17f502915568d4 Mon Sep 17 00:00:00 2001 From: Accipiter Nisus Date: Thu, 25 Sep 2025 15:01:40 +0200 Subject: [PATCH 2/2] GH-29: Remove onResponse documentation. Updated index.ts to match documentation.md. --- docs/documentation.md | 33 ++------------------- lib/host.ts | 32 ++------------------ lib/types/host/index.d.ts | 32 ++------------------ scripts/index.ts | 62 ++++++++++++++++++++++++++++++++------- 4 files changed, 58 insertions(+), 101 deletions(-) diff --git a/docs/documentation.md b/docs/documentation.md index b2ff3c5..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) diff --git a/lib/host.ts b/lib/host.ts index 18b81c8..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 */ diff --git a/lib/types/host/index.d.ts b/lib/types/host/index.d.ts index da813e4..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. */ 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 +}