@needle-tools/engine 4.13.0 → 4.13.1-next.6cb1b73

package/src/engine-components/ShadowCatcher.ts

@@ -4,6 +4,9 @@ import { ObjectUtils, PrimitiveType } from "../engine/engine_create_objects.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { RGBAColor } from "../engine/js-extensions/index.js";
 import { Behaviour } from "./Component.js";
+import type { ContactShadows } from "./ContactShadows.js";
+import type { Light } from "./Light.js";
+import type { Renderer } from "./Renderer.js";
 
 /**
  * The mode of the ShadowCatcher.  
@@ -18,14 +21,66 @@ enum ShadowMode {
 }
 
 /**
- * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.    
- * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.  
- * 
- * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
- * 
- * @summary Creates a shadow mask or a light occluder 
+ * ShadowCatcher renders real-time shadows cast by lights onto a mesh surface.  
+ * Captures actual shadow data from the scene's lighting system (directional lights, point lights, spot lights).  
+ *
+ * If the GameObject is a Mesh, it applies a shadow-catching material to it.  
+ * Otherwise, it creates a quad mesh with the shadow-catching material automatically.  
+ *
+ * [![](https://cloud.needle.tools/-/media/pFXPchA4vynNKOjgG_KucQ.gif)](https://engine.needle.tools/samples/shadow-catcher/)   
+ * *Additive ShadowCatcher mode with point light shadows*  
+ *
+ * [![](https://cloud.needle.tools/-/media/oIWgEU49rEA0xJ2TrbzVlg.gif)](https://engine.needle.tools/samples/transmission/)   
+ * *ShadowCatcher with directional light shadows*
+ *
+ * **Shadow Modes:**  
+ * - `ShadowMask` - Only renders shadows (works best with directional lights)  
+ * - `Additive` - Renders light additively (works best with point/spot lights)
+ * - `Occluder` - Occludes light without rendering shadows
+ *
+ * **ShadowCatcher vs ContactShadows:**
+ * - **ShadowCatcher**: Real-time shadows from actual lights. Accurate directional shadows that match light sources. Requires lights with shadows enabled. Updates every frame.
+ * - **{@link ContactShadows}**: Proximity-based ambient occlusion-style shadows. Extremely soft and diffuse, ideal for subtle grounding. Better performance, works without lights.
+ *
+ * **When to use ShadowCatcher:**
+ * - You need accurate shadows that match specific light directions
+ * - Scene has real-time lighting with shadow-casting lights
+ * - Shadows need to follow light attenuation and angles
+ * - AR/VR scenarios where light estimation is available
+ * - Hard or semi-hard shadow edges are desired
+ *
+ * **When to use ContactShadows instead:**
+ * - You want very soft, ambient occlusion-style ground shadows
+ * - Performance is critical (no per-frame shadow rendering)
+ * - Scene doesn't have shadow-casting lights
+ * - Product visualization or configurators (subtle grounding effect)
+ * - Soft, diffuse shadows are more visually appealing than accurate ones
+ *
+ * **Note:** ShadowCatcher meshes are not raycastable by default (layer 2). Change layers in `onEnable()` if raycasting is needed.
+ *
+ * @example Basic shadow catcher plane
+ * ```ts
+ * const plane = new Object3D();
+ * const catcher = addComponent(plane, ShadowCatcher);
+ * catcher.mode = ShadowMode.ShadowMask;
+ * catcher.shadowColor = new RGBAColor(0, 0, 0, 0.8);
+ * ```
+ *
+ * @example Apply to existing mesh
+ * ```ts
+ * const mesh = this.gameObject.getComponent(Mesh);
+ * const catcher = addComponent(mesh, ShadowCatcher);
+ * // The mesh will now catch shadows from scene lights
+ * ```
+ *
+ * @summary Renders real-time shadows from lights onto surfaces
  * @category Rendering
  * @group Components
+ * @see {@link ContactShadows} for proximity-based fake shadows (better performance)
+ * @see {@link Light} for shadow-casting light configuration
+ * @see {@link Renderer} for shadow receiving settings
+ * @link https://engine.needle.tools/samples/shadow-catcher/
+ * @link https://engine.needle.tools/samples/transmission/
  */
 export class ShadowCatcher extends Behaviour {
 

package/src/engine-components/Skybox.ts

@@ -114,20 +114,52 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
 
 
 /**
- * RemoteSkybox is a component that allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.  
- * It supports .hdr, .exr, .jpg, .png files.
- * 
+ * The [RemoteSkybox](https://engine.needle.tools/docs/api/RemoteSkybox) component allows you to set the skybox or environment texture of a scene from a URL, a local file or a static skybox name.
+ * It supports .hdr, .exr, .jpg, .png, and .ktx2 files.
+ *
+ * **HTML Attributes:**
+ * You can control skybox and environment from HTML using `<needle-engine>` attributes:
+ * - `background-image`: Sets the scene background/skybox image
+ * - `environment-image`: Sets the scene environment map (for reflections and lighting)
+ *
+ * These attributes accept URLs or magic skybox names (see examples below).
+ *
+ * **Magic Skybox Names:**
+ * Built-in optimized skyboxes hosted on Needle CDN:
+ * - `"studio"` - Neutral studio lighting (default)
+ * - `"blurred-skybox"` - Blurred environment
+ * - `"quicklook"` - Apple QuickLook object mode style
+ * - `"quicklook-ar"` - Apple QuickLook AR mode style
+ *
  * ### Events
  * - `dropped-unknown-url`: Emitted when a file is dropped on the scene. The event detail contains the sender, the url and a function to apply the url.
- * 
- * @example adding a skybox
+ *
+ * @example Using HTML attributes
+ * ```html
+ * <needle-engine
+ *   background-image="https://example.com/skybox.hdr"
+ *   environment-image="studio">
+ * </needle-engine>
+ * ```
+ *
+ * @example Using magic skybox names
+ * ```html
+ * <needle-engine background-image="studio"></needle-engine>
+ * <needle-engine environment-image="quicklook"></needle-engine>
+ * ```
+ *
+ * @example Adding via code
  * ```ts
- * GameObject.addComponent(gameObject, Skybox, { url: "https://example.com/skybox.hdr", background: true, environment: true });
+ * GameObject.addComponent(gameObject, RemoteSkybox, {
+ *   url: "https://example.com/skybox.hdr",
+ *   background: true,
+ *   environment: true
+ * });
  * ```
- * 
- * @example handle custom url
+ *
+ * @example Handle custom dropped URL
  * ```ts
- * const skybox = GameObject.addComponent(gameObject, Skybox);
+ * const skybox = GameObject.addComponent(gameObject, RemoteSkybox);
  * skybox.addEventListener("dropped-unknown-url", (evt) => {
  *    let url = evt.detail.url;
  *    console.log("User dropped file", url);
@@ -137,15 +169,19 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  *    evt.detail.apply(url);
  * });
  * ```
- * 
- * @example update skybox url
+ *
+ * @example Update skybox at runtime
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
+ * // Or use a magic name:
+ * skybox.setSkybox("studio");
  * ```
- * 
+ *
  * @summary Sets the skybox or environment texture of a scene
  * @category Rendering
  * @group Components
+ * @see {@link Camera} for clearFlags and background control
+ * @link https://engine.needle.tools/docs/html.html#needle-engine-element
  */
 export class RemoteSkybox extends Behaviour {
 

package/src/engine-components/SmoothFollow.ts

@@ -4,14 +4,58 @@ import { Mathf } from "../engine/engine_math.js";
 import { Axes } from "../engine/engine_physics.types.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getWorldPosition, getWorldQuaternion } from "../engine/engine_three_utils.js";
+import type { LookAt } from "./api.js";
 import { Behaviour } from "./Component.js";
 
 /**
- * SmoothFollow makes the {@link Object3D} (`GameObject`) smoothly follow another target {@link Object3D}.  
- * It can follow the target's position, rotation, or both.   
- * @summary Smoothly follows a target object
+ * [SmoothFollow](https://engine.needle.tools/docs/api/SmoothFollow) makes this GameObject smoothly follow another target object's position and/or rotation.  
+ *
+ * **Position Following:**  
+ * When enabled (`followFactor > 0`), this object will move towards the target's world position.  
+ * The object interpolates from its current position to the target's position each frame.  
+ * Use `positionAxes` to restrict following to specific axes (e.g., only horizontal movement).  
+ *
+ * **Rotation Following:**  
+ * When enabled (`rotateFactor > 0`), this object will rotate to match the target's world rotation.  
+ * The object smoothly interpolates from its current rotation to the target's rotation each frame.  
+ * This makes the object face the same direction as the target, not look at it (use {@link LookAt} for that).  
+ *
+ * **Smoothing:**  
+ * Both position and rotation use time-based interpolation (lerp/slerp).  
+ * Higher factor values = faster following (less lag), lower values = slower following (more lag).  
+ * Set a factor to 0 to disable that type of following entirely.  
+ *
+ * **Common Use Cases:**  
+ * - Camera following a player character  
+ * - UI elements tracking world objects  
+ * - Delayed motion effects (ghost trails, spring arms)  
+ * - Smoothed object attachment  
+ *
+ * @example Follow a target with smooth position
+ * ```ts
+ * const follower = myObject.addComponent(SmoothFollow);
+ * follower.target = playerObject;
+ * follower.followFactor = 5;  // Higher = faster following
+ * follower.rotateFactor = 0;  // Don't follow rotation
+ * ```
+ *
+ * @example Follow only on horizontal plane
+ * ```ts
+ * follower.positionAxes = Axes.X | Axes.Z; // Follow X and Z only (no vertical)
+ * ```
+ *
+ * @example Follow both position and rotation
+ * ```ts
+ * follower.target = targetObject;
+ * follower.followFactor = 3;  // Smooth position following
+ * follower.rotateFactor = 2;  // Smooth rotation following
+ * ```
+ *
+ * @summary Smoothly follows a target object's position and/or rotation
  * @category Interactivity
  * @group Components
+ * @see {@link LookAtConstraint} for making an object look at a target (different from rotation following)
+ * @see {@link Mathf} for the interpolation used
  */
 export class SmoothFollow extends Behaviour {
 
@@ -22,21 +66,34 @@ export class SmoothFollow extends Behaviour {
     target: Object3D | null = null;
 
     /**
-     * The factor to smoothly follow the target's position.  
-     * The value is clamped between 0 and 1. If 0, the GameObject will not follow the target's position.  
+     * Speed factor for position following.
+     * Controls how quickly this object moves to match the target's position.
+     * Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
+     * Set to 0 to disable position following entirely.
+     * @default 0.1
      */
     @serializable()
     followFactor = .1;
+
     /**
-     * The factor to smoothly follow the target's rotation.   
-     * The value is clamped between 0 and 1. If 0, the GameObject will not follow the target's rotation.
+     * Speed factor for rotation following.
+     * Controls how quickly this object rotates to match the target's rotation.
+     * Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
+     * Set to 0 to disable rotation following entirely.
+     * @default 0.1
      */
     @serializable()
     rotateFactor = .1;
 
+    /**
+     * Which position axes to follow. Use bitwise OR to combine:
+     * `Axes.X | Axes.Y` follows only X and Y axes.
+     * @default Axes.All
+     */
     @serializable()
     positionAxes: Axes = Axes.All;
 
+    /** When true, rotates 180° around Y axis (useful for mirrored setups) */
     flipForward: boolean = false;
 
     private static _invertForward: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
@@ -49,6 +106,10 @@ export class SmoothFollow extends Behaviour {
         this.updateNow(false);
     }
 
+    /**
+     * Manually update the position/rotation to follow the target.
+     * @param hard If true, snaps instantly to target without smoothing
+     */
     updateNow(hard: boolean) {
         if (!this.target || this.target === this.gameObject) return;
         if (this.followFactor > 0) {

package/src/engine-components/SpatialTrigger.ts

@@ -24,11 +24,34 @@ function testMask(mask1, mask2) {
 }
 
 /**
- * Component that receives and responds to spatial events, like entering or exiting a trigger zone.
- * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.
+ * Component that receives and responds to spatial events, like entering or exiting a trigger zone.  
+ * Used in conjunction with {@link SpatialTrigger} to create interactive spatial events.  
+ *
+ * Place this on objects that should react when entering trigger zones. The receiver checks  
+ * against all active SpatialTriggers each frame and fires events when intersections change.  
+ *
+ * Events can be connected via {@link EventList} in the editor or listened to in code.  
+ *
+ * @example Listen to trigger events
+ * ```ts
+ * export class DoorTrigger extends Behaviour {
+ *   @serializable(SpatialTriggerReceiver)
+ *   receiver?: SpatialTriggerReceiver;
+ *
+ *   start() {
+ *     this.receiver?.onEnter?.addEventListener(() => {
+ *       console.log("Player entered door zone");
+ *     });
+ *   }
+ * }
+ * ```
+ *
  * @summary Receives spatial trigger events
  * @category Interactivity
  * @group Components
+ * @see {@link SpatialTrigger} for defining trigger zones
+ * @see {@link EventList} for event handling
+ * @link https://engine.needle.tools/samples/spatial-triggers/
  */
 export class SpatialTriggerReceiver extends Behaviour {
 
@@ -126,10 +149,34 @@ export class SpatialTriggerReceiver extends Behaviour {
 }
 
 /**
- * A spatial trigger component that detects objects within a box-shaped area.
- * Used to trigger events when objects enter, stay in, or exit the defined area
+ * A spatial trigger component that detects objects within a box-shaped area.  
+ * Used to trigger events when objects enter, stay in, or exit the defined area.  
+ *
+ * The trigger area is defined by the GameObject's bounding box (uses {@link BoxHelperComponent}).  
+ * Objects with {@link SpatialTriggerReceiver} components are tested against this area.  
+ *
+ * **Mask system:** Both trigger and receiver have a `triggerMask` - they only interact  
+ * when their masks have overlapping bits set. This allows selective triggering.  
+ *
+ * **Debug:** Use `?debugspatialtrigger` URL parameter to visualize trigger zones.  
+ *
+ * @example Create a pickup zone
+ * ```ts
+ * // On the pickup zone object
+ * const trigger = pickupZone.addComponent(SpatialTrigger);
+ * trigger.triggerMask = 1; // Layer 1 for pickups
+ *
+ * // On the player
+ * const receiver = player.addComponent(SpatialTriggerReceiver);
+ * receiver.triggerMask = 1; // Match the pickup layer
+ * ```
+ *
+ * @summary Define a trigger zone that detects entering objects
  * @category Interactivity
  * @group Components
+ * @see {@link SpatialTriggerReceiver} for objects that respond to triggers
+ * @see {@link BoxHelperComponent} for the underlying box used to define the trigger area
+ * @link https://engine.needle.tools/samples/spatial-triggers/
  */
 export class SpatialTrigger extends Behaviour {
 

package/src/engine-components/SpectatorCamera.ts

@@ -31,14 +31,32 @@ export enum SpectatorMode {
 const debug = getParam("debugspectator");
 
 /**
- * Provides functionality to follow and spectate other users in a networked environment.
- * Handles camera switching, following behavior, and network synchronization for spectator mode.
- * 
- * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
- * 
+ * SpectatorCamera enables following and spectating other users in networked sessions.  
+ * Switch between first-person (see what they see) and third-person (orbit around them) views.  
+ *
+ * **Keyboard controls** (when `useKeys = true`):  
+ * - `F` - Request all users to follow the local player
+ * - `ESC` - Stop spectating
+ *
+ * **Spectator modes:**  
+ * - `FirstPerson` - View from the followed player's perspective
+ * - `ThirdPerson` - Freely orbit around the followed player
+ *
+ * **Debug:** Use `?debugspectator` URL parameter for logging.
+ *
+ * @example Start spectating a user
+ * ```ts
+ * const spectator = camera.getComponent(SpectatorCamera);
+ * spectator.follow(targetUserId);
+ * spectator.mode = SpectatorMode.ThirdPerson;
+ * ```
+ *
  * @summary Spectator camera for following other users
  * @category Networking
  * @group Components
+ * @see {@link SpectatorMode} for view options
+ * @see {@link SyncedRoom} for networked sessions
+ * @see {@link OrbitControls} for third-person orbit
  */
 export class SpectatorCamera extends Behaviour {
 

package/src/engine-components/SyncedRoom.ts

@@ -11,8 +11,8 @@ const viewParamName = "view";
 const debug = utils.getParam("debugsyncedroom");
 
 /**
- * SyncedRoom is a behaviour that will attempt to join a networked room based on the URL parameters or a random room.  
- * It will also create a button in the menu to join or leave the room.  
+ * [SyncedRoom](https://engine.needle.tools/docs/api/SyncedRoom) is a behaviour that will attempt to join a networked room based on the URL parameters or a random room.
+ * It will also create a button in the menu to join or leave the room.
  * You can also join a networked room by calling the core methods like `this.context.connection.joinRoom("roomName")`.
  * 
  * @example Join a networked room
@@ -33,9 +33,15 @@ const debug = utils.getParam("debugsyncedroom");
  * myObject.addComponent(SyncedRoom, { joinRandomRoom: true, roomPrefix: "myApp_" });
  * ```
  * 
+ * **Debug:** Use `?debugsyncedroom` URL parameter for logging.
+ *
  * @summary Joins a networked room based on URL parameters or a random room
  * @category Networking
  * @group Components
+ * @see {@link SyncedTransform} for synchronizing object transforms
+ * @see {@link Voip} for voice communication in rooms
+ * @see {@link ScreenCapture} for screen/video sharing
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class SyncedRoom extends Behaviour {
 

package/src/engine-components/SyncedTransform.ts

@@ -55,12 +55,48 @@ onUpdate((ctx) => {
 })
 
 /**
- * SyncedTransform synchronizes the position and rotation of a game object over the network.
- * It handles ownership transfer, interpolation, and network state updates automatically.
- * 
+ * SyncedTransform synchronizes position and rotation of a GameObject across the network.
+ * When users interact with an object (e.g., via {@link DragControls}), they automatically
+ * take ownership and their changes are broadcast to other users.
+ *
+ * **Features:**
+ * - Automatic ownership transfer when interacting
+ * - Smooth interpolation of remote updates
+ * - Physics integration (can override kinematic state)
+ * - Fast mode for rapidly moving objects
+ *
+ * **Requirements:**
+ * - Active network connection via {@link SyncedRoom}
+ * - Objects must have unique GUIDs (set automatically in Unity/Blender export)
+ *
+ * **Ownership:**
+ * This component uses {@link OwnershipModel} internally to manage object ownership.
+ * Only the client that owns an object can send transform updates. Use `requestOwnership()`
+ * before modifying the transform, or check `hasOwnership()` to see if you can modify it.
+ *
+ * **Debug:** Use `?debugsync` URL parameter for logging.
+ *
+ * @example Basic networked object
+ * ```ts
+ * // Add to any object you want synced
+ * const sync = myObject.addComponent(SyncedTransform);
+ * sync.fastMode = true; // For fast-moving objects
+ *
+ * // Request ownership before modifying
+ * sync.requestOwnership();
+ * myObject.position.x += 1;
+ * ```
+ *
+ * - Example: https://engine.needle.tools/samples/collaborative-sandbox
+ *
  * @summary Synchronizes object transform over the network with ownership management
  * @category Networking
  * @group Components
+ * @see {@link SyncedRoom} for room/session management
+ * @see {@link OwnershipModel} for ownership management details
+ * @see {@link DragControls} for interactive dragging with sync
+ * @see {@link Duplicatable} for networked object spawning
+ * @link https://engine.needle.tools/docs/networking.html
  */
 export class SyncedTransform extends Behaviour {
 
@@ -94,9 +130,18 @@ export class SyncedTransform extends Behaviour {
     private _receivedFastUpdate: boolean = false;
     private _shouldRequestOwnership: boolean = false;
 
-    /** 
+    /**
      * Requests ownership of this object on the network.
      * You need to be connected to a room for this to work.
+     * Call this before modifying the object's transform to ensure your changes are synchronized.
+     *
+     * @example
+     * ```ts
+     * // Request ownership before modifying
+     * syncedTransform.requestOwnership();
+     * this.gameObject.position.y += 1;
+     * ```
+     * @see {@link OwnershipModel.requestOwnership} for more details
      */
     public requestOwnership() {
         if (debug)
@@ -110,25 +155,29 @@ export class SyncedTransform extends Behaviour {
     }
 
     /**
-     * Free ownership of this object on the network.  
-     * You need to be connected to a room for this to work.  
+     * Free ownership of this object on the network.
+     * You need to be connected to a room for this to work.
      * This will also be called automatically when the component is disabled.
+     * Call this when you're done modifying an object to allow other users to interact with it.
+     * @see {@link OwnershipModel.freeOwnership} for more details
      */
     public freeOwnership() {
         this._model?.freeOwnership();
     }
 
     /**
-     * Checks if this client has ownership of the object
-     * @returns true if this client has ownership, false if not, undefined if ownership state is unknown
+     * Checks if this client has ownership of the object.
+     * @returns `true` if this client has ownership, `false` if not, `undefined` if ownership state is unknown
+     * @see {@link OwnershipModel.hasOwnership} for more details
      */
     public hasOwnership(): boolean | undefined {
         return this._model?.hasOwnership ?? undefined;
     }
 
     /**
-     * Checks if the object is owned by any client
-     * @returns true if the object is owned, false if not, undefined if ownership state is unknown
+     * Checks if the object is owned by any client (local or remote).
+     * @returns `true` if the object is owned, `false` if not, `undefined` if ownership state is unknown
+     * @see {@link OwnershipModel.isOwned} for more details
      */
     public isOwned(): boolean | undefined {
         return this._model?.isOwned;

package/src/engine-components/TransformGizmo.ts

@@ -8,12 +8,39 @@ import { OrbitControls } from "./OrbitControls.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 
 /**
- * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
- * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
- * 
- * @summary Object manipulation gizmo for translating, rotating, and scaling
+ * 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 class TransformGizmo extends Behaviour {