@vladkrutenyuk/three-kvy-core/dist/umd/core/factory.d.ts

Everything you need to create any-complexity 3D apps with Three.js. Empower Three.js with a modular, lifecycle-managed context that seamlessly propagates through objects via reusable features providing structured logic.

import type * as THREE from "three";
import { IFeaturable } from "./Object3DFeaturablity";
import { Object3DFeature } from "./Object3DFeature";
/**
 * A static factory method that creates {@link Object3DFeature} and adds it to a given Three.js `Object3D` instance.
 * It uses a given feature class (not an instance) that extends {@link Object3DFeature}
 * with optional constructor parameters. Returns an instance of the provided feature class.
 * @param {THREE.Object3D} obj  - The target Three.js `Object3D` instance to which the feature is added.
 * @param {typeof Object3DFeature} Feature - The feature class to add, which extends {@link Object3DFeature}.
 * @param {object | undefined} props - An object containing parameters for the feature's constructor. Optional of feature implementation has no custom props in constructor.
 * @param {(feature: Object3DFeature) => void} [beforeAttach] - (optional) A callback invoked before attaching the feature
 * @returns {Object3DFeature} The created feature instance.
 */
export declare function addFeature<TObj extends THREE.Object3D, TFeature extends Object3DFeature<any, any>, TProps>(obj: TObj, Feature: new (object: IFeaturable, props: TProps) => TFeature, props: keyof TProps extends never ? undefined : TProps, beforeAttach?: (feature: TFeature) => void): TFeature;
export declare function addFeature<TObj extends THREE.Object3D, TFeature extends Object3DFeature<any, any>>(obj: TObj, Feature: new (object: IFeaturable) => TFeature): TFeature;
/**
 * A static method that retrieves a feature instance from the given object by its class (constructor). Returns first found such feature instance, or `null` if not.
 * @param {THREE.Object3D} obj - The target Three.js Object3D instance to search for the feature.
 * @param {typeof Object3DFeature} FeatureClass - The feature class (constructor) whose instance is being searched for. It must extends Object3DFeature.
 * @returns {Object3DFeature | null}
 */
export declare function getFeature<TObj extends THREE.Object3D, TFeatureClass extends typeof Object3DFeature>(obj: TObj, FeatureClass: TFeatureClass): InstanceType<TFeatureClass> | null;
/**
 * Finds a feature in the given object using a predicate function. Returns the first matching instance of `Object3DFeature` if found, otherwise `null`.
 * @param {THREE.Object3D} obj - The target Three.js `Object3D` instance to search within.
 * @param {(feature: Object3DFeature) => boolean} predicate - A predicate function that receives a feature instance as an argument and returns a boolean indicating whether the feature matches.
 * @returns {Object3DFeature | null}
 */
export declare function getFeatureBy<TObj extends THREE.Object3D, TFeature extends Object3DFeature>(obj: TObj, predicate: (feature: TFeature) => boolean): TFeature | null;
/**
 * Retrieves all features attached to a given object. Returns a copy of the feature list—an array of `Object3DFeature[]` instances—or `null` if no features were added.
 * @remarks Note that changing returned array won't affect anything. It returns a **COPY** of this object features list.
 * @param {THREE.Object3D} obj - The target Three.js `Object3D` instance.
 * @returns {Object3DFeature[] | null}
 */
export declare function getFeatures<TObj extends THREE.Object3D>(obj: TObj): Object3DFeature[] | null;
/**
 * Destroys and detaches all features from the given object, freeing associated resources.
 * If `recursively` is set to `true`, this method will apply cleanup recursively to the entire object hierarchy.
 * @param {THREE.Object3D} obj - The target Three.js `Object3D` instance.
 * @param {boolean} recursively  - (Optional) Default is `false`. A boolean flag indicating whether to apply this method recursively to the object's hierarchy.
 */
export declare function clear<TObj extends THREE.Object3D>(obj: TObj, recursively?: boolean): void;