@needle-tools/engine/lib/engine-components/SpectatorCamera.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 { PlayerView } from "../engine/engine_playerview.js";
import { Camera } from "./Camera.js";
import { Behaviour } from "./Component.js";
/**
 * Defines the viewing perspective in spectator mode
 */
export declare enum SpectatorMode {
    /** View from the perspective of the followed player */
    FirstPerson = 0,
    /** Freely view from a third-person perspective */
    ThirdPerson = 1
}
/**
 * SpectatorCamera enables following and spectating other users in networked sessions.
 * Switch between first-person (see what they see) and third-person (orbit around them) views.
 *
 * **Keyboard controls** (when `useKeys = true`):
 * - `F` - Request all users to follow the local player
 * - `ESC` - Stop spectating
 *
 * **Spectator modes:**
 * - `FirstPerson` - View from the followed player's perspective
 * - `ThirdPerson` - Freely orbit around the followed player
 *
 * **Debug:** Use `?debugspectator` URL parameter for logging.
 *
 * @example Start spectating a user
 * ```ts
 * const spectator = camera.getComponent(SpectatorCamera);
 * spectator.follow(targetUserId);
 * spectator.mode = SpectatorMode.ThirdPerson;
 * ```
 *
 * @summary Spectator camera for following other users
 * @category Networking
 * @group Components
 * @see {@link SpectatorMode} for view options
 * @see {@link SyncedRoom} for networked sessions
 * @see {@link OrbitControls} for third-person orbit
 */
export declare class SpectatorCamera extends Behaviour {
    /** Reference to the Camera component on this GameObject */
    cam: Camera | null;
    /**
     * When enabled, pressing F will send a request to all connected users to follow the local player.
     * Pressing ESC will stop spectating.
     */
    useKeys: boolean;
    private _mode;
    /** Gets the current spectator perspective mode */
    get mode(): SpectatorMode;
    /** Sets the current spectator perspective mode */
    set mode(val: SpectatorMode);
    /** Returns whether this user is currently spectating another user */
    get isSpectating(): boolean;
    /**
     * Checks if this instance is spectating the user with the given ID
     * @param userId The user ID to check
     * @returns True if spectating the specified user, false otherwise
     */
    isSpectatingUser(userId: string): boolean;
    /**
     * Checks if the user with the specified ID is following this user
     * @param userId The user ID to check
     * @returns True if the specified user is following this user, false otherwise
     */
    isFollowedBy(userId: string): boolean;
    /** List of user IDs that are currently following the user */
    get followers(): string[];
    /** Stops the current spectating session */
    stopSpectating(): void;
    /** Gets the local player's connection ID */
    private get localId();
    /**
     * Sets the player view to follow
     * @param target The PlayerView to follow, or undefined to stop spectating
     */
    set target(target: PlayerView | undefined);
    /** Gets the currently followed player view */
    get target(): PlayerView | undefined;
    /** Sends a network request for all users to follow this player */
    requestAllFollowMe(): void;
    /** Determines if the camera is spectating the local player */
    private get isSpectatingSelf();
    private orbit;
    private _handler?;
    private eventSub_WebXRRequestStartEvent;
    private eventSub_WebXRStartEvent;
    private eventSub_WebXREndEvent;
    private _debug?;
    private _networking;
    awake(): void;
    onDestroy(): void;
    /**
     * Checks if the current platform supports spectator mode
     * @returns True if the platform is supported, false otherwise
     */
    private isSupportedPlatform;
    /**
     * Called before entering WebXR mode
     * @param _evt The WebXR event
     */
    onBeforeXR(_evt: any): void;
    /**
     * Called when entering WebXR mode
     * @param _evt The WebXR event
     */
    onEnterXR(_evt: any): void;
    /**
     * Called when exiting WebXR mode
     * @param _evt The WebXR event
     */
    onLeaveXR(_evt: any): void;
    /**
     * Sets the target to follow the local player
     */
    private followSelf;
    /**
     * Called after the main rendering pass to render the spectator view
     */
    onAfterRender(): void;
    /**
     * Updates avatar visibility flags for rendering in spectator mode
     */
    private setAvatarFlagsBeforeRender;
    /**
     * Restores avatar visibility flags after spectator rendering
     */
    private resetAvatarFlags;
}