Shape Object Facade (ShapeObject)
The ShapeObject is the fundamental programmatic bridge for 3D primitive geometry in Aircada (e.g., Cubes, Spheres, Cylinders, Toruses). It extends the base ISceneObject interface and hydrates spatial, material, effect, and interaction behaviors.
Operators interact with a ShapeObject using declared properties decorated with @SceneObjectProperty(). Once hydrated by the engine, all direct properties, inputs, and outputs become available for logic implementation.
Example: Triggering Action Inputs#
Example showing how to hide a shape facade on startup.
// Dynamically toggling visibility
@Setup()
setup() {
// Hide object initially
this.targetCube.hide();
}Example: Click Event & Scale Transformation#
Example showing how to subscribe to a click output on a ShapeObject and scale the object on interaction.
import { Setup, Dispose, Operator, SceneObjectProperty, ShapeObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Shape Click Scale",
type: "SHAPE_CLICK_SCALE"
})
export class ShapeClickScale {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
targetCube: ShapeObject = SceneObjects.CUBE_1;
private unsubscribeToClick?: () => void;
@Setup()
setup() {
// Listen to click, save cleanup, and update scale using vector set()
this.unsubscribeToClick = this.targetCube.onClick.addListener(() => {
this.targetCube.transform.scale.set(0.35, 0.35, 0.35);
});
}
@Dispose()
dispose() {
// Clean up the listener to prevent memory leaks
this.unsubscribeToClick?.();
}
}Example: Targeting a ShapeObject#
Example showing how to target a ShapeObject, register a click listener, and update its material color dynamically.
import { Setup, Dispose, Operator, SceneObjectProperty, ShapeObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Shape Interaction Controller",
type: "SHAPE_INTERACTION_CONTROLLER"
})
export class ShapeController {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
targetCube: ShapeObject = SceneObjects.CUBE_1;
private unsubscribeToClick?: () => void;
@Setup()
setup() {
// Listen to standard click interactions and save cleanup
this.unsubscribeToClick = this.targetCube.onClick.addListener(() => {
console.log("Cube clicked! Changing color...");
this.targetCube.material.color = "#FF5733"; // Direct property change
});
}
@Dispose()
dispose() {
// Clean up the listener to prevent memory leaks
this.unsubscribeToClick?.();
}
}Example: Mutating Geometry Properties#
Example showing how to query shapeType and update radialSegments and detail.
// Reading and configuring geometry details
const currentType = this.targetCube.shapeType; // e.g. "CYLINDER"
this.targetCube.radialSegments = 64; // Instantly smooth the cylinder curvature
this.targetCube.detail = 3;ShapeObject Action Inputs (@Input)#
Inputs represent executable operations that other systems or Operators can trigger on a ShapeObject. They are declared as methods on the facade.
Standard Shape Inputs:
- show(): Renders the shape visible in the active viewport and reactivates physical colliders and raycast interactions.
- hide(): Disables rendering for the shape and deactivates all physical interactions and collision detection.
- dataInput(payload: DataBlock[]): Standard dynamic pipeline intake. Streams an array of structured DataBlocks to the shape mesh to drive visual animations or state changes.
- show() / hide(): Safe, non-destructive toggling of shape rendering.
- dataInput(payload): Pipeline data intake for streaming data-driven parameters.
ShapeObject Event Outputs (@Output)#
Outputs allow operators to subscribe to runtime event channels using .addListener(callback). They represent the reactive surface of the ShapeObject.
Available Interactions & Gestures:
- onClick: AirEvent<void>: Dispatched when a user interacts with or taps on the shape's collider bounds.
- whileHeld: AirEvent<void>: Fired continuously on every render frame while the user maintains an active click, grip, or touch gesture on the object. Ideal for dragging, rotating, or custom continuous gestures.
- onRelease: AirEvent<void>: Dispatched the instant a click, tap, or hold interaction is ended by the user.
- dataOutput: AirEvent<DataBlock[]>: Propagates data blocks outwards through the connection graph to downstream elements.
- onClick: Raycast click detection. Fired on pointer down/up completion.
- whileHeld: Continuous interaction tracking, triggered once per tick during user engagement.
- onRelease: End of interaction callback, matching standard touch/mouse up events.
- dataOutput: Custom pipeline event emitter for transferring serializable states.
ShapeObject Direct Properties#
A ShapeObject exposes direct geometric properties that match the parameters configured visually in the Aircada Studio Geo Panel. These properties are non-destructive and can be read or modified dynamically at runtime.
Available Properties:
- shapeType: Establishes the primitive geometry. Values: CUBE, SPHERE, CYLINDER, TORUS, CAPSULE, CONE, ICOSAHEDRON, RING, PLANE, CIRCLE.
- segments: Primary segment resolution (INT). Controls mesh density. Range: 1 to 300.
- radialSegments: Radial segment resolution (INT) for curved primitives. Range: 2 to 300.
- detail: Level of detail (INT) subdivisions for complex shapes. Range: 0 to 5.
- roundedEdgeRadiusX / Y / Z: Radius parameters for rounded edges (NONE systemType).
- shapeType: Enum defining primitive geometry type. Default:
CUBE. - segments: Integer resolution control. Min: 1, Max: 300.
- radialSegments: Radial division density. Min: 2, Max: 300.
- detail: Subdivision details. Min: 0, Max: 5.
Material, Transform, and Effects Facades#
Every ShapeObject encapsulates three powerful sub-properties to manage its visual and physical state in the scene:
- .material: Provides direct controls for rendering characteristics (e.g., color, roughness, opacity, metalness). For complete details, see the 3D Materials & Facades reference guide.
- .transform: Coordinates spatial parameters including position, scale, and rotation. For complete details, see the 3D Transforms & Coordinates reference guide.
- .effects: Accesses custom runtime shader behaviors such as outlines, blinking, highlighting, or customized glowing. For complete details, see the The Effects Facade API reference guide.