Model Object Facade (ModelObject)
The ModelObject is the fundamental programmatic facade for imported 3D mesh assets in Aircada (e.g. GLTF, OBJ, or FBX formats, type: 'MODEL'). It extends the base ISceneObject interface to expose high-performance spatial transformations, physical collision boundaries, and material characteristics.
Operators query and manipulate ModelObject instances using default references decorated with @SceneObjectProperty(). Once bound by the runtime engine, developers can dynamically alter model pivots, physics attributes, and interact with user gestures.
Example: Dynamic Material Override Initialization#
Example showing how to show a ModelObject and instantiate its material parameters.
// Hydrate and instanciate individual material parameters
this.industrialPump.show();
this.industrialPump.materialInstance();Example: Physical Displacement and Memory Teardown#
Example showing how to subscribe to click events on a ModelObject mesh to displace its position and cleanly dispose the listener.
import { Setup, Dispose, Operator, SceneObjectProperty, ModelObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Displacement Trigger",
type: "DISPLACEMENT_TRIGGER"
})
export class DisplacementTrigger {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
targetMesh: ModelObject = SceneObjects.DICE_MESH;
private unsubscribeToClick?: () => void;
@Setup()
setup() {
// Attach click listener and save unsubscribe callback
this.unsubscribeToClick = this.targetMesh.onClick.addListener(() => {
console.log("Mesh clicked! Elevating dice physically...");
this.targetMesh.transform.position.set(0, 5.0, 0); // Displace physically upwards
});
}
@Dispose()
dispose() {
// Prevent memory leaks by cleaning up the listener
this.unsubscribeToClick?.();
}
}Example: Referencing and Initializing a ModelObject#
Example showing how to declare a ModelObject property and show the model on setup.
import { Setup, Operator, SceneObjectProperty, ModelObject } from "@aircada/spec";
import { SceneObjects } from "../registry/scene.registry";
@Operator({
name: "Asset Animation Controller",
type: "ASSET_ANIMATION_CONTROLLER"
})
export class AssetController {
// Direct 3D mesh reference: matches an actual object in the 3D scene configured and referenced in the auto-generated scene.registry file.
@SceneObjectProperty()
industrialPump: ModelObject = SceneObjects.PUMP_1;
@Setup()
setup() {
// Set initial visibility on startup
this.industrialPump.show();
}
}Example: Custom Physical Collider Configuration#
Example showing how to configure physics, collider properties, and shadows on a ModelObject.
// Configure model as a heavy, highly frictional physical rigid body
this.industrialPump.castShadows = true;
this.industrialPump.receiveShadow = true;
this.industrialPump.isCollider = true;
this.industrialPump.reactToWorldForces = true;
this.industrialPump.colliderFriction = 0.85;
this.industrialPump.colliderElasticity = 0.1; // Low bounce
this.industrialPump.colliderDensity = 0.9;ModelObject Action Inputs (@Input)#
Inputs represent imperative operations that other systems can trigger on a ModelObject facade:
Available Inputs:
- show(): Renders the mesh visible in the active viewport and enables physical boundaries.
- hide(): Disables rendering and physical bounds detection completely.
- materialInstance(): Rebinds standard texture assets dynamically to instantiate individual surface overrides.
- dataInput(payload: DataBlock[]): Streams serializable data blocks to drive visual components or animate states.
- show() / hide(): Safe, non-destructive visibility switches.
- materialInstance(): Dynamically overrides base glTF textures with custom runtime instances.
- dataInput(payload): Dynamic pipeline data intake.
ModelObject Event Outputs (@Output)#
Outputs allow Operators to subscribe to reactive runtime events dispatched by the ModelObject:
Available Outputs:
- onClick: AirEvent<void>: Dispatched once when a user taps or clicks on the model's visual or physical bounds.
- whileHeld: AirEvent<void>: Fired continuously on every frame while the user maintains an active select gesture on the model.
- onRelease: AirEvent<void>: Dispatched when a click, select, or drag gesture is ended.
- dataOutput: AirEvent<DataBlock[]>: Emits custom pipeline values downstream to other nodes.
- onClick: Pointer click trigger.
- whileHeld: Continuous interaction tracking, excellent for real-time physics manipulation.
- onRelease: Selection ended trigger.
- dataOutput: Custom pipeline event emitter for transferring serializable states.
ModelObject Direct Properties#
A ModelObject exposes rich parameters for configuring pivots, shadows, collision boundaries, and physics metrics at runtime.
Mesh Pivot and Bounds:
- pivotOffset: Vector3: Moves the model relative to its coordinate handle. Useful for centering off-origin meshes.
- pivotRotation: Quaternion: Adjusts the internal mesh coordinate axes.
- boundingScale: Vector3: Sets the size boundaries of the mesh along spatial axes.
- renderOrder: number: Adjusts painter-sorting prioritization for overlapping or translucent geometry.
- mediaItemId: string: The complex media asset reference ID holding the source file.
Shadow Behaviors:
- castShadows: boolean: Enables the mesh to block light source rays and draw shadows on other objects.
- receiveShadow: boolean: Renders physical light shadows projected by other casting scene elements.
- useOriginal: boolean: Determines if the mesh should preserve its custom baked glTF textures rather than being overridden by scene-wide materials.
Physics and Colliders:
- isCollider: boolean: Enables collision bounds detection for physical simulations or raycasts.
- colliderOffset / Rotation / Scale: Configures the physical bounding box bounds separate from the visual mesh.
- reactToWorldForces: boolean: When active, registers the object as a rigid dynamic body responding to gravity and collision impacts.
- colliderFriction: number: Surface friction coefficients (FLOAT, Range: 0 to 1).
- colliderElasticity: number: Restitution bouncy coefficient (FLOAT, Range: 0 to 1).
- colliderDensity: number: Material mass density calculations (FLOAT, Range: 0 to 1).
- pivotOffset: Real-time adjustment to correct physical rotational handles.
- reactToWorldForces: Activates rigid-body gravity and collision physical simulation.
- castShadows / receiveShadow: Realistic occlusion shadows.
- isCollider: Toggles raycast bounds and rigid physical collisions.
Material, Transform, and Effects Facades#
Like other physical scene facades, ModelObject structures sub-properties to partition rendering and location parameters:
- .material: Configures direct physical surface color, roughness, metalness, and opacity overrides. For complete details, see the 3D Materials & Facades reference guide.
- .transform: Coordinates spatial position, scale, and rotation. For complete details, see the 3D Transforms & Coordinates reference guide.
- .effects: Activates custom runtime visual highlight shaders (e.g. flashing warning blinking, highlight outlines). For complete details, see the The Effects Facade API reference guide.