Material

Material.

Type	Name	Interface Description
Variables	mainPass: Pass	• Function: Gets the main pass of the material. If no passes exist, a new one is created and returned. Returns The main Pass object for the material.
Variables	passes: Pass[]	• Function: Gets the passes for the material.
Variables	renderQueue: number	• Function: Gets the render queue for the material.
Functions	constructor()
Functions	clone(): Material	• Function: Create a clone of this material. Returns A new Material instance that is a clone of this material.
Functions	disableMacro(macro: string): void	• Function: Unsets a shader macro. The macro name must match the shader macro/key exactly. Parameters • macro: - The name of the shader macro.
Functions	enableMacro(macro: string, value: number): void	• Function: Sets a shader macro that is enabled by this material. The macro name must match the shader macro/key exactly. Parameters • macro: - The name of the shader macro. • value: - The value to set for the shader macro.
Functions	getColor(name: string): Color | undefined	• Function: Retrieves the color associated with a given name from the material's properties. The property name must match a color/vec4 property exposed by the material shader. Returns undefined when the property does not exist or the named property is not stored as a Vector4f color value. Parameters • name: - The name of the property to retrieve the color from. Returns A Color object if the property exists and is a Vector4f, otherwise undefined.
Functions	getFloat(name: string): number | undefined	• Function: Gets a named float value from the material. The property name must match a float uniform/property exposed by the material shader. Parameters • name: - The name of the float property. Returns The float value if found, undefined otherwise.
Functions	getInt(name: string): number | undefined	• Function: Gets a named integer value. The property name must match an integer uniform/property exposed by the material shader. Parameters • name: - The name of the integer property.
Functions	getMatrix(name: string): Matrix4x4f | undefined	• Function: Gets a named matrix value. The property name must match a matrix uniform/property exposed by the material shader. Parameters • name: - The name of the matrix property. Returns The matrix value if found, undefined otherwise.
Functions	getTexture(name: string): Texture | null	• Function: Gets a named texture value from the material. The property name must match a texture slot exposed by the material shader. Parameters • name: - The name of the texture property. Returns The texture value if found, null otherwise.
Functions	getVector(name: string): Vector2f | Vector3f | Vector4f | undefined	• Function: Retrieves a vector property by name from the material. The property name must match a vector property exposed by the material shader. The returned type depends on the stored property kind: Vector2f for vec2, Vector3f for vec3, and Vector4f for vec4. Parameters • name: - The name of the vector property to retrieve. Returns A Vector2f, Vector3f, or Vector4f object if found; otherwise, undefined.
Functions	hasFloatKey(key: string): boolean	• Function: Checks whether this material currently has a float property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The float property name to check. Returns True if a float property with that exact name exists; otherwise false.
Functions	hasIntKey(key: string): boolean	• Function: Checks whether this material currently has an integer property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The integer property name to check. Returns True if an integer property with that exact name exists; otherwise false.
Functions	hasMatrixKey(key: string): boolean	• Function: Checks whether this material currently has a matrix property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The matrix property name to check. Returns True if a matrix property with that exact name exists; otherwise false.
Functions	hasTextureKey(key: string): boolean	• Function: Checks whether this material currently has a texture property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The texture property name to check. Returns True if a texture property with that exact name exists; otherwise false.
Functions	hasVector2Key(key: string): boolean	• Function: Checks whether this material currently has a Vector2 property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The Vector2 property name to check. Returns True if a Vector2 property with that exact name exists; otherwise false.
Functions	hasVector3Key(key: string): boolean	• Function: Checks whether this material currently has a Vector3 property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The Vector3 property name to check. Returns True if a Vector3 property with that exact name exists; otherwise false.
Functions	hasVector4Key(key: string): boolean	• Function: Checks whether this material currently has a Vector4 property with the specified name. Property names are matched exactly and should come from the material/shader property definitions used by this material. Parameters • key: - The Vector4 property name to check. Returns True if a Vector4 property with that exact name exists; otherwise false.
Functions	isMacroEnabled(value: string): boolean	• Function: Checks whether a shader macro is enabled on this material. The macro name must match the shader macro/key exactly. Parameters • value: - The name of the macro. Returns True if the macro is enabled, false otherwise.
Functions	setColor(name: string, color: Color): void	• Function: Sets the color of a material property by name. The property name must match a color/vec4 property exposed by the material shader. Parameters • name: - The name of the material property to set the color for. • color: - The Color object containing the RGBA values to be set.
Functions	setFloat(name: string, value: number): void	• Function: Sets a named float value. The property name must match a float uniform/property exposed by the material shader. Parameters • name: - The name of the float property. • value: - The float value to set.
Functions	setInt(name: string, value: number): void	• Function: Sets a named integer value. The property name must match an integer uniform/property exposed by the material shader. Parameters • name: - The name of the integer property. • value: - The integer value to set.
Functions	setMatrix(name: string, m: Matrix4x4f): void	• Function: Sets a named matrix value. The property name must match a matrix uniform/property exposed by the material shader. Parameters • name: - The name of the matrix property. • m: - The matrix value to set.
Functions	setTexture(name: string, texture: Texture): void	• Function: Sets a named texture value. The property name must match a texture slot exposed by the material shader. Parameters • name: - The name of the texture property. • texture: - The texture value to set.
Functions	setVector(name: string, value: Vector2f | Vector3f | Vector4f): void	• Function: Sets a vector value in the material by its name. The property name must match a vector property exposed by the material shader. The vector dimension must also match the target property: pass Vector2f for vec2, Vector3f for vec3, and Vector4f for vec4. Parameters • name: - The name of the vector property to set. • value: - The vector value to set, which can be of type Vector2f, Vector3f, or Vector4f.

