Banter Multiplayer State, Users, and Scene Events
The Banter JavaScript SDK exposes connected users through BanterScene and provides several ways to communicate state: public space properties, protected space properties, user properties, and one-shot messages. Scene events let scripts react to users, loading, state changes, browser messages, keyboard input, and voice features.
Register listeners when the scene becomes ready, keep lasting values in space or user properties, and use one-shot messages for transient actions.
- Wait for
unity-loadedbefore creating interactive scene logic. - Listen for user and state events before sending updates.
- Use properties for values that represent state and one-shot messages for individual events.
Read the Local User
The current user is available through scene.localUser. The official UserData reference lists:
iduidnamecolorisLocalprops
The scene also exposes connected users in its users collection.
const user = scene.localUser;
console.log(user.name, user.isLocal, user.props);React to Users Joining and Leaving
Listen for user-joined and user-left:
scene.On("user-joined", (event) => {
const user = event.detail;
console.log(user.name, "joined");
});
scene.On("user-left", (event) => {
const user = event.detail;
console.log(user.name, "left");
});Register these handlers before the system needs to track player membership. A script that starts listening later will only see later events.
Store Shared Space State
Public space properties represent shared values in the space:
scene.SetPublicSpaceProps({
gameScore: "100",
currentRound: "3"
});The official API also exposes:
SetProtectedSpaceProps()for protected propertiesSetUserProps()for properties associated with a user
Listen for space-state-changed to react to updates:
scene.On("space-state-changed", (event) => {
for (const change of event.detail.changes) {
console.log(
change.property,
change.oldValue,
change.newValue
);
}
});Keep property names stable. Changing names casually creates separate state fields rather than updating the value the rest of the system expects.
Send One-Shot Messages
Use scene.OneShot() for a discrete message rather than a stored property:
scene.OneShot({
type: "player-action",
data: { x: 1, y: 2 }
}, true);Receive messages with the one-shot event:
scene.On("one-shot", (event) => {
console.log(event.detail.fromId);
console.log(event.detail.fromAdmin);
console.log(event.detail.data);
});The second argument in the official examples controls whether the message targets all instances. Check the current API reference before depending on cross-instance behaviour.
Scene Loading Events
The official reference distinguishes:
| Event | Meaning |
|---|---|
loaded |
The scene has settled and its objects have been enumerated. |
unity-loaded |
Unity has finished loading and the loading screen is gone. |
Use unity-loaded for code that must not run until the Unity side is ready.
Component and GameObject Events
Components and GameObjects emit their own events. Content-loading components can emit:
loadedprogressunity-linked
GameObjects can emit object-update. Physics objects can emit collision and trigger events when the required collider event component is present.
Attach an Object to a User
UserData.Attach() can attach a GameObject to documented body locations including the head, hands, feet, chest, and back:
scene.localUser.Attach(
badgeObject,
BS.AttachmentType.Chest
);Use the AttachmentType enum from the current API reference rather than typing body-location strings.
Common Questions
Should this value be a space property or a one-shot message?
Use a space or user property when the value describes current state. Use a one-shot message when the action only needs to be delivered as an event.
Why did my script miss a user-joined event?
Register the listener before the interaction system depends on membership changes, and use the scene's current users collection when you also need users who were already connected.
