@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
1,003 lines • 42.7 kB
JavaScript
const defaultNetworkingBackendUrlProvider = "https://urls.needle.tools/default-networking-backend/index";
let networkingServerUrl = "wss://networking-2.needle.tools/socket";
import * as flatbuffers from 'flatbuffers';
import * as schemes from "../engine-schemes/schemes.js";
import { isDevEnvironment } from './debug/index.js';
import { Telemetry } from './engine_license.js';
import { PeerNetworking } from './engine_networking_peer.js';
import { SendQueue } from './engine_networking_types.js';
import { WebsocketTransport } from './engine_networking.transport.websocket.js';
import { isHostedOnGlitch } from './engine_networking_utils.js';
import * as utils from "./engine_utils.js";
/** @internal Symbol used to attach the original callback to unsubscribe functions returned by beginListen/beginListenBinary */
const $originalCallback = Symbol("originalCallback");
export const debugNet = utils.getParam("debugnet") ? true : false;
export const debugOwner = debugNet || utils.getParam("debugowner") ? true : false;
const debugnetBin = utils.getParam("debugnetbin");
/** Events regarding the websocket connection (e.g. when the connection opens) */
export var ConnectionEvents;
(function (ConnectionEvents) {
ConnectionEvents["ConnectionInfo"] = "connection-start-info";
})(ConnectionEvents || (ConnectionEvents = {}));
/** Use to listen to room networking events like joining a networked room
* For example: `this.context.connection.beginListen(RoomEvents.JoinedRoom, () => { })`
* @link https://engine.needle.tools/docs/networking.html#manual-networking
* */
export var RoomEvents;
(function (RoomEvents) {
/** Internal: Sent to the server when attempting to join a room */
RoomEvents["Join"] = "join-room";
/** Internal: Sent to the server when attempting to leave a room */
RoomEvents["Leave"] = "leave-room";
/** Incoming: When the local user has joined a room */
RoomEvents["JoinedRoom"] = "joined-room";
/** Incoming: When the local user has left a room */
RoomEvents["LeftRoom"] = "left-room";
/** Incoming: When a other user has joined the room */
RoomEvents["UserJoinedRoom"] = "user-joined-room";
/** Incoming: When a other user has left the room */
RoomEvents["UserLeftRoom"] = "user-left-room";
/** When a user joins a room, the server sends the entire room state. Afterwards, the server sends the room-state-sent event. */
RoomEvents["RoomStateSent"] = "room-state-sent";
})(RoomEvents || (RoomEvents = {}));
/** Received when listening to `RoomEvents.JoinedRoom` event */
export class JoinedRoomResponse {
room; // room name
viewId;
allowEditing;
inRoom; // connection ids
}
export class LeftRoomResponse {
room; // room name
}
export class UserJoinedOrLeftRoomModel {
userId;
}
/** The Needle Engine networking server supports the concept of ownership that can be requested.
* This enum contains possible outgoing (Request*) and incoming (Response*) events for communicating ownership.
*
* Typically, using the {@link OwnershipModel} class instead of dealing with those events directly is preferred. */
export var OwnershipEvent;
(function (OwnershipEvent) {
OwnershipEvent["RequestHasOwner"] = "request-has-owner";
OwnershipEvent["ResponseHasOwner"] = "response-has-owner";
OwnershipEvent["RequestIsOwner"] = "request-is-owner";
OwnershipEvent["ResponseIsOwner"] = "response-is-owner";
OwnershipEvent["RequestOwnership"] = "request-ownership";
OwnershipEvent["GainedOwnership"] = "gained-ownership";
OwnershipEvent["RemoveOwnership"] = "remove-ownership";
OwnershipEvent["LostOwnership"] = "lost-ownership";
OwnershipEvent["GainedOwnershipBroadcast"] = "gained-ownership-broadcast";
OwnershipEvent["LostOwnershipBroadcast"] = "lost-ownership-broadcast";
})(OwnershipEvent || (OwnershipEvent = {}));
// #region OwnershipModel
/**
* Manages ownership of networked objects or components.
*
* In multiplayer scenarios, ownership determines which client has authority to modify an object.
* The networking server rejects changes from clients that don't own an object. This prevents conflicts
* when multiple users try to manipulate the same object simultaneously.
*
* **Ownership states:**
* - `hasOwnership`: This client owns the object and can modify it
* - `isOwned`: Some client (could be local or remote) owns the object
* - `undefined`: Ownership state is unknown (not yet queried)
*
* **Typical workflow:**
* 1. Request ownership before modifying an object
* 2. Make your changes while you have ownership
* 3. Free ownership when done (or keep it if still interacting)
*
* @example Basic usage
* ```ts
* export class MyComponent extends Behaviour {
* private ownership?: OwnershipModel;
*
* awake() {
* this.ownership = new OwnershipModel(this.context.connection, this.guid);
* }
*
* onClick() {
* // Request ownership before modifying the object
* this.ownership.requestOwnership();
* }
*
* update() {
* if (this.ownership.hasOwnership) {
* // Safe to modify and sync the object
* this.gameObject.position.y += 0.01;
* }
* }
*
* onDisable() {
* // Release ownership when done
* this.ownership.freeOwnership();
* this.ownership.destroy();
* }
* }
* ```
*
* @example Async ownership
* ```ts
* async modifyObject() {
* try {
* await this.ownership.requestOwnershipAsync();
* // Now guaranteed to have ownership
* this.transform.position.x = 5;
* } catch(e) {
* console.log("Failed to gain ownership");
* }
* }
* ```
*
* @see {@link SyncedTransform} for a complete example of ownership in action
* @link https://engine.needle.tools/docs/networking.html
*/
export class OwnershipModel {
/** The unique identifier (GUID) of the object this ownership model manages */
guid;
connection;
/**
* Checks if the local client has ownership of this object.
* @returns `true` if this client owns the object and can modify it, `false` otherwise
*/
get hasOwnership() {
return this._hasOwnership;
}
// TODO: server should just send id to everyone
/**
* Checks if anyone (local or remote client) has ownership of this object.
* @returns `true` if someone owns the object, `false` if no one owns it, `undefined` if unknown
*/
get isOwned() {
return this._isOwned;
}
/**
* Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `isInRoom` property.
* @returns true if connected to the websocket.
*/
get isConnected() {
return this.connection.isConnected;
}
_hasOwnership = false;
_isOwned = undefined;
_gainSubscription;
_lostSubscription;
_hasOwnerResponse;
_pendingOwnershipResolve = null;
constructor(connection, guid) {
this.connection = connection;
this.guid = guid;
this._gainSubscription = this.onGainedOwnership.bind(this);
this._lostSubscription = this.onLostOwnership.bind(this);
connection.beginListen(OwnershipEvent.LostOwnership, this._lostSubscription);
connection.beginListen(OwnershipEvent.GainedOwnershipBroadcast, this._gainSubscription);
this._hasOwnerResponse = this.onHasOwnerResponse.bind(this);
connection.beginListen(OwnershipEvent.ResponseHasOwner, this._hasOwnerResponse);
}
_isWaitingForOwnershipResponseCallback = null;
/**
* Queries the server to update the `isOwned` state.
* Call this to check if anyone currently has ownership.
*/
updateIsOwned() {
this.connection.send(OwnershipEvent.RequestHasOwner, { guid: this.guid });
}
onHasOwnerResponse(res) {
if (res.guid === this.guid) {
this._isOwned = res.value;
}
}
/**
* Requests ownership only if the object is not currently owned by anyone.
* Internally checks ownership state first, then requests ownership if free.
* @returns this OwnershipModel instance for method chaining
*/
requestOwnershipIfNotOwned() {
if (this._isWaitingForOwnershipResponseCallback !== null)
return this;
this._isWaitingForOwnershipResponseCallback = this.waitForHasOwnershipRequestResponse.bind(this);
this.connection.beginListen(OwnershipEvent.ResponseHasOwner, this._isWaitingForOwnershipResponseCallback);
this.connection.send(OwnershipEvent.RequestHasOwner, { guid: this.guid });
return this;
}
waitForHasOwnershipRequestResponse(res) {
if (res.guid === this.guid) {
if (this._isWaitingForOwnershipResponseCallback) {
this.connection.stopListen(OwnershipEvent.ResponseHasOwner, this._isWaitingForOwnershipResponseCallback);
this._isWaitingForOwnershipResponseCallback = null;
}
this._isOwned = res.value;
if (!res.value) {
if (debugOwner)
console.log("request ownership", this.guid);
this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
}
}
}
/**
* Requests ownership and waits asynchronously until ownership is granted or timeout occurs.
* @returns Promise that resolves with this OwnershipModel when ownership is gained
* @throws Rejects with "Timeout" if ownership is not gained within ~1 second
* @example
* ```ts
* const owned = await ownership.requestOwnership();
* if (owned) {
* // Ownership granted, safe to modify object
* }
* ```
*/
/**
* Requests ownership of this object from the networking server.
* Returns a Promise that resolves with `true` when ownership is granted, or `false` on timeout/failure.
* If ownership is already held, resolves immediately with `true`.
* @returns Promise that resolves with `true` if ownership was gained, `false` otherwise
*/
requestOwnership() {
if (this._hasOwnership)
return Promise.resolve(true);
// Cancel any previous pending request
this._pendingOwnershipResolve?.(false);
this._pendingOwnershipResolve = null;
if (debugOwner)
console.log("Request ownership", this.guid);
this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
return new Promise((resolve) => {
this._pendingOwnershipResolve = resolve;
// Timeout after ~2 seconds
setTimeout(() => {
if (this._pendingOwnershipResolve === resolve) {
this._pendingOwnershipResolve = null;
resolve(false);
}
}, 2000);
});
}
/**
* @deprecated Use `requestOwnership()` instead for a more reliable way to gain ownership
*/
async requestOwnershipAsync() {
if (debugOwner)
console.log("Request ownership", this.guid);
this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
return this;
}
/**
* Releases ownership of this object, allowing others to take control.
* Call this when you're done modifying an object to allow other users to interact with it.
* @returns this OwnershipModel instance for method chaining
*/
freeOwnership() {
// TODO: abort "requestOwnershipIfNotOwned"
this.connection.send(OwnershipEvent.RemoveOwnership, { guid: this.guid });
if (this._isWaitingForOwnershipResponseCallback) {
this.connection.stopListen(OwnershipEvent.ResponseHasOwner, this._isWaitingForOwnershipResponseCallback);
this._isWaitingForOwnershipResponseCallback = null;
}
return this;
}
/**
* Cleans up event listeners and resources.
* Call this when the OwnershipModel is no longer needed (e.g., in `onDestroy()`).
*/
destroy() {
this.connection.stopListen(OwnershipEvent.GainedOwnership, this._gainSubscription);
this.connection.stopListen(OwnershipEvent.LostOwnership, this._lostSubscription);
this.connection.stopListen(OwnershipEvent.ResponseHasOwner, this._hasOwnerResponse);
if (this._isWaitingForOwnershipResponseCallback) {
this.connection.stopListen(OwnershipEvent.ResponseHasOwner, this._isWaitingForOwnershipResponseCallback);
this._isWaitingForOwnershipResponseCallback = null;
}
// Clean up pending ownership request
this._pendingOwnershipResolve?.(false);
this._pendingOwnershipResolve = null;
}
onGainedOwnership(res) {
if (res.guid === this.guid) {
this._isOwned = true;
if (this.connection.connectionId === res.owner) {
if (debugOwner)
console.log("GAINED OWNERSHIP", this.guid);
this._hasOwnership = true;
// Resolve pending ownership request
if (this._pendingOwnershipResolve) {
this._pendingOwnershipResolve(true);
this._pendingOwnershipResolve = null;
}
}
else
this._hasOwnership = false;
}
}
onLostOwnership(guid) {
if (guid === this.guid) {
if (debugOwner)
console.log("LOST OWNERSHIP", this.guid);
this._hasOwnership = false;
this._isOwned = false;
// Resolve pending ownership request as failed
if (this._pendingOwnershipResolve) {
this._pendingOwnershipResolve(false);
this._pendingOwnershipResolve = null;
}
}
}
}
/**
* Main class for multiuser networking. Access via `this.context.connection` from any component.
*
* **About GUIDs:**
* In Needle Engine networking, GUIDs (Globally Unique Identifiers) are used to identify objects and components across the network.
* Every GameObject and Component has a unique `guid` property that remains consistent across all clients.
* GUIDs are automatically assigned (e.g. during export from Unity/Blender) and are essential for:
* - Object ownership management (see {@link OwnershipModel})
* - State synchronization (storing and retrieving object state)
* - Identifying which object received a network message
*
* When working with networking, you'll typically use `this.guid` to identify your component or `this.gameObject.guid` for the GameObject.
*
* @example Joining a room
* ```ts
* this.context.connection.connect();
* this.context.connection.joinRoom("my-room");
* ```
* @example Listening to events
* ```ts
* this.context.connection.beginListen("my-event", (data) => {
* console.log("Received:", data);
* });
* ```
* @example Sending data
* ```ts
* this.context.connection.send("my-event", { message: "Hello" });
* ```
* @example Using GUIDs for object identification
* ```ts
* // Get state for a specific object by its GUID
* const state = this.context.connection.tryGetState(this.guid);
*
* // Delete remote state for an object
* this.context.connection.sendDeleteRemoteState(this.guid);
* ```
* @see {@link RoomEvents} for room lifecycle events
* @see {@link OwnershipModel} for object ownership
* @link https://engine.needle.tools/docs/how-to-guides/networking/
* @category Networking
*/
export class NetworkConnection {
context;
_peer = null;
constructor(context) {
this.context = context;
}
/** Experimental: networking via peerjs */
get peer() {
if (!this._peer) {
this._peer = new PeerNetworking();
}
return this._peer;
}
/**
* Returns the cached network state for a given GUID.
* The state is stored locally whenever network updates are received for that object.
* @param guid The unique identifier of the object whose state you want to retrieve
* @returns The cached state object, or `null` if no state exists for this GUID
* @example
* ```ts
* // Get the last known state for this component
* const myState = this.context.connection.tryGetState(this.guid);
* if (myState) {
* console.log("Found cached state:", myState);
* }
* ```
*/
tryGetState(guid) {
if (guid === "invalid")
return null;
return this._state[guid];
}
/** The connection id of the local user - it is given by the networking backend and can not be changed */
get connectionId() {
return this._connectionId;
}
/** Returns true if the networking backend is in debug mode.
* To see all networking messages in the console use `?debugnet` in the url
*/
get isDebugEnabled() {
return debugNet;
}
/**
* Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `{@link isInRoom}` property.
* @returns true if connected to the websocket.
*/
get isConnected() {
return this.connected;
}
/** The name of the room the user is currently connected to */
get currentRoomName() { return this._currentRoomName; }
/** True when connected to a room via a regular url, otherwise (when using a view only url) false indicating that the user should not be able to modify the scene */
get allowEditing() { return this._currentRoomAllowEditing; }
/**
* The view id of the room the user is currently connected to.
*/
get currentRoomViewId() { return this._currentRoomViewId; }
/**
* Returns a url that can be shared with others to view the current room in view only mode.
* This is useful for sharing a room with others without allowing them to modify the scene.
* Use `connection.allowEditing` to check if the current room is in view only mode.
*/
getViewOnlyUrl() {
if (this.currentRoomViewId === null)
return null;
const url = new URL(window.location.href);
url.searchParams.set("view", this.currentRoomViewId);
return url.href;
}
/** True if connected to a networked room. Use the joinRoom function or a `SyncedRoom` component */
get isInRoom() {
return this._isInRoom;
}
/** Latency to currently connected backend server */
get currentLatency() {
return this._currentDelay;
}
/**
* The current server url that the networking backend is connected to (e.g. the url of the websocket server)
*/
get currentServerUrl() {
return this._transport?.url ?? null;
}
/** A ping is sent to the server at a regular interval while the browser tab is active. This method can be used to send additional ping messages when needed so that the user doesn't get disconnected from the networking backend */
sendPing() {
this.send("ping", { time: this.context.time.time });
}
/** Returns true if a user with the given connectionId is in the room */
userIsInRoom(id) {
return this._currentInRoom.indexOf(id) !== -1;
}
_usersInRoomCopy = [];
/** Returns a list of all user ids in the current room */
usersInRoom(target = null) {
if (!target)
target = this._usersInRoomCopy;
target.length = 0;
for (const user of this._currentInRoom)
target.push(user);
return target;
}
/** Joins a networked room. If you don't want to manage a connection yourself you can use a `{@link SyncedRoom}` component as well */
joinRoom(room, viewOnly = false) {
if (!room) {
console.error("Missing room name, can not join: \"" + room + "\"");
return false;
}
// There's not really a reason to limit the room name length
if (room.length > 1024) {
console.error("Room name too long, can not join: \"" + room + "\". Max length is 1024 characters.");
return false;
}
else if (this.isInRoom && this.currentRoomName !== room) {
console.warn("Needle Engine is already connected to a networking room. Connecting to multiple rooms is not supported");
}
this.connect();
if (debugNet)
console.log("join: " + room);
this.send(RoomEvents.Join, { room: room, viewOnly: viewOnly }, SendQueue.OnConnection);
return true;
}
/** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
leaveRoom(room = null) {
if (!room)
room = this.currentRoomName;
if (!room) {
console.error("Missing room name, can not join: \"" + room + "\"");
return false;
}
this.send(RoomEvents.Leave, { room: room });
return true;
}
send(key, data, queue = SendQueue.Queued) {
if (queue === SendQueue.Queued) {
this._defaultMessagesBuffer.push({ key: key, value: data });
return;
}
return this.sendWithWebsocket(key, data, queue);
}
/**
* Deletes the network state for a specific object on the server.
* This removes the object's state from the room, preventing it from being sent to newly joining users.
* @param guid The unique identifier of the object whose state should be deleted
* @example
* ```ts
* // When destroying a networked object, clean up its server state
* onDestroy() {
* this.context.connection.sendDeleteRemoteState(this.guid);
* }
* ```
*/
sendDeleteRemoteState(guid) {
this.send("delete-state", { guid: guid, dontSave: true });
delete this._state[guid];
}
/** Use to delete all state in the currently connected room on the server */
sendDeleteRemoteStateAll() {
this.send("delete-all-state");
this._state = {};
}
/** Send a binary message to the server (broadcasted to all connected users) */
sendBinary(bin) {
if (debugnetBin)
console.log("<< send binary", this.context.time.frame, (bin.length / 1024) + " KB");
this._transport?.send(bin);
}
_defaultMessagesBuffer = [];
_defaultMessagesBufferArray = [];
sendBufferedMessagesNow() {
if (!this._transport)
return;
this._defaultMessagesBufferArray.length = 0;
const count = Object.keys(this._defaultMessagesBuffer).length;
for (const key in this._defaultMessagesBuffer) {
const data = this._defaultMessagesBuffer[key];
// if there is only one message to be sent we dont need to send an array
if (count <= 1) {
this.sendWithWebsocket(data.key, data.value, SendQueue.Immediate);
break;
}
const msg = this.toMessage(data.key, data.value);
this._defaultMessagesBufferArray.push(msg);
}
this._defaultMessagesBuffer.length = 0;
if (this._defaultMessagesBufferArray.length > 0 && debugNet)
console.log("SEND BUFFERED", this._defaultMessagesBufferArray.length);
if (this._defaultMessagesBufferArray.length <= 0)
return;
const message = JSON.stringify(this._defaultMessagesBufferArray);
this._transport?.send(message);
}
/** Use to start listening to networking events.
* Returns an unsubscribe function that removes the listener when called.
* The returned function can also be passed to {@link stopListen} or {@link Component.autoCleanup} for automatic lifecycle management.
*
* @example With autoCleanup (recommended)
* ```ts
* export class MyComponent extends Behaviour {
* onEnable() {
* this.autoCleanup(this.context.connection.beginListen("joined-room", () => {
* console.log("I joined a networked room");
* }));
* }
* // Automatically unsubscribed on disable — no manual cleanup needed!
* }
* ```
*
* @example Manual unsubscribe
* ```ts
* const unsub = this.context.connection.beginListen("joined-room", () => { });
* // Later:
* unsub(); // removes the listener
* ```
*
* @example With stopListen (legacy pattern, still supported)
* ```ts
* export class MyComponent extends Behaviour {
* onEnable() {
* this.context.connection.beginListen("joined-room", this.onJoinedRoom);
* }
* onDisable() {
* this.context.connection.stopListen("joined-room", this.onJoinedRoom);
* }
* onJoinedRoom = () => {
* console.log("I joined a networked room");
* }
* }
* ```
* @link https://engine.needle.tools/docs/networking.html
*
*/
beginListen(key, callback) {
if (!this._listeners[key])
this._listeners[key] = [];
this._listeners[key].push(callback);
const unsub = () => this.stopListen(key, callback);
unsub[$originalCallback] = callback;
return unsub;
}
/**@deprecated please use stopListen instead (2.65.2-pre) */
stopListening(key, callback) { return this.stopListen(key, callback); }
/** Use to stop listening to networking events.
* Accepts either the original callback or the unsubscribe function returned by {@link beginListen}.
* To subscribe to events use the `{@link beginListen}` method.
*
* @example
* ```ts
* // Both patterns work:
* this.context.connection.stopListen("joined-room", this.onJoinedRoom); // original callback
* this.context.connection.stopListen("joined-room", unsub); // unsubscribe fn from beginListen
* ```
*/
static _didLogStopListenHint = false;
stopListen(key, callback) {
if (!callback)
return;
if (!this._listeners[key])
return;
// Backwards compat: if an unsubscribe function returned by beginListen was passed to stopListen,
// resolve it to the original callback via symbol so the listener can be found and removed.
const original = callback[$originalCallback] ?? callback;
if (original !== callback && isDevEnvironment() && !NetworkConnection._didLogStopListenHint) {
NetworkConnection._didLogStopListenHint = true;
console.warn("[Needle Engine] Tip: beginListen() returns an unsubscribe function — you can call it directly instead of using stopListen().");
}
const index = this._listeners[key].indexOf(original);
if (index >= 0) {
this._listeners[key].splice(index, 1);
}
}
/** Use to start listening to networking binary events.
* Returns an unsubscribe function that removes the listener when called.
* The returned function can also be passed to {@link stopListenBinary} or {@link Component.autoCleanup}.
*/
beginListenBinary(identifier, callback) {
if (!this._listenersBinary[identifier])
this._listenersBinary[identifier] = [];
this._listenersBinary[identifier].push(callback);
const unsub = () => this.stopListenBinary(identifier, callback);
unsub[$originalCallback] = callback;
return unsub;
}
/** Use to stop listening to networking binary events.
* Accepts either the original callback or the unsubscribe function returned by {@link beginListenBinary}.
*/
stopListenBinary(identifier, callback) {
if (!this._listenersBinary[identifier])
return;
// Backwards compat: resolve unsubscribe function to original callback via symbol
const original = callback?.[$originalCallback] ?? callback;
const index = this._listenersBinary[identifier].indexOf(original);
if (index >= 0) {
this._listenersBinary[identifier].splice(index, 1);
}
}
netWebSocketUrlProvider;
/** Use to override the networking server backend url.
* This is what the `{@link Networking}` component uses to modify the backend url.
**/
registerProvider(prov) {
this.netWebSocketUrlProvider = prov;
}
/** Used to connect to the networking server
* @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
* @param transport Optional custom transport to use instead of the default websocket. Useful for testing or alternative transports.
*/
async connect(url, transport) {
if (this.connected && url && url !== networkingServerUrl) {
return Promise.reject("Can not connect to different server url. Please disconnect first.");
}
if (this.connected) {
return Promise.resolve(true);
}
if (transport) {
return this.connectTransport(transport);
}
if (url)
console.debug("Connecting to user provided url " + url);
const overrideUrl = url || this.netWebSocketUrlProvider?.getWebsocketUrl();
if (overrideUrl) {
networkingServerUrl = overrideUrl;
}
else if (isHostedOnGlitch()) {
networkingServerUrl = "wss://" + window.location.host + "/socket";
}
return this.connectWebsocket();
}
;
/** Disconnect from the networking backend + reset internal state */
disconnect() {
if (this._transport) {
// Clear callbacks before closing so the onClose handler doesn't fire
this._transport.onOpen = null;
this._transport.onClose = null;
this._transport.onError = null;
this._transport.onMessage = null;
this._transport.close();
this._transport = undefined;
}
networkingServerUrl = undefined;
// Reset all state synchronously so callers can rely on isConnected/isInRoom immediately
this.connected = false;
this._connectionId = null;
this._currentRoomAllowEditing = true;
this._currentRoomName = null;
this._currentRoomViewId = null;
this._isInRoom = false;
this._currentInRoom.length = 0;
this._state = {};
this._currentDelay = -1;
this._connectingToWebsocketPromise = null;
}
/** Full teardown: disconnect, clear all listeners, and release all resources.
* Called when the owning Context is destroyed. After dispose(), this instance should not be reused. */
dispose() {
this.disconnect();
this._listeners = {};
this._listenersBinary = {};
this._waitingForSocket = {};
this._peer = null;
}
_listeners = {};
_listenersBinary = {};
connected = false;
_connectionId = null;
// Transport ------------------------------------------------------------
_transport;
_waitingForSocket = {};
_isInRoom = false;
_currentRoomName = null;
_currentRoomViewId = null;
_currentRoomAllowEditing = true;
_currentInRoom = [];
_state = {};
_currentDelay = -1;
_connectingToWebsocketPromise = null;
/** Wire up a transport's event callbacks and start it */
connectTransport(transport) {
if (this._connectingToWebsocketPromise)
return this._connectingToWebsocketPromise;
return this._connectingToWebsocketPromise = new Promise((res) => {
let didResolve = false;
const resolve = (val) => {
if (didResolve)
return;
didResolve = true;
res(val);
};
transport.onOpen = () => {
this._connectingToWebsocketPromise = null;
this._transport = transport;
this.connected = true;
if (isDevEnvironment() || debugNet)
console.log("Connected to networking backend\n" + (transport.url ?? ""));
else
console.debug("Connected to networking backend", transport.url ?? "");
resolve(true);
this.onSendQueued(SendQueue.OnConnection);
};
transport.onClose = () => {
this._connectingToWebsocketPromise = null;
this.connected = false;
this._isInRoom = false;
resolve(false);
let msg = "Websocket connection closed...";
if (!transport.url?.includes("/socket"))
msg += ` Do you perhaps mean to connect to "/socket"?`;
console.error(msg);
};
transport.onError = () => {
console.error("Websocket connection failed...");
resolve(false);
Telemetry.sendEvent(this.context, "networking", {
event: "connection_error",
});
};
transport.onMessage = (data) => {
this.onMessage(data);
};
transport.start();
});
}
async connectWebsocket() {
if (this._connectingToWebsocketPromise)
return this._connectingToWebsocketPromise;
if (networkingServerUrl === undefined) {
console.log("Fetch default backend url: " + defaultNetworkingBackendUrlProvider);
const defaultUrlResponse = await fetch(defaultNetworkingBackendUrlProvider);
networkingServerUrl = await defaultUrlResponse.text();
}
if (networkingServerUrl === undefined) {
return false;
}
console.debug("Connecting to networking backend on\n" + networkingServerUrl);
const transport = new WebsocketTransport(networkingServerUrl);
return this.connectTransport(transport);
}
onMessage(data) {
const msg = data;
try {
if (typeof msg !== "string") {
if (msg.size) {
// is binary blob
this.handleIncomingBinaryMessage(msg);
}
return;
}
const message = JSON.parse(msg);
if (Array.isArray(message)) {
// console.log("Receive package of " + message.length + " messages")
for (const msg of message) {
this.handleIncomingStringMessage(msg);
}
}
else
this.handleIncomingStringMessage(message);
return;
}
catch (err) {
if (debugNet && msg === "pong")
console.log("<<", msg);
else if (isDevEnvironment())
console.error("Failed to parse message", err);
}
}
async handleIncomingBinaryMessage(blob) {
if (debugnetBin)
console.log("<< bin", this.context.time.frame);
const buf = await blob.arrayBuffer();
var data = new Uint8Array(buf);
const bb = new flatbuffers.ByteBuffer(data);
const id = bb.getBufferIdentifier();
const callbacks = this._listenersBinary[id];
// use registered cast methods to get the correct type from the flatbuffer
const obj = schemes.tryCastBinary(bb);
const guid = schemes.tryGetGuid(obj);
if (guid && typeof guid === "string") {
this._state[guid] = obj;
}
if (!callbacks)
return;
const res = obj ?? bb; // fallback to bytebuffer if no cast method is registered
// call all listeners subscribed to these events
for (const cb of callbacks) {
cb(res);
}
}
handleIncomingStringMessage(message) {
if (debugNet)
console.log("<<", message.key ?? message);
if (message.key) {
switch (message.key) {
case ConnectionEvents.ConnectionInfo:
if (message.data) {
const connection = message.data;
if (connection) {
console.assert(connection.id !== undefined && connection.id !== null && connection.id.length > 0, "server did not send connection id", connection.id);
console.debug("Your id is: " + connection.id, this.context.alias ?? "");
this._connectionId = connection.id;
Telemetry.sendEvent(this.context, "networking", {
event: "connected",
});
}
}
else
console.warn("Expected connection id in " + message.key);
break;
case RoomEvents.JoinedRoom:
if (debugNet)
console.log(message);
if (message) {
this._isInRoom = true;
const model = message;
this._currentRoomName = model.room;
this._currentRoomViewId = model.viewId;
this._currentRoomAllowEditing = model.allowEditing ?? true;
this._currentInRoom.length = 0;
this._currentInRoom.push(...model.inRoom);
if (debugnetBin || isDevEnvironment())
console.debug("Joined Needle Engine Room: " + model.room);
const viewUrl = new URL(window.location.href);
if (viewUrl.searchParams.has("room")) {
viewUrl.searchParams.delete("room");
}
viewUrl.searchParams.set("view", this._currentRoomViewId);
console.debug(`Room view id: ${this._currentRoomViewId}\n${viewUrl.href}`);
}
this.onSendQueued(SendQueue.OnRoomJoin);
Telemetry.sendEvent(this.context, "networking", {
event: "joined_room",
room: this._currentRoomName,
});
break;
case RoomEvents.LeftRoom:
const model = message;
if (model.room === this.currentRoomName) {
this._isInRoom = false;
this._currentRoomName = null;
this._currentRoomAllowEditing = true;
this._currentInRoom.length = 0;
if (debugnetBin || isDevEnvironment())
console.debug("Left Needle Engine Room: " + model.room);
}
Telemetry.sendEvent(this.context, "networking", {
event: "left_room",
room: model.room,
});
break;
case RoomEvents.UserJoinedRoom:
if (message.data) {
const model = message.data;
this._currentInRoom.push(model.userId);
if (debugNet)
console.log(model.userId + " joined", "now in room:", this._currentInRoom);
}
break;
case RoomEvents.UserLeftRoom:
if (message.data) {
const model = message.data;
const index = this._currentInRoom.indexOf(model.userId);
if (index >= 0) {
if (debugNet)
console.log(model.userId + " left", "now in room:", this._currentInRoom);
this._currentInRoom.splice(index, 1);
}
if (model.userId === this.connectionId) {
// you left the room
console.log("you left the room");
}
}
break;
case "all-room-state-deleted":
if (debugNet)
console.log("RECEIVED all-room-state-deleted");
this._state = {};
break;
case "ping":
case "pong":
const time = message.data?.time;
if (time) {
this._currentDelay = this.context.time.time - time;
}
if (debugNet)
console.log(`Current latency: ${(this._currentDelay * 1000).toFixed()} ms`, "Clients in room: " + this._currentInRoom?.length);
break;
}
}
const model = message.data;
if (model) {
this._state[model.guid] = model;
}
let listeners = this._listeners[message.key];
if (listeners) {
// Copy listeners array in case a listener is removed while iterating
listeners = [...listeners];
for (const listener of listeners) {
try {
listener(message.data);
}
catch (err) {
console.error("Error invoking callback for \"" + message.key + "\"", err);
}
}
}
}
toMessage(key, data) {
return {
key: key,
data: data
};
}
sendWithWebsocket(key, data, queue = SendQueue.OnRoomJoin) {
// console.log(key);
if (!this._transport) {
const arr = this._waitingForSocket[queue] || [];
arr.push(() => this.sendWithWebsocket(key, data, queue));
this._waitingForSocket[queue] = arr;
// console.log(this._bufferedMessages)
return;
}
const str = JSON.stringify(this.toMessage(key, data));
if (debugNet)
console.log(">>", key);
this._transport.send(str);
}
onSendQueued(queue) {
const queued = this._waitingForSocket[queue];
// console.log("send", queue, queued);
if (queued) {
for (const callback of queued) {
callback();
}
queued.length = 0;
}
}
}
//# sourceMappingURL=engine_networking.js.map