Text Object Facade (TextObject)

Detailed specification of the TextObject facade in the Aircada SDK, providing programmatic access to 3D and 2D text primitives, typography settings, inputs, and outputs.

Published: 7/10/2026

The TextObject is the SDK bridge for rendering and configuring dynamic text blocks in the 3D scene (type: 'TEXT'). It extends the base ISceneObject interface and inherits standard spatial transform and material features.

Developers declare relationships to TextObject instances using the @SceneObjectProperty() decorator. Once hydrated, they can query and update direct text properties, call action inputs, and listen to event outputs.

Example: Custom Path Render Injection#

Example illustrating using action inputs to trigger text mesh visibility and raw SVG paths.

Example showing how to inject dynamic SVG paths into a TextObject.

typescript

// Render custom SVG characters dynamically
const customPath = "<svg>...</svg>";
this.statusText.svgString(customPath);

Updating TextObject text rendering using a dynamic SVG path string.

Example: Click Event & Memory Teardown#

Example illustrating how to register user click handlers on TextObjects and cleanly unsubscribe using the Dispose pattern.

Example showing how to attach an event listener to a TextObject and clean up correctly to prevent memory leaks.

TextToggle.ts (typescript)

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

@Operator({
    name: "Interactive Text Toggle",
    type: "INTERACTIVE_TEXT_TOGGLE"
})
export class TextToggle {
    // Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
    @SceneObjectProperty()
    targetText: TextObject = SceneObjects.WARNING_LABEL;

    private unsubscribeToClick?: () => void;

    @Setup()
    setup() {
        // Attach click listener and save unsubscribe callback
        this.unsubscribeToClick = this.targetText.onClick.addListener(() => {
            console.log("Label clicked! Toggling Bevel...");
            this.targetText.isBevelEnabled = !this.targetText.isBevelEnabled;
        });
    }

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

Operator registering an onClick listener on a TextObject and cleaning it up in dispose.

Example: Declaring and Referencing a TextObject#

Example illustrating how to declare a TextObject inside an Operator and update its value on startup.

Example showing how to declare and reference a TextObject in an Operator class.

TextBillboardController.ts (typescript)

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

@Operator({
    name: "Text Billboard Controller",
    type: "TEXT_BILLBOARD_CONTROLLER"
})
export class TextBillboardController {
    // Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
    @SceneObjectProperty()
    statusText: TextObject = SceneObjects.STATUS_LABEL_1;

    @Setup()
    setup() {
        // Directly change text label at startup
        this.statusText.textValue = "System Initialized";
    }
}

Operator class declaring statusText property as a TextObject and modifying it in setup.

Example: Modifying Typography and Bevels#

Example showcasing dynamic adjustments to text values, extrusion toggling, and character bevel sizes.

Example showing how to enable extruded 3D text and configure smooth bevels dynamically.

typescript

// Enable extruded 3D text and configure smooth bevels
this.statusText.textValue = "Warning: High Temp!";
this.statusText.useExtrusion = true;
this.statusText.isBevelEnabled = true;
this.statusText.textBevelThickness = 0.02;
this.statusText.textBevelSize = 0.01;

Enabling 3D extrusion, enabling bevels, and configuring bevel parameters on TextObject.

TextObject Action Inputs (@Input)#

Control methods exposed as inputs on TextObject instances to handle visibility and update text geometry.

Inputs represent imperative commands that can be triggered on TextObject facades:

Available Inputs:

- show(): Renders character meshes visible in the scene and enables interactive raycast listeners.

- hide(): Suspends character mesh rendering and disables collision detection.

- svgString(payload: string): Dynamically updates the text rendering using custom raw SVG path strings.

- dataInput(payload: DataBlock[]): Streams dynamic data blocks to drive visual styling or animation states.

show() / hide(): Dynamic visibility switches.
svgString(payload): Custom vector path rendering intake.
dataInput(payload): Dynamic pipeline data input channel.

TextObject Event Outputs (@Output)#

Asynchronous event channels capturing pointer clicks, drag interactions, and internal data streams.

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

Available Outputs:

- onClick: AirEvent<void>: Fired once upon completing a click or tap interaction on the text bounds.

- whileHeld: AirEvent<void>: Dispatched continuously every tick while the user maintains an active click, grip, or select on the text.

- onRelease: AirEvent<void>: Dispatched when a mouse click or select interaction is ended.

- dataOutput: AirEvent<DataBlock[]>: Emits processed data blocks downstream to linked scene nodes.

onClick: Standard user interaction listener.
whileHeld: Real-time engagement stream, excellent for custom dragging.
onRelease: Interaction completed signal.
dataOutput: Custom pipeline event emitter for transferring serializable states.

TextObject Direct Properties#

Typographic parameters and geometry settings available directly on TextObject instances.

A TextObject exposes geometric and typographical parameters to modify rendered text appearance in real time.

Typographic and Extrusion Properties:

- textValue: string: The actual string text to display in the scene.

- textFontSize: number: Absolute font scale size (FLOAT, Range: 0 to 200).

- letterSpacing: number: Horizontal padding between characters (FLOAT, Range: -100 to 100).

- useExtrusion: boolean: Toggles between flat 2D billboard text and solid extruded 3D text geometry.

- textSmoothing: number: Density of mesh subdivision smoothing (FLOAT, Range: 1 to 5).

- normalSmoothing: number: Normal interpolation threshold (FLOAT, Range: 0 to 1).

- isBevelEnabled: boolean: Enables rounded/slanted bevel edges along character boundaries.

- textBevelThickness: number: Depth of the bevel extrusion (FLOAT, Range: 0 to 0.1).

- textBevelSize: number: Width/inset distance of the bevel (FLOAT, Range: 0 to 0.1).

- fontSelection: any: Complex typography variant mapping containing the custom media asset ID.

textValue: Main display text, safe for real-time updates.
useExtrusion: Dynamic toggle for 2D flat vs 3D solid rendering.
isBevelEnabled: Adds premium bevel edges to 3D characters.

Material, Transform, and Effects Facades#

Overview of child facades hosted by TextObject instances for material styling, transforms, and custom visual effects.

Like other physical scene facades, TextObject structures sub-properties to partition rendering and location parameters:

- .material: Exposes physical render characteristics such as surface color, roughness, metalness, and opacity. For complete details, see the 3D Materials & Facades reference guide.

- .transform: Handles physical 3D positioning, scaling, and rotation. For complete details, see the 3D Transforms & Coordinates reference guide.

- .effects: Accesses custom runtime shader behaviors like glow panels, custom hover overlays, and highlight systems. For complete details, see the The Effects Facade API reference guide.