@needle-tools/engine/lib/engine-components/TransformGizmo.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 { TransformControls } from "three/examples/jsm/controls/TransformControls.js";
import { Behaviour } from "./Component.js";
/**
 * The [TransformGizmo](https://engine.needle.tools/docs/api/TransformGizmo) displays manipulation controls for translating, rotating, and scaling objects.
 * Wraps three.js {@link TransformControls} with keyboard shortcuts and snapping support.
 *
 * **Keyboard shortcuts:**
 * - `W` - Translate mode
 * - `E` - Rotate mode
 * - `R` - Scale mode
 * - `Q` - Toggle local/world space
 * - `Shift` (hold) - Enable grid snapping
 * - `+/-` - Adjust gizmo size
 * - `X/Y/Z` - Toggle axis visibility
 * - `Space` - Toggle controls enabled
 *
 * **Snapping:**
 * Configure grid snapping with `translationSnap`, `rotationSnapAngle`, and `scaleSnap`.
 *
 * **Networking:**
 * Automatically works with {@link SyncedTransform} for multiplayer editing.
 *
 * @example Add transform gizmo to an object
 * ```ts
 * const gizmo = editableObject.addComponent(TransformGizmo);
 * gizmo.translationSnap = 0.5; // Snap to 0.5 unit grid
 * gizmo.rotationSnapAngle = 45; // Snap to 45° increments
 * ```
 *
 * @summary Object manipulation gizmo for translate/rotate/scale
 * @category Helpers
 * @group Components
 * @see {@link DragControls} for simpler drag-only interaction
 * @see {@link SyncedTransform} for network synchronization
 * @see {@link OrbitControls} - automatically disabled during gizmo drag
 * @link https://threejs.org/docs/index.html#examples/en/controls/TransformControls for underlying three.js controls and additional features
 */
export declare class TransformGizmo extends Behaviour {
    /**
     * When true, this is considered a helper gizmo and will only be shown if showGizmos is enabled in engine parameters.
     */
    isGizmo: boolean;
    /**
     * Specifies the translation grid snap value in world units.
     * Applied when holding Shift while translating an object.
     */
    translationSnap: number;
    /**
     * Specifies the rotation snap angle in degrees.
     * Applied when holding Shift while rotating an object.
     */
    rotationSnapAngle: number;
    /**
     * Specifies the scale snapping value.
     * Applied when holding Shift while scaling an object.
     */
    scaleSnap: number;
    /**
     * Gets the underlying three.js {@link TransformControls} instance.
     * @returns The TransformControls instance or undefined if not initialized.
     */
    get control(): TransformControls | undefined;
    private _control?;
    private orbit?;
    /** @internal */
    onEnable(): void;
    /** @internal */
    onDisable(): void;
    /**
     * Enables grid snapping for transform operations according to set snap values.
     * This applies the translationSnap, rotationSnapAngle, and scaleSnap properties to the controls.
     */
    enableSnapping(): void;
    /**
     * Disables grid snapping for transform operations.
     * Removes all snapping constraints from the transform controls.
     */
    disableSnapping(): void;
    /**
     * Event handler for when dragging state changes.
     * Disables orbit controls during dragging and requests ownership of the transform if it's synchronized.
     * @param event The drag change event
     */
    private onControlChangedEvent;
    /**
     * Handles keyboard shortcuts for transform operations:
     * - Q: Toggle local/world space
     * - W: Translation mode
     * - E: Rotation mode
     * - R: Scale mode
     * - Shift: Enable snapping (while held)
     * - +/-: Adjust gizmo size
     * - X/Y/Z: Toggle visibility of respective axis
     * - Spacebar: Toggle controls enabled state
     * @param event The keyboard event
     */
    private windowKeyDownListener;
    /**
     * Handles keyboard key release events.
     * Currently only handles releasing Shift key to disable snapping.
     * @param event The keyboard event
     */
    private windowKeyUpListener;
}