@aura3d/engine 1.4.4 → 1.5.0

package/dist/controls/TransformControls.d.ts

@@ -1,11 +1,145 @@
-import { type ControlObject3DLike, type Vector3Like } from "./NativeControlTypes";
+import type { ControlObject3DLike, Vector3Like } from "./NativeControlTypes";
 export type TransformControlMode = "translate" | "rotate" | "scale";
+export type TransformControlSpace = "world" | "local";
+export type TransformControlHandle = "x" | "y" | "z" | "xy" | "xz" | "yz" | "uniform";
+/** A pointer ray in world space, as a viewport would unproject it. */
+export interface TransformControlRay {
+    readonly origin: Vector3Like;
+    readonly direction: Vector3Like;
+}
+/** One renderable gizmo handle. */
+export interface TransformControlHandleGeometry {
+    readonly handle: TransformControlHandle;
+    readonly kind: "axis-arrow" | "plane-quad" | "rotation-ring" | "uniform-box";
+    readonly segments: readonly {
+        readonly start: readonly [number, number, number];
+        readonly end: readonly [number, number, number];
+    }[];
+    readonly color: readonly [number, number, number, number];
+    readonly direction?: readonly [number, number, number];
+}
+export interface TransformControlPick {
+    readonly handle: TransformControlHandle;
+    readonly distance: number;
+    readonly point: readonly [number, number, number];
+}
+export interface TransformControlDragUpdate {
+    readonly handle: TransformControlHandle;
+    readonly mode: TransformControlMode;
+    /** Snapped total since drag start: world units for translate/scale, radians for rotate. */
+    readonly totalDelta: number;
+    /** Snapped change since the previous move. */
+    readonly stepDelta: number;
+    readonly snapped: boolean;
+}
+export interface TransformControlSnapSettings {
+    readonly enabled?: boolean;
+    readonly position?: number;
+    readonly rotationDegrees?: number;
+    readonly scale?: number;
+}
+export interface TransformControlsOptions {
+    readonly mode?: TransformControlMode;
+    readonly space?: TransformControlSpace;
+    /** Gizmo arm length in world units. */
+    readonly size?: number;
+    /** Pick radius around each handle, in world units. */
+    readonly pickTolerance?: number;
+    readonly snap?: TransformControlSnapSettings;
+}
+/**
+ * Interactive transform controls: rendered gizmo handles, ray picking, a pointer drag
+ * lifecycle, axis and plane constraints, snapping, and local/world spaces.
+ *
+ * This class previously applied explicit deltas only, with no geometry, picking, or
+ * drag state, which is why it could not support an interactive-parity claim. The delta
+ * API (`apply`) is retained unchanged for source compatibility; everything below it is
+ * new.
+ *
+ * Drag math is projection-free: a pointer ray is intersected with a plane through the
+ * gizmo origin and the resulting world point is projected onto the constrained axis.
+ * The drag plane is derived from the ray direction rather than fixed, because a fixed
+ * plane can be parallel to the pointer ray, in which case there is no intersection and
+ * the drag silently stops responding.
+ */
 export declare class TransformControls {
     object: ControlObject3DLike | null;
     mode: TransformControlMode;
+    enabled: boolean;
+    private space;
+    private readonly size;
+    private readonly pickTolerance;
+    private snapSettings;
+    private origin;
+    private orientation;
+    private hovered;
+    private active;
+    private dragStartValue;
+    private accumulated;
+    private dragging;
+    constructor(options?: TransformControlsOptions);
     attach(object: ControlObject3DLike): void;
     detach(): void;
     setMode(mode: TransformControlMode): void;
+    setSpace(space: TransformControlSpace): void;
+    setSnap(settings: TransformControlSnapSettings): void;
+    /** Places the gizmo. Orientation drives local-space handle directions. */
+    place(origin: readonly [number, number, number], orientation?: readonly [number, number, number, number]): void;
+    state(): {
+        readonly mode: TransformControlMode;
+        readonly space: TransformControlSpace;
+        readonly origin: readonly [number, number, number];
+        readonly hoveredHandle: TransformControlHandle | undefined;
+        readonly activeHandle: TransformControlHandle | undefined;
+        readonly dragging: boolean;
+        readonly snapEnabled: boolean;
+    };
+    /** Renderable handle geometry for the current mode and space. */
+    handles(): readonly TransformControlHandleGeometry[];
+    /**
+     * Picks the nearest handle along a pointer ray.
+     *
+     * Axis and uniform handles outrank plane handles: plane quads share their corner
+     * edges with the axis arms, so a ray aimed at an arm is inside tolerance of both, and
+     * sorting purely by distance would make the arms effectively unclickable.
+     */
+    pick(ray: TransformControlRay): TransformControlPick | undefined;
+    /** Updates hover state. Returns the hovered handle, if any. */
+    hover(ray: TransformControlRay): TransformControlHandle | undefined;
+    /**
+     * Begins a drag on whichever handle the ray picks.
+     *
+     * Returns false when nothing was picked so a viewport can fall through to scene
+     * selection instead of swallowing the pointer.
+     */
+    pointerDown(ray: TransformControlRay): boolean;
+    /**
+     * Continues an active drag and applies the resulting delta to the attached object.
+     *
+     * Only the constrained component is applied, so dragging the X arm cannot move the
+     * object on Y or Z.
+     */
+    pointerMove(ray: TransformControlRay): TransformControlDragUpdate | undefined;
+    /** Ends an active drag and reports the committed total. */
+    pointerUp(): {
+        readonly handle: TransformControlHandle;
+        readonly totalDelta: number;
+    } | undefined;
+    /** Aborts a drag without further mutation, for example on Escape or focus loss. */
+    cancelDrag(): void;
+    /** Explicit-delta mutation, retained unchanged for source compatibility. */
     apply(delta: Vector3Like): void;
+    dispose(): void;
+    private applyConstrainedDelta;
+    /** Which object-space axes a handle affects. */
+    private axisMaskFor;
+    /** World-space direction a translate drag moves along. */
+    private translationDirectionFor;
+    private measure;
+    private axisUnitFor;
+    private applySnap;
+    private toActiveSpace;
+    private pickSegments;
+    private pickRing;
 }
 //# sourceMappingURL=TransformControls.d.ts.map

