The Effects Facade API

Detailed overview of the .effects collection object (EffectsCollectionFacade) and the underlying EffectFacade class that powers dynamic property reading and writing through JavaScript Proxies.
Published: 7/10/2026

Every 3D scene object exposes an .effects property of type EffectsCollectionFacade. This facade serves as a high-performance, type-safe API for querying and manipulating effects, complete with caching mechanisms optimized for frame-by-frame updates.

EffectsCollectionFacade API

The EffectsCollectionFacade provides the following core methods:

- get<T extends EffectFacade>(operatorIdOrName: string): T | undefined Retrieves an individual active effect by its unique operator ID or custom name. Uses a local cache map for extremely fast repeat access.

- getAll(): EffectFacade[] Retrieves all active effects attached to the object, automatically evicting any stale cache entries for deleted effects.

- find(predicate: (effect: EffectFacade, index: number, obj: EffectFacade[]) => boolean): EffectFacade | undefined Mimics standard Array.find behavior to easily locate an effect meeting a specific criteria.

- add<T extends EffectFacade>(effectSystemId: string): Promise<T | undefined> Programmatically attaches a new visual effect to the object using its system identifier (e.g. "fx_bloom") and registers it in the cache.

- remove(operatorIdOrName: string): boolean Removes an active effect from the object and cleans up its cache entry.

Under the Hood: EffectFacade & Dynamic Proxying

Each effect returned by the collection is wrapped in an EffectFacade class, which uses a JavaScript Proxy to dynamically read/write properties directly into the engine's plugin adapter layer:

- Property Redirection: Getting or setting a property on the facade (e.g. effect.proportionalScalar = 0.5) invokes the engine's getPropertyValue or setPropertyValue dynamically under the hood using the effect's ID.

- Property Name Mapping: The proxy handles name conversion maps automatically. For example, reading/writing effect.mix automatically remaps to the engine's internal "effectMixAmount" property.

- Dynamic Logic Nodes: The proxy checks if a field is a dynamic logic node (via FacadeProxyHelpers.resolveDynamicLogicNode) and returns it when appropriate, enabling direct execution or interaction.