@needle-tools/engine/lib/engine-components/Networking.d.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 { Behaviour } from "./Component.js";
/**
 * 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 declare 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
     */
    url: string | 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.
     */
    urlParameterName: string | 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.
     */
    localhost: string | null;
    /** @internal */
    awake(): void;
    /**
     * 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;
    /**
     * 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
     */
    static GetUrl(url: string | null | undefined, localhostFallback?: string | null): string | null | undefined;
    /**
     * 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
     */
    static IsLocalNetwork(hostname?: string): boolean;
}