package/dist/controls/TransformControls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransformControls.d.ts","sourceRoot":"","sources":["../../../../packages/controls/src/TransformControls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,qBAAa,iBAAiB;IAC5B,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAQ;IAC1C,IAAI,EAAE,oBAAoB,CAAe;IAEzC,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IACzC,MAAM,IAAI,IAAI;IACd,OAAO,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAEzC,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;CAMhC"}
+{"version":3,"file":"TransformControls.d.ts","sourceRoot":"","sources":["../../../../packages/controls/src/TransformControls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AACpE,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,OAAO,CAAC;AACtD,MAAM,MAAM,sBAAsB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAEtF,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;CACjC;AAED,mCAAmC;AACnC,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,eAAe,GAAG,aAAa,CAAC;IAC7E,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,EAAE,CAAC;IACrI,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,4BAA4B,CAAC;CAC9C;AAYD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAC5B,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAQ;IAC1C,IAAI,EAAE,oBAAoB,CAAe;IACzC,OAAO,UAAQ;IAEf,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,MAAM,CAAgD;IAC9D,OAAO,CAAC,WAAW,CAA2D;IAC9E,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,GAAE,wBAA6B;IAmBlD,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAMzC,MAAM,IAAI,IAAI;IAKd,OAAO,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAKzC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI;IAI5C,OAAO,CAAC,QAAQ,EAAE,4BAA4B,GAAG,IAAI;IASrD,0EAA0E;IAC1E,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAgB,GAAG,IAAI;IAO7H,KAAK,IAAI;QACP,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;QACpC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;QACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,QAAQ,CAAC,aAAa,EAAE,sBAAsB,GAAG,SAAS,CAAC;QAC3D,QAAQ,CAAC,YAAY,EAAE,sBAAsB,GAAG,SAAS,CAAC;QAC1D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;KAC/B;IAYD,iEAAiE;IACjE,OAAO,IAAI,SAAS,8BAA8B,EAAE;IAuEpD;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,mBAAmB,GAAG,oBAAoB,GAAG,SAAS;IAmBhE,+DAA+D;IAC/D,KAAK,CAAC,GAAG,EAAE,mBAAmB,GAAG,sBAAsB,GAAG,SAAS;IAMnE;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO;IAc9C;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,mBAAmB,GAAG,0BAA0B,GAAG,SAAS;IAiB7E,2DAA2D;IAC3D,SAAS,IAAI;QAAE,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IASjG,mFAAmF;IACnF,UAAU,IAAI,IAAI;IAMlB,4EAA4E;IAC5E,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAS/B,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,qBAAqB;IA2B7B,gDAAgD;IAChD,OAAO,CAAC,WAAW;IAYnB,0DAA0D;IAC1D,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,OAAO;IAsBf,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,QAAQ;CAejB"}