@needle-tools/engine/src/engine-components/Networking.ts

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.

import type { INetworkingWebsocketUrlProvider } from "../engine/engine_networking.js";
import { isLocalNetwork } from "../engine/engine_networking_utils.js";
import { serializable } from "../engine/engine_serialization.js";
import { getParam } from "../engine/engine_utils.js";
import { Behaviour } from "./Component.js";

const debug = getParam("debugnet");

/**
 * Provides websocket URL configuration for the built-in networking system.
 * Add this component to override the default networking backend URL used by {@link NetworkConnection} (`this.context.connection`).
 *
 * The component registers itself as a URL provider on `awake()`. When the networking system connects,
 * it queries this provider for the websocket URL to use instead of the default Needle networking backend.
 *
 * **URL resolution order:**
 * 1. If `urlParameterName` is set and the corresponding URL parameter exists in the browser URL, that value is used
 * 2. If running on a local network and `localhost` is set, the `localhost` URL is used
 * 3. Otherwise, the `url` field is used
 *
 * Without this component, the default backend URL `wss://networking-2.needle.tools/socket` is used.
 *
 * **Note:** This component only configures the websocket URL. To actually join a networked room,
 * use a `SyncedRoom` component or call `this.context.connection.joinRoom("room-name")` directly.
 *
 * @example Overriding the URL via browser parameter
 * ```ts
 * // With urlParameterName="server", visiting:
 * // https://myapp.com/?server=wss://my-server.com/socket
 * // will connect to that server instead
 * ```
 *
 * @see {@link NetworkConnection} for the main networking API (`this.context.connection`)
 * @see {@link SyncedRoom} for automatic room joining
 * @see {@link OwnershipModel} for networked object ownership
 * @see {@link RoomEvents} for room lifecycle events
 * @link https://engine.needle.tools/docs/how-to-guides/networking/
 * @summary Networking configuration
 * @category Networking
 * @group Components
 */
export class Networking extends Behaviour implements INetworkingWebsocketUrlProvider {

    /** 
     * The websocket URL to connect to for networking functionality.
     * Can be a complete URL or a relative path that will be resolved against the current origin.
     * @default null
     */
    @serializable()
    url: string | null = null;

    /** 
     * Name of the URL parameter that can override the websocket connection URL.
     * When set, the URL will be overridden by the parameter value from the browser URL.
     * For example, with `urlParameterName="ws"`, adding `?ws=ws://localhost:8080` to the browser URL will override the connection URL.
     */
    @serializable()
    urlParameterName: string | null = null;

    /** 
     * Alternative URL to use when running on a local network.
     * This is particularly useful for development, when the server is running on the same machine as the client.
     */
    @serializable()
    localhost: string | null = null;

    /** @internal */
    awake() {
        if (debug)
            console.log(this);
        this.context.connection.registerProvider(this);
    }

    /** 
     * Determines the websocket URL to use for networking connections.
     * Processes the configured URL, applying localhost fallbacks when appropriate and
     * handling URL parameter overrides if specified.
     * @returns The formatted websocket URL string or null if no valid URL could be determined
     * @internal
     */
    getWebsocketUrl(): string | null {

        let socketurl = this.url ? Networking.GetUrl(this.url, this.localhost) : null;

        if (this.urlParameterName) {
            const res = getParam(this.urlParameterName);
            if (res && typeof res === "string") {
                socketurl = res;
            }
        }

        if (!socketurl) return null;

        // regex https://regex101.com/r/JQ5WqB/1
        const regex = new RegExp("(((https?)|(?<socket_prefix>wss?)):\/\/)?(www\.)?(?<url>.+)", "gm");
        const match = regex.exec(socketurl);
        if (!match?.groups) return null;
        // if the url has a ws or wss prefix already assume the whole url is in the correct format
        const socketPrefix = match?.groups["socket_prefix"];
        if (socketPrefix) return socketurl;
        // otherwise add the ws prefix
        return "wss://" + match?.groups["url"];
    }

    /**
     * Processes a URL string applying various transformations based on network environment.
     * Handles relative paths and localhost fallbacks for local network environments.
     * @param url The original URL to process
     * @param localhostFallback Alternative URL to use when on a local network
     * @returns The processed URL string or null/undefined if input was invalid
     */
    public static GetUrl(url: string | null | undefined, localhostFallback?: string | null): string | null | undefined {

        let result = url;

        const useLocalHostUrl = Networking.IsLocalNetwork() && localhostFallback;
        if (useLocalHostUrl) {
            result = localhostFallback;
        }

        if (url?.startsWith("/")) {
            const base = useLocalHostUrl ? result : window.location.origin;
            if(base?.endsWith("/") && url.startsWith("/"))
                url = url.substring(1);
            result = base + url;
        }

        return result;
    }

    /**
     * Determines if the current connection is on a local network.
     * Useful for applying different networking configurations in local development environments.
     * This is the same as calling {@link isLocalNetwork}.
     * @param hostname Optional hostname to check instead of the current window location
     * @returns True if the connection is on a local network, false otherwise
     */
    public static IsLocalNetwork(hostname = window.location.hostname) {
        return isLocalNetwork(hostname);
    }
}