Feature Methods

The following static factory methods are used to manage object features.

Adding Features

Use the static method addFeature to add a feature to an instance of Three.js Object3D. Pass a feature class (not an instance) that extends Object3DFeature, with an optional object containing parameters for its constructor.

const obj = new THREE.Object3D();

const feature = KVY.addFeature(obj, FeatureExample, { speed: 3 });

ctx.root.add(obj);

const another = KVY.addFeature(obj, AnotherFeature, { name: "Vitalik" });
another.name = "Rohalik";

KVY.addFeature(obj, FeatureWithoutProps);

Retrieving Features

Use the static method getFeature to find a feature by its class, getFeatureBy to find one using a custom predicate, or getFeatures to get all features attached to an object.

const simpleMovement = KVY.getFeature(obj, YourSimpleMovement);
const someOtherFeature = KVY.getFeatureBy(obj, (x) => x.isSmth);

KVY.getFeatures(obj)?.forEach((feature) => {
    console.log(feature);
})

Clearing Features

Use the static method clear to destroy and detach all features from the given object, freeing associated resources and removing its feature capabilities. This method can also be applied recursively to an entire object hierarchy for efficient cleanup.

KVY.clear(obj);

API

addFeature( obj: Object3D, Feature: class Object3DFeature, props?: Object ): Object3DFeature

A static factory method that adds a feature to a Three.js Object3D instance. It uses a given feature class (not an instance) that extends Object3DFeature, with optional constructor parameters. Returns an instance of the provided feature class.

• obj - The target Three.js Object3D instance to which the feature is added.
• Feature - The feature class to add, which extends Object3DFeature.
• props - (Optional) An object containing parameters for the feature's constructor.

getFeature( obj: Object3D, Feature: class Object3DFeature ): Object3DFeature | null

A static method that retrieves a feature instance from the given object by its class (constructor). Returns such feature instance if found, or null if not.

• obj - The target Three.js Object3D instance to search for the feature.
• Feature - The feature class (constructor) whose instance is being searched for. It must extends Object3DFeature.

getFeatureBy( obj: Object3D, predicate: Function ): Object3DFeature | null

Finds a feature in the given object using a predicate function. Returns an instance of Object3DFeature if found, otherwise null.

• obj - The target Three.js Object3D instance to search within.
• predicate - A predicate function that receives a feature instance as an argument and returns a boolean indicating whether the feature matches.

getFeatures( obj: Object3D ): Object3DFeature[] | 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. Note that changing returned array won't affect anything. It returns a COPY of this object features list.

• obj - The target Three.js Object3D instance.

clear( obj: Object3D, recursively?: boolean ): void

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.

• obj - The target Three.js Object3D instance.
• recursively - (Optional) Default is false. A boolean flag indicating whether to apply this method recursively to the object's hierarchy.