@needle-tools/engine
Version:
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.
216 lines (215 loc) • 8.82 kB
TypeScript
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}.
*
* 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 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.
*/
useNetworking: boolean;
/**
* 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.
* @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;
/**
* 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>;
/** @internal */
onEnable(): void;
/** @internal */
onDisable(): void;
/**
* Loads a file from the given URL and adds it to the scene.
*/
loadFromURL(url: string, data?: {
point?: Vec3;
size?: Vec3;
}): void;
/**
* Forgets all previously added objects.
* The droplistener will then not be able to remove previously added objects.
*/
forgetObjects(): 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, loads them as 3D models, and handles networking if enabled
* Creates an abort controller to cancel previous uploads if new files are dropped
* @param fileList Array of dropped files
* @param ctx Context information about where the drop occurred
*/
private addDroppedFiles;
/** 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 addObject;
/**
* 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;
}