Light Object Facade (LightObject)
The LightObject represents a physical light emitter or ambient lighting component in the 3D scene (type: 'LIGHT'). It extends the base ISceneObject interface and exposes properties to configure optical properties, spatial lighting falloffs, and shadow-mapping buffers.
Developers declare relationships to LightObject instances using the @SceneObjectProperty() decorator. Once hydrated, Operators can dynamically turn lights on/off, alter color temperatures, adjust spot cones, and configure shadow rendering parameters.
Example: Turning Lights On and Off#
Example showing how to hide a Spotlight facade to disable its light emission.
// Turn off the ambient or spotlight emitter dynamically
this.spotlight.hide();Example: Interactive Helper Trigger & Memory Teardown#
Example showing how to subscribe to click events on a LightObject helper to toggle intensity and dispose listeners correctly.
import { Setup, Dispose, Operator, SceneObjectProperty, LightObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Lighting Interactive Toggle",
type: "LIGHTING_INTERACTIVE_TOGGLE"
})
export class LightingToggle {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
spotlight: LightObject = SceneObjects.SPOTLIGHT_1;
private unsubscribeToClick?: () => void;
@Setup()
setup() {
// Attach click listener and save unsubscribe callback
this.unsubscribeToClick = this.spotlight.onClick.addListener(() => {
console.log("Light icon clicked! Toggling intensity...");
this.spotlight.lightIntensity = this.spotlight.lightIntensity === 0 ? 15.0 : 0;
});
}
@Dispose()
dispose() {
// Prevent memory leaks by cleaning up the listener
this.unsubscribeToClick?.();
}
}Example: Declaring a LightObject#
Example showing how to declare a LightObject and turn it on in setup.
import { Setup, Operator, SceneObjectProperty, LightObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Lighting Controller",
type: "LIGHTING_CONTROLLER"
})
export class LightingController {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
spotlight: LightObject = SceneObjects.SPOTLIGHT_1;
@Setup()
setup() {
// Turn on spotlight initially
this.spotlight.show();
}
}Example: Real-time Lighting Mutator#
Example showing how to configure amber alert mode on a Spotlight.
// Set to dynamic amber alert mode spotlight
this.spotlight.lightColor = "#FF8800";
this.spotlight.lightIntensity = 18.0;
this.spotlight.spotlightAngle = 0.4;
this.spotlight.spotlightFeather = 0.8; // Very soft boundariesLightObject Action Inputs (@Input)#
Inputs represent imperative commands that can be called on LightObject facades:
Available Inputs:
- show(): Enables the light emitter (turns the light ON).
- hide(): Disables the light emitter (turns the light OFF).
- dataInput(payload: DataBlock[]): Streams dynamic data blocks to drive visual colors or intensity levels.
- show(): Turns on light emission.
- hide(): Turns off light emission (zeroes out output energy).
- dataInput(payload): Dynamic pipeline data intake.
LightObject Event Outputs (@Output)#
Outputs allow Operators to subscribe to reactive runtime events dispatched by the LightObject:
Available Outputs:
- onClick: AirEvent<void>: Fired once upon completing a click interaction on the light helper body.
- whileHeld: AirEvent<void>: Dispatched continuously every tick while the user maintains an active select on the helper body.
- 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 light helper icon.
- whileHeld: Pointer hold interaction stream.
- onRelease: Hold ended trigger.
- dataOutput: Custom pipeline event emitter for transferring serializable states.
LightObject Direct Properties#
A LightObject exposes direct physical properties to manage lighting characteristics and shadow projections in real time.
Optical & Emitter Properties:
- lightType: Defines the light simulation. Values: POINT, AMBIENT, DIRECTIONAL, SPOTLIGHT, RECT_AREA_LIGHT.
- lightColor: Hex string or normalized RGBA array defining the emitter color.
- lightIntensity: Lumens intensity factor (FLOAT, Range: 0.01 to 25).
- lightDecay: Decay attenuation rate over distance (FLOAT, Range: 0 to 10).
- lightDistance: Maximum physical throw threshold before decay fully zero out (FLOAT, Range: 0 to 1000).
Spotlight Specifics:
- spotlightAngle: Spotlight cone throw width (FLOAT, Range: 0 to 1).
- spotlightFeather: Softness blending along the cone boundary (FLOAT, Range: 0 to 1).
Shadow Mapping Specifics:
- useGlobalShadowSettings: Locks shadow-mapping variables to scene-wide defaults.
- castShadows: Enables the emitter to cast shadows from objects intersecting its throw paths.
- shadowMapSize: Resolution width/height of the shadow depth map buffer. Options: 512, 768, 1024.
- shadowAreaSize: Bounds scaling for directional lights (FLOAT, Range: 0 to 100).
- shadowRadius / Blur / Bias: Softness and depth offsets to optimize shadows and prevent artifact banding.
Helpers:
- showLightHelperInViewMode: Renders visual cones and throw guides in view modes.
- lightHelperOpacity: Opacity of the visual throw guidelines (FLOAT, Range: 0 to 1).
- lightType: Enum defining physical light simulation characteristics.
- lightIntensity: Relative output strength of the light emitter.
- castShadows: Toggles shadow-map calculation for this specific light.
- lightColor: Supports dynamic RGB array or HEX string values.
Transform Facade#
Every LightObject hosts a sub-facade to delegate spatial coordinates:
- .transform: Coordinates spatial positioning, scaling, and rotation. (See the 3D Transforms & Coordinates reference guide).