Examples

constructor()

let obj = new APJS.Material();

Use Case

Example 1 — Change a 3D object's material color at runtime via MeshRenderer.mainMaterial

@component()
export class MaterialColorChange extends APJS.BasicScriptComponent {
  @serializeProperty
  private targetColor: APJS.Color = new APJS.Color(1, 0, 0, 1);

  onStart(): void {
    this.applyColor(this.targetColor);
  }

  private applyColor(color: APJS.Color): void {
    const renderer = this.getSceneObject().getComponent("MeshRenderer") as APJS.MeshRenderer;
    // Use mainMaterial for single material access
    // Use setVector (NOT setVector4 — it doesn't exist)
    if (renderer && renderer.mainMaterial) {
      renderer.mainMaterial.setVector("_AlbedoColor", new APJS.Vector4f(color.r, color.g, color.b, color.a));
    }
  }

  onDestroy(): void {}
}

Example 2 — Animated progress bar using Image filled mode with setMaterialProperty for health/loading display

@component()
export class ImageProgressBar extends APJS.BasicScriptComponent {
  @serializeProperty
  private progressBarObject: APJS.SceneObject;

  @serializeProperty
  private duration: number = 3.0;

  private barImage: APJS.Image;
  private elapsed: number = 0;
  private filling: boolean = true;

  onStart(): void {
    this.barImage = this.progressBarObject.getComponent("Image") as APJS.Image;
    if (this.barImage) {
      // Horizontal fill from left
      this.barImage.setMaterialProperty("_filledType", 0);
      this.barImage.setMaterialProperty("_startPoint", 0.0);
      this.barImage.setMaterialProperty("_filledRange", 0.0);
    }
  }

  onUpdate(deltaTime: number): void {
    if (!this.barImage) return;

    this.elapsed += deltaTime;
    const progress = Math.min(this.elapsed / this.duration, 1.0);
    this.barImage.setMaterialProperty("_filledRange", this.filling ? progress : 1.0 - progress);

    if (this.elapsed >= this.duration) {
      this.elapsed = 0;
      this.filling = !this.filling;
    }
  }
}