Skip to content

Feature/gh 29 script broadcast #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
anisus merged 2 commits into from
Sep 25, 2025
Merged

Feature/gh 29 script broadcast #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e9b7f8
GH-29: Added script.broadcast.
anisus Sep 25, 2025
c6eb8da
GH-29: Remove onResponse documentation. Updated index.ts to match doc…
anisus Sep 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 39 additions & 38 deletions docs/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -107,8 +106,8 @@ export function onRoomEvent(
<h3 id="onmessage">onMessage</h3>

_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.

<h4 id="onmessage-parameters">Parameters</h4>
Expand Down Expand Up @@ -262,34 +261,6 @@ export function onRequest(
}
```

<h3 id="onresponse">onResponse</h3>

_onResponse_ is called when another script sends a response to a request by
calling [Request.reply](#method-request-reply).

<h4 id="onresponse-parameters">Parameters</h4>

* `addr` _(string)_: Address of the script instance receiving the response.
* `response` _([Response](#class-response))_: Response object.

<h4 id="onresponse-examples">Examples</h4>

```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<string>()
const value = Store.getString(key);
// Send a response to the request
request.reply(value)
}
}
```

<h1 id="api-references">API references</h1>

[Type aliases](#type-aliases)
Expand Down Expand Up @@ -509,6 +480,7 @@ export function onResponse(
<h3 id="namespace-script">Script namespace</h3>

[Script functions](#script-functions)
&nbsp;&nbsp;&nbsp;&nbsp;[function Script.broadcast](#function-script-broadcast)
&nbsp;&nbsp;&nbsp;&nbsp;[function Script.cancelPost](#function-script-cancelpost)
&nbsp;&nbsp;&nbsp;&nbsp;[function Script.getChar](#function-script-getchar)
&nbsp;&nbsp;&nbsp;&nbsp;[function Script.listen](#function-script-listen)
Expand Down Expand Up @@ -3575,6 +3547,27 @@ Detailed room information.

<h2 id="script-functions">Script functions</h2>

<h3 id="function-script-broadcast">function Script.broadcast</h3>

```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).

<h4>Parameters</h4>

* `topic` <i>(string)</i>: Message topic. May be any kind of string.
* `data` <i>(string | null)</i>: Additional data. Must be valid JSON.


---

<h3 id="function-script-cancelpost">function Script.cancelPost</h3>

```ts
Expand Down Expand Up @@ -3626,14 +3619,15 @@ To get character description or image info use Room.getChar instead.
Script.listen(addrs: Array<string> | 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.
Expand Down Expand Up @@ -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:
Expand Down
3 changes: 3 additions & 0 deletions lib/env.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,9 @@ export declare namespace Script {

@external("env", "script.request")
export function request<T>(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 {
Expand Down
68 changes: 31 additions & 37 deletions lib/host.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<string>()
* const value = Store.getString(key);
* // Send a response to the request
* request.reply(value)
* }
* }
* ```
*
* @packageDocumentation
*/

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand All @@ -1683,6 +1663,20 @@ export namespace Script {
return script_binding.request<Response>(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.
*
Expand Down
65 changes: 28 additions & 37 deletions lib/types/host/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<string>()
* 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. */
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand All @@ -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.
*
Expand Down
Loading