3D Scene

Overview of the 3D scene architecture, bridging visual configurations from the Aircada Studio to strongly-typed SDK Operator references.
Published: 7/10/2026

Aircada separates visual scene composition from logic implementation. All 3D objects, materials, and world settings are defined within the Studio environment.

The Aircada CLI processes this scene data to generate src/registry/scene.registry, a comprehensive bridge that allows Operators to reference scene objects with full TypeScript safety.

To ensure clean development, the registry is architected into three layers: Raw IDs, Operator Refs (Facades), and Data Registries.

Layer 3: Data Registries (The Source of Truth)#

The fully serialized JSON state of the scene (SceneObjectRegistry, OperatorRegistry).

When to use:

1. When you need context about what exists in the scene (e.g., light positions).

2. When identifying object relationships (e.g., shared material IDs).

Agent Heuristic: Treat this layer as Read-Only Context. Never attempt to mutate these registries at runtime.

Decorator Behavior: @SceneObjectProperty#

How decorated properties bridge Operator logic to visual selection controls in the Aircada Studio.

The @SceneObjectProperty() decorator tells the Aircada engine that a property expects a reference to another 3D object in the scene.

Studio Integration

Properties using this decorator are automatically exposed in the Studio UI as selection buttons on the Operator's configuration panel.

Nullable Initialization

You can safely initialize these properties with null or leave them blank. This allows designers in the Studio to pick the target object visually.

Automatic Hydration

At runtime, the engine injects the hydrated object (e.g., a ModelObject) into the property before the @Setup() method is called.

Layer 2: Operator Refs (The Magic Facades)#

Hydrated API Objects (ModelObject, CameraObject, etc.) used for native type-checking in scripts.

This layer wraps raw IDs in a sceneObjectRef<T>(id) facade. It tells the compiler the string is a functional 3D object.

When to use: Specifically for assigning static default values to properties decorated with @SceneObjectProperty().

Agent Heuristic: NEVER attempt to read properties (like .transform) directly off SceneObjects.KEY inside logic blocks. The engine only hydrates these after assignment to a decorated property.

typescript
@SceneObjectProperty()
defaultShoe: ModelObject = SceneObjects.UPLOADED_OBJECT_1;
Assigning static default values to properties decorated with @SceneObjectProperty.

Example: SceneObjectProperty in an Operator#

A complete Operator demonstrating how to properly type and initialize a SceneObjectProperty using Layer 2 Operator Refs.

When an Operator needs to declare a relationship with another 3D object in the scene, use @SceneObjectProperty(). You should initialize it using the Layer 2 Operator Refs (e.g., SceneObjects) imported from the registry.

FocusController.ts (typescript)
import { Setup, Operator, SceneObjectProperty, Context, ModelObject, AircadaContext } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";

@Operator({ 
    name: "Focus Controller", 
    type: "FOCUS_CONTROLLER"
})
export class FocusController {
    @Context()
    air!: AircadaContext;

    // 1. Declare the property and strongly type the expected hydrated object (e.g., ModelObject)
    // 2. Initialize using the Layer 2 Operator Ref.
    @SceneObjectProperty()
    focusTarget: ModelObject = SceneObjects.UPLOADED_OBJECT_1;

    @Setup()
    setup() {
        // Hydration happens automatically. The reference tells the engine which 
        // 3D object this operator targets without needing imperative lookup code.
    }
}
Operator declaring a SceneObjectProperty relationship with ModelObject.

Layer 1: Raw IDs (The Master Indexes)#

Strictly typed Base36 hash string constants (e.g., SceneObjectIds, OperatorIds).

When to use:

1. When an external system (network/dataset) provides a string ID.

2. When looking up an object's initial state in the Data Registry (Layer 3).

3. When logging or debugging sync issues.

Agent Heuristic: If an API specifically asks for an id: string, use this layer.

Studio Configuration & CLI Hydration#

Visual configuration in the Studio is synchronized with code through the Aircada CLI and the project-registry.ts file.

In Aircada, the Studio acts as the primary environment for scene composition. Developers place objects, configure lighting, and assign materials visually.

When you run a sync via the CLI, the system generates or updates the project-registry.ts file. This file contains a snapshot of all static IDs and registries.

This registry is critical for Operators to 'hook' into the scene without needing to perform slow or error-prone string-based lookups at runtime.