Skip to main content

createBroadcastReceiver

createBroadcastReceiver lets you keep the client's state in sync with the server's shared state, whose updates are sent by createBroadcaster.

const receiver = createBroadcastReceiver(options);

Reference

createBroadcastReceiver(options)

Call createBroadcastReceiver to create a receiver that can be used to connect your state to the broadcaster on the server.

import { createBroadcastReceiver } from "@rbxts/reflex";

const receiver = createBroadcastReceiver({
start: () => {
remotes.start.fire();
},
});

Once you have the receiver, you need to apply the middleware to your producer and connect dispatch to a remote:

remotes.dispatch.connect((actions) => {
receiver.dispatch(actions);
});

producer.applyMiddleware(receiver.middleware);

createBroadcastReceiver will request the server's shared state when the middleware is applied, and merge it with the client's state. This means that the client's state will not be overwritten, but instead hydrated with the server's state. It is safe to use your producer before the server's state is received.

Broadcasters send shared actions dispatched on the server to the client through a remote, so you need to connect the receiver's dispatch method to run the actions passed to the remote.

On the server, call createBroadcaster to share state and actions with the client.

See more examples below.

Parameters

  • options - An object with options for the broadcast receiver.
    • start - A function that should call broadcaster.start on the server for the local player. Called when the middleware is applied.

Returns

createBroadcastReceiver returns a receiver object with a dispatch method and a middleware property.

caveats

receiver.middleware

Apply the broadcast receiver middleware to call start and initialize the client's root producer with the server's shared state. It's safe to use the producer before this middleware is applied, and order does not matter.

producer.applyMiddleware(receiver.middleware);

receiver.dispatch(actions)

Connect the receiver's dispatch method to a remote to dispatch the actions passed to the remote.

It's important to use this method instead of your own custom dispatch function, as this method also handles hydration and merging of the server's shared state.

remotes.dispatch.connect((actions) => {
receiver.dispatch(actions);
});

Parameters

  • actions - An array of BroadcastAction objects to dispatch.

Returns

receiver.dispatch returns nothing.


Usage

Syncing server state on the client

If you haven't already, see how to send server state to clients to create a basic project setup. The createBroadcaster page is treated as the primary reference for this feature.

Once you have your broadcaster set up, you can use createBroadcastReceiver to initialize the client state with the server's shared state and keep it in sync.

import { createBroadcastReceiver } from "@rbxts/reflex";

const receiver = createBroadcastReceiver({
start: () => {
remotes.start.fire();
},
});

remotes.dispatch.connect((actions) => {
receiver.dispatch(actions);
});

producer.applyMiddleware(receiver.middleware);

This code will call start when the middleware is applied, and merge the server's shared state with the client's state. You should also connect the receiver's dispatch method to the remote, so that the state continues to be kept in sync.

It's thread-safe, so it's safe to apply the middleware at any time, and you can even use your producer before the server's state is received.


Sending server state to clients

To share the server's state with clients, see createBroadcaster.