@needle-tools/engine 4.11.5-next.f5ee735 → 4.11.6

package/lib/engine-components/DropListener.d.ts

@@ -1,224 +1,224 @@
-import { Object3D, Vector3 } from "three";
-import { Model, Vec3 } from "../engine/engine_types.js";
-import { Behaviour } from "./Component.js";
-import { EventList } from "./EventList.js";
-/**
- * Events dispatched by the DropListener component
- * @enum {string}
- */
-export declare enum DropListenerEvents {
-    /**
-     * Dispatched when a file is dropped into the scene. The detail of the event is the {@link File} that was dropped.
-     * The event is called once for each dropped file.
-     */
-    FileDropped = "file-dropped",
-    /**
-     * Dispatched when a new object is added to the scene. The detail of the event contains {@link DropListenerOnDropArguments} for the content that was added.
-     */
-    ObjectAdded = "object-added"
-}
-/**
- * Network event arguments passed between clients when using the DropListener with networking
- */
-export declare type DropListenerNetworkEventArguments = {
-    /** Unique identifier of the sender */
-    guid: string;
-    /** Name of the dropped object */
-    name: string;
-    /** URL or array of URLs to the dropped content */
-    url: string | string[];
-    /** Worldspace point where the object was placed in the scene */
-    point: Vec3;
-    /** Bounding box size */
-    size: Vec3;
-    /** MD5 hash of the content for verification */
-    contentMD5: string;
-};
-/**
- * Arguments provided to handlers when an object is dropped or added to the scene
- */
-export declare type DropListenerOnDropArguments = {
-    /** The DropListener component that processed the drop event */
-    sender: DropListener;
-    /** The root object added to the scene */
-    object: Object3D;
-    /** The complete model with all associated data */
-    model: Model;
-    /** MD5 hash of the content for verification */
-    contentMD5: string;
-    /** The original dropped URL or File object */
-    dropped: URL | File | undefined;
-};
-/** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene
- * It can be used to allow users to drag and drop glTF files into the scene to add new objects.
- *
- * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
- * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
- *
- * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
- *
- * The following events are dispatched by the DropListener:
- * - **object-added** - dispatched when a new object is added to the scene
- * - **file-dropped** - dispatched when a file is dropped into the scene
- *
- * @example
- * ```typescript
- * import { DropListener, DropListenerEvents } from "@needle-tools/engine";
- *
- * const dropListener = new DropListener();
- *
- * gameObject.addComponent(dropListener);
- * dropListener.on(DropListenerEvents.FileDropped, (evt) => {
- *   console.log("File dropped", evt.detail);
- *   const file = evt.detail as File;
- * });
- *
- * dropListener.on(DropListenerEvents.ObjectAdded, (evt) => {
- *    console.log("Object added", evt.detail);
- *    const gltf = evt.detail as GLTF;
- * });
- * ```
- *
- * @category Asset Management
- * @group Components
- */
-export declare class DropListener extends Behaviour {
-    /**
-     * When assigned, the DropListener will only accept files that are dropped on this specific object.
-     * This allows creating designated drop zones in your scene.
-     */
-    dropArea?: Object3D;
-    /**
-     * When enabled, dropped objects will be automatically scaled to fit within the volume defined by fitVolumeSize.
-     * Useful for ensuring dropped models appear at an appropriate scale.
-     *
-     * **Tip**: Use the handy `fitObjectIntoVolume` function (`import { fitObjectIntoVolume } from "@needle-tools/engine"`) for custom fitting needs.
-     *
-     * @default false
-     */
-    fitIntoVolume: boolean;
-    /**
-     * Defines the dimensions of the volume that dropped objects will be scaled to fit within.
-     * Only used when fitIntoVolume is enabled.
-     */
-    fitVolumeSize: Vector3;
-    /**
-     * When enabled, dropped objects will be positioned at the point where the cursor hit the scene.
-     * When disabled, objects will be placed at the origin of the DropListener.
-     * @default true
-     */
-    placeAtHitPosition: boolean;
-    /**
-     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
-     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
-     * @default false
-     */
-    useNetworking: boolean;
-    /**
-     * Event list that gets invoked after a file has been successfully added to the scene.
-     * Receives {@link DropListenerOnDropArguments} containing the added object and related information.
-     * @event object-added
-     * @example
-     * ```typescript
-     * dropListener.onDropped.addEventListener((evt) => {
-     *  console.log("Object added", evt.model);
-     * });
-     */
-    onDropped: EventList<DropListenerOnDropArguments>;
-    /**
-     * Loads a file from the given URL and adds it to the scene.
-     * @returns A promise that resolves to the loaded object or null if loading failed.
-     */
-    loadFromURL(url: string, data?: {
-        point?: Vec3;
-        size?: Vec3;
-    }): Promise<Object3D | null>;
-    /**
-     * Forgets all previously added objects.
-     * The droplistener will then not be able to remove previously added objects.
-     */
-    forgetObjects(): void;
-    awake(): void;
-    /** @internal */
-    onEnable(): void;
-    /** @internal */
-    onDisable(): void;
-    /**
-     * Handles network events received from other clients containing information about dropped objects
-     * @param evt Network event data containing object information, position, and content URL
-     */
-    private onNetworkEvent;
-    /**
-     * Handles clipboard paste events and processes them as potential URL drops
-     * Only URLs are processed by this handler, and only when editing is allowed
-     * @param evt The paste event
-     */
-    private handlePaste;
-    /**
-     * Handles drag events over the renderer's canvas
-     * Prevents default behavior to enable drop events
-     * @param evt The drag event
-     */
-    private onDrag;
-    /**
-     * Processes drop events to add files to the scene
-     * Handles both file drops and text/URL drops
-     * @param evt The drop event
-     */
-    private onDrop;
-    /**
-     * Processes a dropped or pasted URL and tries to load it as a 3D model
-     * Handles special cases like GitHub URLs and Polyhaven asset URLs
-     * @param url The URL to process
-     * @param ctx Context information about where the drop occurred
-     * @param isRemote Whether this URL was shared from a remote client
-     * @returns The added object or null if loading failed
-     */
-    private addFromUrl;
-    private _abort;
-    /**
-     * Processes dropped files and loads them as 3D models.
-     * When enabled, it also handles network drops (sending files between clients).
-     * Automatically handles cancelling previous uploads if new files are dropped.
-     * @param fileList Array of dropped files
-     * @param ctx Context information about where on the screen or in 3D space the drop occurred
-     */
-    private addFromFiles;
-    /** Previously added objects */
-    private readonly _addedObjects;
-    private readonly _addedModels;
-    /**
-     * Removes all previously added objects from the scene
-     * @param doDestroy When true, destroys the objects; when false, just clears the references
-     */
-    private removePreviouslyAddedObjects;
-    /**
-     * Adds a loaded model to the scene with proper positioning and scaling.
-     * Handles placement based on component settings and raycasting.
-     * If {@link fitIntoVolume} is enabled, the object will be scaled to fit within the volume defined by {@link fitVolumeSize}.
-     * @param data The loaded model data and content hash
-     * @param ctx Context information about where the drop occurred
-     * @param isRemote Whether this object was shared from a remote client
-     * @returns The added object or null if adding failed
-     */
-    private onObjectLoaded;
-    /**
-     * Sends a network event to other clients about a dropped object
-     * Only triggered when networking is enabled and the connection is established
-     * @param url The URL to the content that was dropped
-     * @param obj The object that was added to the scene
-     * @param contentmd5 The content hash for verification
-     */
-    private sendDropEvent;
-    /**
-     * Deletes remote state for this DropListener's objects
-     * Called when new files are dropped to clean up previous state
-     */
-    private deleteDropEvent;
-    /**
-     * Tests if a drop event occurred within the designated drop area if one is specified
-     * @param ctx The drop context containing screen position information
-     * @returns True if the drop is valid (either no drop area is set or the drop occurred inside it)
-     */
-    private testIfIsInDropArea;
-}
+import { Object3D, Vector3 } from "three";
+import { Model, Vec3 } from "../engine/engine_types.js";
+import { Behaviour } from "./Component.js";
+import { EventList } from "./EventList.js";
+/**
+ * Events dispatched by the DropListener component
+ * @enum {string}
+ */
+export declare enum DropListenerEvents {
+    /**
+     * Dispatched when a file is dropped into the scene. The detail of the event is the {@link File} that was dropped.
+     * The event is called once for each dropped file.
+     */
+    FileDropped = "file-dropped",
+    /**
+     * Dispatched when a new object is added to the scene. The detail of the event contains {@link DropListenerOnDropArguments} for the content that was added.
+     */
+    ObjectAdded = "object-added"
+}
+/**
+ * Network event arguments passed between clients when using the DropListener with networking
+ */
+export declare type DropListenerNetworkEventArguments = {
+    /** Unique identifier of the sender */
+    guid: string;
+    /** Name of the dropped object */
+    name: string;
+    /** URL or array of URLs to the dropped content */
+    url: string | string[];
+    /** Worldspace point where the object was placed in the scene */
+    point: Vec3;
+    /** Bounding box size */
+    size: Vec3;
+    /** MD5 hash of the content for verification */
+    contentMD5: string;
+};
+/**
+ * Arguments provided to handlers when an object is dropped or added to the scene
+ */
+export declare type DropListenerOnDropArguments = {
+    /** The DropListener component that processed the drop event */
+    sender: DropListener;
+    /** The root object added to the scene */
+    object: Object3D;
+    /** The complete model with all associated data */
+    model: Model;
+    /** MD5 hash of the content for verification */
+    contentMD5: string;
+    /** The original dropped URL or File object */
+    dropped: URL | File | undefined;
+};
+/** The DropListener component is used to listen for drag and drop events in the browser and add the dropped files to the scene
+ * It can be used to allow users to drag and drop glTF files into the scene to add new objects.
+ *
+ * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
+ * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
+ *
+ * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
+ *
+ * The following events are dispatched by the DropListener:
+ * - **object-added** - dispatched when a new object is added to the scene
+ * - **file-dropped** - dispatched when a file is dropped into the scene
+ *
+ * @example
+ * ```typescript
+ * import { DropListener, DropListenerEvents } from "@needle-tools/engine";
+ *
+ * const dropListener = new DropListener();
+ *
+ * gameObject.addComponent(dropListener);
+ * dropListener.on(DropListenerEvents.FileDropped, (evt) => {
+ *   console.log("File dropped", evt.detail);
+ *   const file = evt.detail as File;
+ * });
+ *
+ * dropListener.on(DropListenerEvents.ObjectAdded, (evt) => {
+ *    console.log("Object added", evt.detail);
+ *    const gltf = evt.detail as GLTF;
+ * });
+ * ```
+ *
+ * @category Asset Management
+ * @group Components
+ */
+export declare class DropListener extends Behaviour {
+    /**
+     * When assigned, the DropListener will only accept files that are dropped on this specific object.
+     * This allows creating designated drop zones in your scene.
+     */
+    dropArea?: Object3D;
+    /**
+     * When enabled, dropped objects will be automatically scaled to fit within the volume defined by fitVolumeSize.
+     * Useful for ensuring dropped models appear at an appropriate scale.
+     *
+     * **Tip**: Use the handy `fitObjectIntoVolume` function (`import { fitObjectIntoVolume } from "@needle-tools/engine"`) for custom fitting needs.
+     *
+     * @default false
+     */
+    fitIntoVolume: boolean;
+    /**
+     * Defines the dimensions of the volume that dropped objects will be scaled to fit within.
+     * Only used when fitIntoVolume is enabled.
+     */
+    fitVolumeSize: Vector3;
+    /**
+     * When enabled, dropped objects will be positioned at the point where the cursor hit the scene.
+     * When disabled, objects will be placed at the origin of the DropListener.
+     * @default true
+     */
+    placeAtHitPosition: boolean;
+    /**
+     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
+     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
+     * @default false
+     */
+    useNetworking: boolean;
+    /**
+     * Event list that gets invoked after a file has been successfully added to the scene.
+     * Receives {@link DropListenerOnDropArguments} containing the added object and related information.
+     * @event object-added
+     * @example
+     * ```typescript
+     * dropListener.onDropped.addEventListener((evt) => {
+     *  console.log("Object added", evt.model);
+     * });
+     */
+    onDropped: EventList<DropListenerOnDropArguments>;
+    /**
+     * Loads a file from the given URL and adds it to the scene.
+     * @returns A promise that resolves to the loaded object or null if loading failed.
+     */
+    loadFromURL(url: string, data?: {
+        point?: Vec3;
+        size?: Vec3;
+    }): Promise<Object3D | null>;
+    /**
+     * Forgets all previously added objects.
+     * The droplistener will then not be able to remove previously added objects.
+     */
+    forgetObjects(): void;
+    awake(): void;
+    /** @internal */
+    onEnable(): void;
+    /** @internal */
+    onDisable(): void;
+    /**
+     * Handles network events received from other clients containing information about dropped objects
+     * @param evt Network event data containing object information, position, and content URL
+     */
+    private onNetworkEvent;
+    /**
+     * Handles clipboard paste events and processes them as potential URL drops
+     * Only URLs are processed by this handler, and only when editing is allowed
+     * @param evt The paste event
+     */
+    private handlePaste;
+    /**
+     * Handles drag events over the renderer's canvas
+     * Prevents default behavior to enable drop events
+     * @param evt The drag event
+     */
+    private onDrag;
+    /**
+     * Processes drop events to add files to the scene
+     * Handles both file drops and text/URL drops
+     * @param evt The drop event
+     */
+    private onDrop;
+    /**
+     * Processes a dropped or pasted URL and tries to load it as a 3D model
+     * Handles special cases like GitHub URLs and Polyhaven asset URLs
+     * @param url The URL to process
+     * @param ctx Context information about where the drop occurred
+     * @param isRemote Whether this URL was shared from a remote client
+     * @returns The added object or null if loading failed
+     */
+    private addFromUrl;
+    private _abort;
+    /**
+     * Processes dropped files and loads them as 3D models.
+     * When enabled, it also handles network drops (sending files between clients).
+     * Automatically handles cancelling previous uploads if new files are dropped.
+     * @param fileList Array of dropped files
+     * @param ctx Context information about where on the screen or in 3D space the drop occurred
+     */
+    private addFromFiles;
+    /** Previously added objects */
+    private readonly _addedObjects;
+    private readonly _addedModels;
+    /**
+     * Removes all previously added objects from the scene
+     * @param doDestroy When true, destroys the objects; when false, just clears the references
+     */
+    private removePreviouslyAddedObjects;
+    /**
+     * Adds a loaded model to the scene with proper positioning and scaling.
+     * Handles placement based on component settings and raycasting.
+     * If {@link fitIntoVolume} is enabled, the object will be scaled to fit within the volume defined by {@link fitVolumeSize}.
+     * @param data The loaded model data and content hash
+     * @param ctx Context information about where the drop occurred
+     * @param isRemote Whether this object was shared from a remote client
+     * @returns The added object or null if adding failed
+     */
+    private onObjectLoaded;
+    /**
+     * Sends a network event to other clients about a dropped object
+     * Only triggered when networking is enabled and the connection is established
+     * @param url The URL to the content that was dropped
+     * @param obj The object that was added to the scene
+     * @param contentmd5 The content hash for verification
+     */
+    private sendDropEvent;
+    /**
+     * Deletes remote state for this DropListener's objects
+     * Called when new files are dropped to clean up previous state
+     */
+    private deleteDropEvent;
+    /**
+     * Tests if a drop event occurred within the designated drop area if one is specified
+     * @param ctx The drop context containing screen position information
+     * @returns True if the drop is valid (either no drop area is set or the drop occurred inside it)
+     */
+    private testIfIsInDropArea;
+}