3D Materials & Facades (MaterialFacade)

Published Updated
Understanding how Aircada handles material surfaces, direct property mutations, and Physically Based Rendering (PBR) adjustments.

In Aircada, all primary visual 3D scene objects (such as Shapes, Models, and Text) possess a material property conforming to the MaterialFacade interface. This facade allows developers to dynamically modify surface styling at runtime.

Properties like colors, metallic properties, roughness, and visual transparency can be retrieved or assigned directly on the referenced scene object's material facade.

PBR Material Maps and Asset Configuration#

Guidelines for configuring PBR texture maps (Color, Roughness, Metalness, Normal) via Media Registry items and URL fallbacks.

Aircada materials support multiple specialized texture map coordinates, including colorMap, roughnessMap, metalnessMap, normalMap, and emissiveMap. For maximum performance, these maps should be loaded and managed using native platform systems.

1. The Recommended Approach: Media Registry

It is highly recommended to assign maps using assets uploaded to your project media directory. In your custom Operator classes, declare inputs using the @MediaItemProperty() decorator, or pull pre-compiled media identifiers from the autogenerated media.registry.ts file. This allows Aircada to compile, compress, and deliver images over the high-speed CDN in next-generation GPU-accelerated formats (e.g. KTX2).

2. URL Fallbacks

If dynamic external assets are required, the system will accept a standard external URL string (HTTP/HTTPS) as a map value. The Aircada engine will download the asset and automatically generate a temporary media item under the hood.

Performance Caution: Using raw URLs bypasses the Aircada asset optimization and pre-compression systems. Uncompressed PNG/JPEG files can lead to memory bloat and stuttering on mobile viewports. Always prioritize CDN-based media items for production environments.

MaterialFacade Direct Properties Reference#

Detailed index of PBR properties available for customizing 3D surfaces in the Aircada SDK and Studio override rules.

The Aircada material system uses a Physically Based Rendering (PBR) model to compute realistic surface lighting. Visual characteristics like clearcoats, index of refraction (IOR), sheen, and transparency are exposed as configurable variables.

These settings map directly to physical shaders, allowing detailed simulation of plastic, metal, glass, fabric, and polished coatings.

Studio Asset Overrides

When applying material properties dynamically to imported 3D models (ModelObjects), ensure the ModelObject has useOriginal: false enabled in Aircada Studio. If useOriginal is true, the embedded baked glTF material takes precedence.

Material Source Properties Details

