@needle-tools/engine/src/engine-components/NeedleMenu.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 { Context } from '../engine/engine_context.js';
import { serializable } from '../engine/engine_serialization.js';
import { DeviceUtilities } from '../engine/engine_utils.js';
import { Behaviour } from './Component.js';
// Type-only imports for TSDoc @see links
import type { ScreenCapture } from './ScreenCapture.js';
import type { Voip } from './Voip.js';

/**
 * [NeedleMenu](https://engine.needle.tools/docs/api/NeedleMenu) provides configuration for the built-in UI menu.
 * The menu renders as HTML overlay in browser mode and automatically
 * switches to a 3D spatial menu in VR/AR.
 *
 * ![](https://cloud.needle.tools/-/media/YKleg1oPy_I8Hv8sg_k40Q.png)
 *
 * **Features:**
 * - Fullscreen toggle button
 * - Audio mute/unmute button
 * - QR code sharing (desktop only)
 * - Spatial menu in XR (appears when looking up)
 * - Custom positioning (top/bottom)
 *
 * **Programmatic access:**
 * Access the menu API via `this.context.menu` to add custom buttons,
 * show/hide elements, or modify behavior at runtime.
 *
 * @example Configure menu from code
 * ```ts
 * // Access the menu API
 * this.context.menu.appendChild(myCustomButton);
 * this.context.menu.setPosition("top");
 * this.context.menu.showFullscreenOption(true);
 * ```
 *
 * @summary Configuration component for the Needle Menu overlay
 * @category User Interface
 * @group Components
 * @see {@link Context.menu} for programmatic menu control
 * @see {@link NeedleButtonElement} for standalone <needle-button> web component
 * @see {@link NeedleEngineWebComponent} for the main <needle-engine> element
 * @see {@link Voip} adds a microphone button to the menu
 * @see {@link ScreenCapture} adds a screen sharing button
 **/
export class NeedleMenu extends Behaviour {

    /**
     * Determines the vertical positioning of the menu on the screen
     */
    @serializable()
    position: "top" | "bottom" = "bottom";

    /** 
     * Controls the visibility of the Needle logo in the menu (requires PRO license)
     */
    @serializable()
    showNeedleLogo: boolean = false;

    /** 
     * When enabled, displays the menu in VR/AR mode when the user looks up
     * @default undefined
     */
    @serializable()
    showSpatialMenu?: boolean;

    /** 
     * When enabled, adds a fullscreen toggle button to the menu
     * @default undefined
     */
    @serializable()
    createFullscreenButton?: boolean;
    
    /** 
     * When enabled, adds an audio mute/unmute button to the menu
     * @default undefined
     */
    @serializable()
    createMuteButton?: boolean;

    /**
     * When enabled, adds a button to display a QR code for sharing the application.
     * The QR code is only displayed on desktop devices.
     * @default undefined
     */
    @serializable()
    createQRCodeButton?: boolean;

    /** 
     * Applies the configured menu options when the component is enabled
     * @hidden
     */
    onEnable() {
        this.applyOptions();
    }

    /** 
     * Applies all configured options to the active {@link Context.menu}.
     */
    applyOptions() {
        this.context.menu.setPosition(this.position);
        this.context.menu.showNeedleLogo(this.showNeedleLogo);
        if (this.createFullscreenButton === true)
            this.context.menu.showFullscreenOption(true);
        if (this.createMuteButton === true)
            this.context.menu.showAudioPlaybackOption(true);
        if (this.showSpatialMenu === true)
            this.context.menu.showSpatialMenu(this.showSpatialMenu);
        if (this.createQRCodeButton === true) {
            if (!DeviceUtilities.isMobileDevice()) {
                this.context.menu.showQRCodeButton(true);
            }
        }
    }

}