Particles Object Facade (ParticlesObject)

Detailed specification of the ParticlesObject facade in the Aircada SDK, providing control over particle emission states, visibility, and pipeline data streaming.

Published: 7/10/2026

The ParticlesObject represents a dynamic particle system emitter in the 3D scene (e.g. smoke, sparks, dust, or custom weather systems, type: 'PARTICLES'). It extends the base ISceneObject interface and exposes controls to toggle particle emission streams and route pipeline data.

Developers declare relationships to ParticlesObject instances using the @SceneObjectProperty() decorator. Once hydrated, Operators can dynamically start/stop particle flows, position the emitter, and respond to user clicks on the emitter hub.

Example: Turning Emitters On and Off#

Example illustrating using action inputs to trigger particle emission states.

Example showing how to stop emission dynamically on a ParticlesObject.

typescript

// Stop smoke or steam emission dynamically
this.smokeEmitter.hide();

Stopping particle emission on smokeEmitter by calling hide().

Example: Interactive Flow Toggle & Memory Teardown#

Example illustrating how to bind click events to ParticlesObjects to toggle emissions, and cleanly unsubscribe using the Dispose pattern.

Example showing how to subscribe to click events on a ParticlesObject emitter to toggle flow and dispose listeners correctly.

VaporToggle.ts (typescript)

import { Setup, Dispose, Operator, SceneObjectProperty, ParticlesObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";

@Operator({
    name: "Vapor Interactive Toggle",
    type: "VAPOR_INTERACTIVE_TOGGLE"
})
export class VaporToggle {
    // Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
    @SceneObjectProperty()
    steamEmitter: ParticlesObject = SceneObjects.STEAM_EMITTER_1;

    private unsubscribeToClick?: () => void;
    private isFlowing: boolean = true;

    @Setup()
    setup() {
        // Attach click listener and save unsubscribe callback
        this.unsubscribeToClick = this.steamEmitter.onClick.addListener(() => {
            console.log("Emitter hub clicked! Toggling flow...");
            this.isFlowing = !this.isFlowing;
            if (this.isFlowing) {
                this.steamEmitter.show();
            } else {
                this.steamEmitter.hide();
            }
        });
    }

    @Dispose()
    dispose() {
        // Prevent memory leaks by cleaning up the listener
        this.unsubscribeToClick?.();
    }
}

Operator class toggling emission on steamEmitter click and unsubscribing in dispose.

Example: Declaring a ParticlesObject#

Example showing how to declare and target a ParticlesObject property inside an Operator.

Example showing how to target a ParticlesObject and start emission during setup.

VaporController.ts (typescript)

import { Setup, Operator, SceneObjectProperty, ParticlesObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";

@Operator({
    name: "Vapor System Controller",
    type: "VAPOR_SYSTEM_CONTROLLER"
})
export class VaporController {
    // Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
    @SceneObjectProperty()
    smokeEmitter: ParticlesObject = SceneObjects.SMOKE_EMITTER_1;

    @Setup()
    setup() {
        // Turn on steam emissions on startup
        this.smokeEmitter.show();
    }
}

Operator class declaring smokeEmitter property as a ParticlesObject and enabling it.

ParticlesObject Action Inputs (@Input)#

Control methods exposed as inputs on ParticlesObject instances to toggle emitter visibility and flows.

Inputs represent imperative commands that can be called on ParticlesObject facades:

Available Inputs:

- show(): Enables particle spawn emission (turns the flow ON).

- hide(): Stops particle spawn emission (turns the flow OFF).

- dataInput(payload: DataBlock[]): Streams dynamic data blocks to drive visual densities or flow speeds.

show(): Starts particle emission flow.
hide(): Stops new particle emission.
dataInput(payload): Dynamic pipeline data intake.

ParticlesObject Event Outputs (@Output)#

Asynchronous event channels capturing click interactions on particle emitters.

Outputs allow Operators to subscribe to reactive runtime events dispatched by the ParticlesObject:

Available Outputs:

- onClick: AirEvent<void>: Fired once upon completing a click interaction on the particle emitter hub.

- whileHeld: AirEvent<void>: Dispatched continuously every tick while the user maintains an active select on the emitter hub.

- onRelease: AirEvent<void>: Dispatched when a click, select, or hold gesture is ended.

- dataOutput: AirEvent<DataBlock[]>: Emits custom pipeline values downstream to other nodes.

onClick: Pointer click trigger on the emitter hub.
whileHeld: Pointer hold interaction stream.
onRelease: Hold ended trigger.
dataOutput: Custom pipeline event emitter for transferring serializable states.

ParticlesObject Direct Properties#

Understanding the data-driven configuration of particle emission behaviors.

A ParticlesObject relies primarily on pre-configured visual properties defined within the Aircada Studio. Because particles represent intensive visual effects, complex settings like speed, spread, gravity, and scale are managed within the visual editor to optimize GPU pipeline performance.

Key Architectural Characteristics:

- Optimized GPU Pipeline: Core textures, gravity vectors, lifetimes, and spawn limits are baked into visual configurations to run directly in shaders.

- Data-Driven Control: Developers use runtime inputs (show(), hide(), dataInput()) to toggle states and pass streaming data arrays to manipulate particles programmatically.

GPU Optimization: High-performance rendering driven by visual configuration parameters.
Programmatic Interface: Operations are managed through dynamic action inputs rather than individual parameter mutation.

Transform and Effects Facades#

Overview of child facades hosted by ParticlesObject instances for spatial offsets and highlight shaders.

Every ParticlesObject hosts sub-facades to delegate spatial coordinates and custom post-processing layers:

- .transform: Coordinates spatial positioning, scaling, and rotation of the particle emitter hub. (See the 3D Transforms & Coordinates reference guide).

- .effects: Configures custom post-processing layers on the emitter assembly. For complete details, see the The Effects Facade API reference guide.

> [!NOTE] > Unlike geometry meshes, particle system facades do not host a .material facade.