@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";

/**
 * The [AxesHelper](https://engine.needle.tools/docs/api/AxesHelper) visualizes the local coordinate axes of an object.
 * Displays colored lines for X (red), Y (green), and Z (blue) axes.
 *
 * **Use cases:**
 * - Debugging object orientation and rotation
 * - Visualizing pivot points
 * - Understanding coordinate systems
 *
 * **Properties:**
 * - `length` - Length of axis lines in world units
 * - `depthTest` - Whether axes are occluded by scene objects
 * - `isGizmo` - Only show when `?gizmos` URL parameter is set
 *
 * @example Add axes visualization
 * ```ts
 * const axes = myObject.addComponent(AxesHelper);
 * axes.length = 2;
 * axes.depthTest = false; // Always visible on top
 * ```
 *
 * @summary Visualizes object axes (X=red, Y=green, Z=blue)
 * @category Helpers
 * @group Components
 * @see {@link GridHelper} for grid visualization
 * @see {@link Gizmos} for debug drawing utilities
 */
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);
    }
}