@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.
128 lines (127 loc) • 5.07 kB
TypeScript
import { InstantiateContext } from "../engine/engine_gameobject.js";
import type { IEventList } from "../engine/engine_types.js";
/**
* CallInfo represents a single callback method that can be invoked by the {@link EventList}.
*/
export declare class CallInfo {
/**
* When the CallInfo is enabled it will be invoked when the EventList is invoked
*/
enabled: boolean;
/**
* The target object to invoke the method on OR the function to invoke
*/
target: Object | Function;
methodName: string | null;
/**
* The arguments to invoke this method with
*/
arguments?: Array<any>;
get canClone(): boolean;
constructor(target: Function);
constructor(target: Object, methodName: string | null, args?: Array<any>, enabled?: boolean);
invoke(...args: any): void;
}
export declare class EventListEvent<TArgs extends any> extends Event {
args?: TArgs;
}
/**
* EventList manages a list of callbacks that can be invoked together.
* Used for Unity-style events that can be configured in the editor (Unity or Blender).
*
* **Serialization:**
* EventLists are serializable - callbacks configured in Unity/Blender will work at runtime.
* Mark fields with `@serializable(EventList)` for editor support.
*
* **Usage patterns:**
* - Button click handlers
* - Animation events
* - Custom component callbacks
* - Scene loading events
*
* 
* *Screenshot of a Unity component with an EventList field*
*
* 
* *Screenshot of a Blender component with an EventList field*
*
* @example Create and use an EventList
* ```ts
* // Define in your component
* @serializable(EventList)
* onClick: EventList = new EventList();
*
* // Add listeners
* this.onClick.addEventListener(() => console.log("Clicked!"));
*
* // Invoke all listeners
* this.onClick.invoke();
* ```
*
* @example Listen with arguments
* ```ts
* const onScore = new EventList<{ points: number }>();
* onScore.addEventListener(data => console.log("Scored:", data.points));
* onScore.invoke({ points: 100 });
* ```
*
* @category Events
* @group Utilities
* @see {@link CallInfo} for individual callback configuration
* @see {@link Button} for UI button events
*/
export declare class EventList<TArgs extends any = any> implements IEventList {
/** checked during instantiate to create a new instance */
readonly isEventList = true;
/**
* @internal Used by the Needle Engine instantiate call to remap the event listeners to the new instance
*/
__internalOnInstantiate(ctx: InstantiateContext): EventList<any>;
private target?;
private key?;
/** set an event target to try invoke the EventTarget dispatchEvent when this EventList is invoked */
setEventTarget(key: string, target: object): void;
/** How many callback methods are subscribed to this event */
get listenerCount(): number;
/** If the event is currently being invoked */
get isInvoking(): boolean;
private _isInvoking;
private readonly methods;
private readonly _methodsCopy;
/**
* Create a new EventList with the given callback methods. You can pass either CallInfo instances or functions directly.
* @returns a new EventList instance with the given callback methods
* @example
* ```ts
* const onClick = EventList.from(
* () => console.log("Clicked!"),
* new CallInfo(someObject, "someMethod", [arg1, arg2])
* );
* onClick.invoke();
* ```
*/
static from(...evts: Array<Function>): EventList<any>;
/**
* Create a new EventList with the given callback methods. You can pass either CallInfo instances or functions directly.
* @returns a new EventList instance with the given callback methods
*/
constructor(evts?: Array<CallInfo | Function> | Function);
/** Invoke all the methods that are subscribed to this event
* @param args optional arguments to pass to the event listeners. These will be passed before any custom arguments defined in the CallInfo instances. So if you have a CallInfo with arguments and you also pass arguments to invoke, the arguments passed to invoke will take precedence over the CallInfo arguments.
* @returns true if the event was successfully invoked, false if there are no listeners or if a circular invocation was detected
*/
invoke(...args: Array<TArgs>): boolean;
/** Add a new event listener to this event
* @returns a function to remove the event listener
*/
addEventListener(callback: (args: TArgs) => void): Function;
/**
* Remove an event listener from this event.
* @returns true if the event listener was found and removed, false otherwise
*/
removeEventListener(fn: Function | null | undefined): boolean;
/**
* Remove all event listeners from this event. Use with caution! This will remove all listeners!
*/
removeAllEventListeners(): void;
}