@needle-tools/engine/src/engine-components/DeviceFlag.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 { serializable } from "../engine/engine_serialization_decorator.js";
import { DeviceUtilities } from "../engine/engine_utils.js";
import { Behaviour, GameObject } from "./Component.js";


export enum DeviceType {
    Never = 0,
    Desktop = 1 << 0,
    Mobile = 2 << 0,
}

/**
 * DeviceFlag shows or hides GameObjects based on device type.  
 * Use for responsive 3D content - show different UI, models, or interactions  
 * depending on mobile vs desktop.  
 *
 * **Device types:**   
 * - `Desktop` - Traditional computers with mouse/keyboard
 * - `Mobile` - Phones and tablets with touch input
 * - Combine with bitwise OR for multiple: `Desktop | Mobile`
 *
 * @example Show only on desktop
 * ```ts
 * const flag = myObject.addComponent(DeviceFlag);
 * flag.visibleOn = DeviceType.Desktop;
 * ```
 *
 * @example Show on both mobile and desktop
 * ```ts
 * flag.visibleOn = DeviceType.Desktop | DeviceType.Mobile;
 * ```
 *
 * @summary Show or hide GameObject based on device type
 * @category Utilities
 * @group Components
 * @see {@link DeviceType} for device options
 * @see {@link XRFlag} for XR-based visibility
 */
export class DeviceFlag extends Behaviour {

    @serializable()
    visibleOn!: DeviceType;


    onEnable() {
        this.apply();
    }

    apply() {    
        if (!this.test()) {
            GameObject.setActive(this.gameObject, false);
        }
    }

    private test() : boolean {
        if(this.visibleOn < 0) return true;
        if(DeviceUtilities.isMobileDevice()) {
            return (this.visibleOn & (DeviceType.Mobile)) !== 0;
        }
        const allowDesktop = (this.visibleOn & (DeviceType.Desktop)) !== 0;
        return allowDesktop;
    }

}

/**@deprecated use isMobileDevice() */
function isMobile() {
    return DeviceUtilities.isMobileDevice();
};