Constructs a new TransformControls.
Creates the dedicated viewLayer and sceneModel, builds every handle / picker / helper SceneObject, and wires up pointer and camera listeners. If params.target is supplied, attaches to it immediately; otherwise the controls stay hidden until attach is called.
TransformControlsParams for this gizmo.
The axis of the handle currently being dragged, or null when
no drag is in progress.
true while a drag is in progress (between
onDragStart and
onDragEnd).
ReadonlyeventsTyped event emitters fired by this gizmo. See TransformControlsEvents.
The axis of the handle currently under the pointer, or null
when no handle is hovered. Updated by the pointer-move handler
before onChange fires.
ReadonlyidUnique id used as the ViewLayer and SceneModel id.
ReadonlysceneDedicated SceneModel that holds the gizmo's handle, picker, and helper meshes. Created during construction and destroyed by destroy.
ReadonlyviewThe View this gizmo lives in.
ReadonlyviewWhether debug logging is currently on.
World-space pivot snapshot taken at the most recent
pointerdown — read-only window onto the internal
_dragPivot. Read this from devtools mid-drag to verify the
rotate / scale origin matches the surface point you picked.
Returns the same reference each call (do not mutate).
Whether pointer interaction is enabled.
true when the gizmo's pivot came from an explicit
pivotWorld option on attach, false when it
fell back to the target's primary world-matrix translation.
If you supplied a pivot but this reads false, your
attach-time options chain dropped it somewhere.
The current interaction mode.
Current world-space pivot — read-only window onto the
internal _pivotWorld for diagnostics. Returns the same
reference each call (do not mutate).
The current rotation snap step in radians, or null when
rotation snap is disabled.
The current scale snap step as a multiplicative factor, or
null when scale snap is disabled.
Whether the X-axis handles are visible.
Whether the Y-axis handles are visible.
Whether the Z-axis handles are visible.
The current screen-space size in pixels.
The current coordinate space.
The current translation snap step in world units, or null
when translation snap is disabled.
Attaches a target.
Accepts a SceneObject (every
mesh of which transforms as a rigid group), a
SceneMesh, or a getMatrix / setMatrix adapter.
The gizmo's pivot — the rotation centre, scale origin, and the
world-space anchor the handles render around — is set from
options.pivotWorld when supplied (use the world position
returned by your picker so the gizmo appears exactly at the
surface point the user clicked). When omitted, the pivot
falls back to the target's primary world-matrix translation.
Translation drags move the pivot with the object; rotate and scale drags hold the pivot fixed as the operation's centre, which is what makes "rotate this object about the point I clicked" feel correct.
Fires onChange after the rig has been re-posed.
The TransformControlsTarget to manipulate.
Optionaloptions: { pivotWorld?: Vec3 }Optional attach options; pivotWorld sets
the gizmo's anchor.
Destroys this TransformControls.
Unregisters every pointer / mouse / camera listener, destroys
the dedicated sceneModel and viewLayer, and
releases all internal state. Idempotent — calling destroy
a second time is a no-op.
Detaches the current target and hides the gizmo.
Fires onChange.
Toggles verbose console logging during attach, pointerdown, and every drag transform.
Each log line is prefixed [TransformControls <id>] and
carries enough state to verify the pivot / drag-pivot /
per-mesh translation behaviour without poking at private
fields:
Switch on from the host (or from a devtools console on a
captured reference: transformControls.setDebug(true)) when
chasing pivot drift, snapshot mismatch, or mid-drag detach
issues.
Enables or disables pointer interaction with the gizmo.
When disabled the handles still render but do not respond to hover or drag input. Useful for guarding the controls during a transient host-app interaction (for example a modal dialog).
true to enable interaction, false to disable.
Sets the interaction mode.
Changes the visible handle set:
"translate" — axis arrows + plane handles + centre cube"rotate" — axis rings + view-aligned ring + trackball"scale" — axis sticks + plane handles + centre cube"none" — hides every handle without detachingClears any current hover state so a stale highlight from the previous mode does not persist. The next pointer move re-establishes hover for whatever handle the pointer is over.
Fires onChange.
The TransformControlsMode to switch to.
Sets the rotation-mode snap step, in radians.
Rotation drag angles are quantised to multiples of snap. Pass
null to disable snapping.
Fires onChange.
Snap step in radians, or null to disable.
Sets the scale-mode snap step, as a multiplicative factor.
A value of 0.1 snaps to 10% increments. Pass null to disable
snapping.
Fires onChange.
Snap step as a multiplicative factor, or null
to disable.
Shows or hides the X-axis handles in every mode.
Fires onChange.
true to show the X-axis handles, false to hide.
Shows or hides the Y-axis handles in every mode.
Fires onChange.
true to show the Y-axis handles, false to hide.
Shows or hides the Z-axis handles in every mode.
Fires onChange.
true to show the Z-axis handles, false to hide.
Sets the gizmo's screen-space size in pixels.
The handles render at approximately sizePx pixels on screen
regardless of camera distance — the controls recompute the
world-space scale on every camera change. Clamped to a minimum
of 8 pixels.
Fires onChange.
Target on-screen size in pixels.
Sets the coordinate space the controls operate in.
"world" aligns handles with the world axes; "local" aligns
them with the target's current rotation, so axis drags move /
rotate / scale along the target's own local frame.
Fires onChange.
The TransformControlsSpace to use.
Sets the translation-mode snap step, in world units.
Translation drag deltas are quantised to multiples of snap
along each axis. Pass null to disable snapping.
Fires onChange.
Snap step in world units, or null to disable.
StaticgetReturns the live TransformControls bound to the given
View, or undefined when none has
been created (or the last one was destroyed).
StaticiconSVG glyph used in toolbar buttons and context-menu rows that
activate the gizmo — a three-axis pivot. Strokes use
currentColor.
StaticopenIdempotent factory — returns the live
TransformControls for
params.view, or
constructs one. Use this in preference to direct
new TransformControls(...) when the host may already have
built a gizmo for the same View.
Interactive transform gizmo for a View.
Attaches to a SceneObject, SceneMesh, or matrix adapter, and lets the user translate, rotate, or scale the target through axis arrows, plane handles, rotation rings, and a view-aligned trackball.
The rig is built into a dedicated ViewLayer and SceneModel created in the supplied view's scene, so it does not interfere with the host scene's objects or visibility state. Handles render through an overlay bin (depth-cleared, depth-test always-pass) so they float over host geometry regardless of where the target sits in world space.
Modes
Ering, or theXYZEtrackball.Coordinate spaces
setSpace("world") aligns the handles with the world axes; setSpace("local") aligns them with the target's current rotation.
Sizing and snap
setSize sets a target screen-space size in pixels. The controls recompute world-space scale on every camera change so the rig stays a constant pixel size regardless of camera distance.
setTranslationSnap, setRotationSnap, and setScaleSnap quantise drag deltas; pass
nullto disable.Events
Subscribe to TransformControls.events for
onDragStart,onDragEnd,onChange, andonObjectChange. See TransformControlsEvents.Picking
Drag interaction requires a PickStrategy, supplied via TransformControlsParams.picker. Without one the handles render but cannot be grabbed.