@needle-tools/engine/src/engine-components/AxesHelper.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 { AxesHelper as _AxesHelper } from "three";

import * as params from "../engine/engine_default_parameters.js";
import { serializable } from "../engine/engine_serialization_decorator.js";
import { Behaviour } from "./Component.js";

/**
 * Component that visualizes the axes of an object in the scene.
 * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
 * @category Helpers
 * @group Components
 */
export class AxesHelper extends Behaviour {
    /**
     * The length of each axis line in scene units.
     */
    @serializable()
    public length: number = 1;
    
    /**
     * Whether the axes should be occluded by objects in the scene.
     * When set to false, axes will always appear on top regardless of their depth.
     */
    @serializable()
    public depthTest: boolean = true;
    
    /**
     * When true, this helper will only be visible if the debug flag `?gizmos` is enabled.
     */
    @serializable()
    public isGizmo: boolean = false;

    private _axes: _AxesHelper | null = null;

    /**
     * Creates and adds the axes visualization to the scene when the component is enabled.
     * If marked as a gizmo, it will only be shown when gizmos are enabled in the global parameters.
     */
    onEnable(): void {
        if (this.isGizmo && !params.showGizmos) return;
        if (!this._axes)
            this._axes = new _AxesHelper(this.length);
        this._axes.layers.disableAll();
        this._axes.layers.set(this.layer);
        this.gameObject.add(this._axes);
        const mat: any = this._axes.material;
        if (mat) {
            if (mat.depthTest !== undefined)
                mat.depthTest = this.depthTest;
        }
    }

    /**
     * Removes the axes visualization from the scene when the component is disabled.
     */
    onDisable(): void {
        if (!this._axes) return;
        this.gameObject.remove(this._axes);
    }
}