Property & TypeDisplay NameSystem TypeDefault
linkedMaterialId: any
Share From
STRING_ARRAY
UNIT SELECTOR
[]
linkedMaterialType: "INSTANCE" | "COPY" | "LEVELS"
Material Linkage Type
ENUM
DROPDOWN
"INSTANCE"
useLinkedProperties: boolean
Use Linked Properties
BOOL
TOGGLE
true
colorMap: IMediaItem
Texture
MEDIA_ITEM
ELEMENT SELECTOR
""
color: IColor
Color
COLOR
COLOR PICKER
[1, 1, 1, 1]
isTransparent: boolean
isTransparent
BOOL
TOGGLE
false
opacity: float
Opacity
FLOAT
RANGE SLIDER
1
alphaMap: IMediaItem
alphaMap
MEDIA_ITEM
ELEMENT SELECTOR
""
roughness: float
Roughness
FLOAT
RANGE SLIDER
0.5
roughnessMap: IMediaItem
roughnessMap
MEDIA_ITEM
ELEMENT SELECTOR
""
metalness: float
Metalness
FLOAT
RANGE SLIDER
0
metalnessMap: IMediaItem
metalnessMap
MEDIA_ITEM
ELEMENT SELECTOR
""
envMapIntensity: float
Env Map
FLOAT
RANGE SLIDER
1
envMap: IMediaItem
envMap
MEDIA_ITEM
ELEMENT SELECTOR
""
useCustomEnvRotation: boolean
Custom Env Rotation
BOOL
TOGGLE
false
envMapRotationY: float
Rotation
FLOAT
RANGE SLIDER
0
envMapRotationX: float
Tilt
FLOAT
RANGE SLIDER
0
bumpScale: float
Bump Scale
FLOAT
RANGE SLIDER
0
bumpMap: IMediaItem
bumpMap
MEDIA_ITEM
ELEMENT SELECTOR
""
normalScale: float
Normal Scale
FLOAT
RANGE SLIDER
1
normalMap: IMediaItem
normalMap
MEDIA_ITEM
ELEMENT SELECTOR
""
aoMapIntensity: float
AO
FLOAT
RANGE SLIDER
1
aoMap: IMediaItem
aoMap
MEDIA_ITEM
ELEMENT SELECTOR
""
transmission: float
Transmission
FLOAT
RANGE SLIDER
0
transmissionMap: IMediaItem
transmissionMap
MEDIA_ITEM
ELEMENT SELECTOR
""
thickness: float
Thickness
FLOAT
RANGE SLIDER
0
thicknessMap: IMediaItem
thicknessMap
MEDIA_ITEM
ELEMENT SELECTOR
""
dispersion: float
Dispersion
FLOAT
RANGE SLIDER
0
dispersionMap: IMediaItem
dispersionMap
MEDIA_ITEM
ELEMENT SELECTOR
""
ior: float
IOR
FLOAT
RANGE SLIDER
1.5
iorMap: IMediaItem
iorMap
MEDIA_ITEM
ELEMENT SELECTOR
""
sheen: float
Sheen
FLOAT
RANGE SLIDER
0
sheenColorMap: IMediaItem
sheenColorMap
MEDIA_ITEM
ELEMENT SELECTOR
""
sheenColor: IColor
Sheen Color
COLOR
COLOR PICKER
[1, 1, 1, 1]
sheenRoughness: float
Roughness
FLOAT
RANGE SLIDER
0
sheenRoughnessMap: IMediaItem
sheenRoughnessMap
MEDIA_ITEM
ELEMENT SELECTOR
""
specularIntensity: float
Specular
FLOAT
RANGE SLIDER
1
specularColor: IColor
specularColor
COLOR
COLOR PICKER
[1, 1, 1, 1]
specularColorMap: any
specularColorMap
NONE
""
emissiveIntensity: float
Emissive
FLOAT
RANGE SLIDER
0
emissiveMap: IMediaItem
Emissive Map
MEDIA_ITEM
ELEMENT SELECTOR
""
emissive: IColor
emissive
COLOR
COLOR PICKER
[1, 1, 0.8, 1]
attenuationDistance: float
Attenuation
FLOAT
RANGE SLIDER
0
attenuationDistanceMap: IMediaItem
attenuationDistanceMap
MEDIA_ITEM
ELEMENT SELECTOR
""
attenuationColor: IColor
attenuationColor
COLOR
COLOR PICKER
[0, 0.9, 1, 1]
clearcoat: float
Clearcoat
FLOAT
RANGE SLIDER
0
clearcoatMap: IMediaItem
clearcoatMap
MEDIA_ITEM
ELEMENT SELECTOR
""
clearcoatNormalScale: float
Normal
FLOAT
RANGE SLIDER
1
clearcoatNormalMap: IMediaItem
clearcoatNormalMap
MEDIA_ITEM
ELEMENT SELECTOR
""
clearcoatRoughness: float
Clearcoat Roughness
FLOAT
RANGE SLIDER
0
clearcoatRoughnessMap: IMediaItem
clearcoatRoughnessMap
MEDIA_ITEM
ELEMENT SELECTOR
""
iridescence: float
Iridescence
FLOAT
RANGE SLIDER
0
iridescenceMap: IMediaItem
iridescenceMap
MEDIA_ITEM
ELEMENT SELECTOR
""
iridescenceThickness: float
Thickness
FLOAT
RANGE SLIDER
400
iridescenceThicknessMap: IMediaItem
iridescenceThicknessMap
MEDIA_ITEM
ELEMENT SELECTOR
""
iridescenceIOR: float
IOR
FLOAT
RANGE SLIDER
1.3
iridescenceIORMap: IMediaItem
iridescenceIORMap
MEDIA_ITEM
ELEMENT SELECTOR
""
displacementScale: float
Displacement
FLOAT
RANGE SLIDER
0
displacementMap: IMediaItem
displacementMap
MEDIA_ITEM
ELEMENT SELECTOR
""
displacementBias: float
Displacement Bias
FLOAT
RANGE SLIDER
0
side: "FRONT" | "BACK" | "DOUBLE"
Side
ENUM
DROPDOWN
"FRONT"
wrappingType: "REPEAT" | "CLAMP" | "MIRROR"
Wrapping
ENUM
DROPDOWN
"REPEAT"
uvScaleX: float
Scale X
FLOAT
RANGE SLIDER
1
uvScaleY: float
Scale Y
FLOAT
RANGE SLIDER
1
uvOffsetX: float
Offset X
FLOAT
RANGE SLIDER
0
uvOffsetY: float
Offset Y
FLOAT
RANGE SLIDER
0
autoScaleUV: boolean
Auto-Scale
BOOL
TOGGLE
false
autoScaleAdjustment: float
Auto-Scale Amount
FLOAT
RANGE SLIDER
1
autoScaleTextureProperty: "colorMap" | "alphaMap" | "alphaTestMap" | "roughnessMap" | "metalnessMap" | "envMap" | "bumpMap" | "iorMap" | "transmissionMap" | "thicknessMap" | "dispersionMap" | "specularColorMap" | "sheenColorMap" | "sheenRoughnessMap" | "iridescenceMap" | "iridescenceThicknessMap" | "iridescenceIORMap" | "emissiveMap" | "clearcoatMap" | "clearcoatRoughnessMap" | "clearcoatNormalMap" | "attenuationDistanceMap" | "normalMap" | "aoMap" | "displacementMap"
Aspect Based On
ENUM
DROPDOWN
"colorMap"
autoScaleType: "IMAGE_SIZE" | "WIDTH" | "HEIGHT"
Scale Based On
ENUM
DROPDOWN
"IMAGE_SIZE"
autoScalePlane: "XY" | "XZ" | "YZ"
Scale Plane
ENUM
DROPDOWN
"XY"
defaultImageQuality: "ORIGINAL" | "TINY" | "LOW" | "MEDIUM" | "HIGH" | "OPTIMIZED" | "KTX2_TINY" | "KTX2_LOW" | "KTX2_MEDIUM" | "KTX2_HIGH"
Default Image Quality
ENUM
DROPDOWN
"OPTIMIZED"
alphaTest: float
Alpha Test
FLOAT
RANGE SLIDER
0.11
alphaTestMap: IMediaItem
alphaTestMap
MEDIA_ITEM
ELEMENT SELECTOR
""
wireframe: boolean
Wireframe
BOOL
TOGGLE
false
polygonOffset: boolean
Polygon Offset
BOOL
TOGGLE
false
polygonOffsetFactor: float
Polygon Offset Factor
FLOAT
RANGE SLIDER
-4