SDK Integration & Usage Pattern

Describes the core pattern for using visual effects in the Aircada SDK inside Operator classes, and how to reference effect IDs and built-in effect types safely.
Published: 7/10/2026

To work with effects programmatically, you define an Operator class, capture references to the target ModelObject using @SceneObjectProperty(), and manipulate their attached effects using the .effects facade.

Example Integration Pattern

Here is the standard structural pattern for accessing and configuring an effect inside an Operator's setup hook:

typescript
import {
    Operator, Context, AircadaContext,
    SceneObjectProperty, ModelObject, Setup, StickerEffect
} from "@aircada/spec";
import { SceneEffectIds, SceneObjects } from "../registry/scene.generated";

@Operator({
    name: "Example Operator",
    type: "EXAMPLE_OPERATOR"
})
export class ExampleOperator {
    @Context()
    air!: AircadaContext;

    /**
     * References to the shoe models in the scene.
     * This allows the operator to be attached to or reference these specific objects.
     */
    @SceneObjectProperty()
    shoeModel: ModelObject = SceneObjects.SHOE_RIGHT;

    @Setup()
    setup() {
        this.shoeModel.effects.get<StickerEffect>(SceneEffectIds.STICKER_1)!.proportionalScalar = .5;
    }
}

Referencing Scene Effect IDs

Effect IDs should never be hardcoded as raw magic strings. Instead, they must be referenced through the automatically generated scene.registry.ts (or scene.generated.ts) file, which guarantees that all referenced IDs match the active scene configuration:

typescript
export const SceneEffectIds = {
  // OrbitEffect
  ORBIT_1: "petyov5eijp",
  // AutoFrameEffect
  AUTO_FRAME_1: "cefvivlqbsr",
  // StickerEffect
  STICKER_1: "szk50nk6t1",
  // StickerEffect
  STICKER_2: "9obluztx7wo"
} as const;

Built-In Effect Types

All standard, built-in effect type definitions (such as StickerEffect, OrbitEffect, AutoFrameEffect, etc.) can be imported directly from the @aircada/spec package to provide complete IDE type safety, autocomplete support, and property validation inside your operators.