@needle-tools/engine/lib/engine-components-experimental/networking/PlayerSync.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 { Object3D } from "three";
import { AssetReference } from "../../engine/engine_addressables.js";
import type { ComponentInit, IGameObject } from "../../engine/engine_types.js";
import { Behaviour, Component } from "../../engine-components/Component.js";
import { EventList } from "../../engine-components/EventList.js";
/** Type definition for a PlayerSync instance with a guaranteed asset property */
declare type PlayerSyncWithAsset = PlayerSync & Required<Pick<PlayerSync, "asset">>;
/**
 * This component instantiates an asset for each player that joins a networked room. The asset will be destroyed when the player leaves the room.
 * The asset should have a PlayerState component, and can have other components like SyncedTransform, custom components, etc.
 * @summary Instantiates and manages player assets in a networked room
 * @category Networking
 * @group Components
 */
export declare class PlayerSync extends Behaviour {
    /**
     * This API is experimental and may change or be removed in the future.
     * Creates a PlayerSync instance at runtime from a given URL and sets it up for networking
     * @param url Path to the asset that should be instantiated for each player
     * @param init Optional initialization parameters for the PlayerSync component
     * @returns Promise resolving to a PlayerSync instance with a guaranteed asset property
     * @example
     * ```typescript
     * const res = await PlayerSync.setupFrom("/assets/demo.glb");
     * addComponent(res.asset?.asset, DragControls);
     * addComponent(res.asset?.asset, SyncedTransform);
     * scene.add(res.gameObject);
     * ```
     */
    static setupFrom(url: string, init?: Omit<ComponentInit<PlayerSync>, "asset">): Promise<PlayerSyncWithAsset>;
    /**
     * When enabled, PlayerSync will automatically load and instantiate the assigned asset when joining a networked room
     */
    autoSync: boolean;
    /**
     * The asset that will be loaded and instantiated when PlayerSync becomes active and joins a networked room
     */
    asset?: AssetReference;
    /**
     * Event invoked when a player instance is spawned with the spawned {@link Object3D} as parameter
     * @serializable
     */
    onPlayerSpawned?: EventList<Object3D>;
    private _localInstance?;
    awake(): void;
    onEnable(): void;
    onDisable(): void;
    private onJoinedRoom;
    /**
     * Gets or creates an instance of the assigned asset for the local player
     * @returns Promise resolving to the instantiated player object or null if creation failed
     */
    getInstance(): Promise<IGameObject | null | undefined>;
    /**
     * Destroys the current player instance and cleans up networking state
     */
    destroyInstance: () => void;
    /**
     * Sets up visibility change listeners to handle player cleanup when browser tab visibility changes
     */
    private watchTabVisible;
}
/**
 * Enum defining events that can be triggered by PlayerState
 */
export declare enum PlayerStateEvent {
    /** Triggered when a PlayerState's owner property changes */
    OwnerChanged = "ownerChanged"
}
/** Arguments passed when a PlayerState's owner changes */
export declare interface PlayerStateOwnerChangedArgs {
    /** The PlayerState instance that changed */
    playerState: PlayerState;
    /** Previous owner's connection ID */
    oldValue: string;
    /** New owner's connection ID */
    newValue: string;
}
/** Callback type for PlayerState events */
export declare type PlayerStateEventCallback = (args: CustomEvent<PlayerStateOwnerChangedArgs>) => void;
/**
 * Represents a player instance in the networked environment.
 * Handles ownership, synchronization, and lifecycle management of player objects.
 */
export declare class PlayerState extends Behaviour {
    private static _all;
    /** All PlayerState instances for all players in the scene */
    static get all(): PlayerState[];
    private static _local;
    /** All PlayerState instances that belong to the local player */
    static get local(): PlayerState[];
    /**
     * Gets the PlayerState component for a given object or component
     * @param obj Object3D or Component to find the PlayerState for
     * @returns The PlayerState component if found, undefined otherwise
     */
    static getFor(obj: Object3D | Component): PlayerState | null | undefined;
    /**
     * Checks if a given object or component belongs to the local player
     * @param obj Object3D or Component to check
     * @returns True if the object belongs to the local player, false otherwise
     */
    static isLocalPlayer(obj: Object3D | Component): boolean;
    private static _callbacks;
    /**
     * Registers a callback for a specific PlayerState event
     * @param event The event to listen for
     * @param cb Callback function that will be invoked when the event occurs
     * @returns The provided callback function for chaining
     */
    static addEventListener(event: PlayerStateEvent, cb: PlayerStateEventCallback): PlayerStateEventCallback;
    /**
     * Removes a previously registered event callback
     * @param event The event type to remove the callback from
     * @param cb The callback function to remove
     */
    static removeEventListener(event: PlayerStateEvent, cb: PlayerStateEventCallback): void;
    private static dispatchEvent;
    /** Event triggered when the owner of this PlayerState changes */
    onOwnerChangeEvent: EventList<any>;
    /** Event triggered the first time an owner is assigned to this PlayerState */
    onFirstOwnerChangeEvent: EventList<any>;
    /** Indicates if this PlayerState has an owner assigned */
    hasOwner: boolean;
    /**
     * The connection ID of the player who owns this PlayerState instance
     * @syncField Synchronized across the network
     */
    owner?: string;
    /**
     * When enabled, PlayerState will not destroy itself when the owner is not connected anymore
     */
    dontDestroy: boolean;
    /**
     * Indicates if this PlayerState belongs to the local player
     */
    get isLocalPlayer(): boolean;
    /**
     * Handles owner change events and updates relevant state
     * @param newOwner The new owner's connection ID
     * @param oldOwner The previous owner's connection ID
     */
    private onOwnerChange;
    /** @internal */
    awake(): void;
    /** @internal */
    start(): Promise<void>;
    /** Tells the server that this client has been destroyed, and the networking message for the instantiate will be removed      */
    doDestroy(): void;
    /** @internal */
    onDestroy(): void;
    /**
     * Handler for when a user leaves the networked room
     * @param model Object containing the ID of the user who left
     */
    private onUserLeftRoom;
}
export {};