Image

A component for rendering images.

Type	Name	Interface Description
Variables	color: Color	• Function: The base color of the current material.
Variables	flipX: boolean	• Function: Determine whether to flip the image horizontally
Variables	flipY: boolean	• Function: Determine whether to flip the image vertically
Variables	opacity: number	• Function: The opacity of the image.
Variables	pivot: Vector2f	• Function: The pivot point of the Image. Typical values are in the range [0, 1]. Values outside that range are still passed through and place the pivot outside the image rect.
Variables	size: Vector2f	• Function: The size of the image, takes effect according to the stretch mode
Variables	stretchMode: StretchMode	• Function: Determine how the image is stretched to the required size
Variables	texture: Texture	• Function: The main texture of the Image component.
Functions	constructor()
Functions	getMaterialProperty(key: string): number | Vector2f | Vector3f | Vector4f | Texture | Matrix4x4f	• Function: Gets the current Image material property value for the specified key. For general material properties, key must match a property exposed by the Image's current material. Built-in Filled-mode keys such as _filledType, _startPoint, and _filledRange are also supported when the Image DrawMode is configured as Filled in the editor. Parameters • key: - The material property key to read. Returns The current value of the specified material property.
Functions	setMaterialProperty(key: string, arg1: number | Vector2f | Vector3f | Vector4f | Texture | Matrix4x4f): void	• Function: Sets a material property for the current Image. For general material properties, key must match a property exposed by the Image's current material. Commonly used to implement material property-driven UI effects such as health bars, progress bars, timer bars, water levels, pole growth, and image slicing effects. Note: Image DrawMode cannot be changed via script API. You must configure the Image DrawMode (for example, switch to "Filled") in the editor first. When the Image DrawMode is set to "Filled", this API also supports these built-in fill keys: 1. Fill type: key = "_filledType", number - 0: Horizontal fill, the visible area grows from left to right. - 1: Vertical fill, the visible area grows from top to bottom. This describes the visual fill direction only; it does not redefine the screen coordinate origin used by other APIs. 2. Fill start point: key = "_startPoint", number, in the range [0, 1] - For horizontal fill: the start position from left to right. - For vertical fill: the start position from top to bottom. For example: 0 means start from the very left/top, 0.5 means start from the center. 3. Fill range (progress): key = "_filledRange", number, in the range [0, 1] - Represents the current fill percentage: 0 is 0%, 1 is 100%. Example: ts // Horizontal fill, starting from the left, currently filled to 50% image.setMaterialProperty("_filledType", 0); image.setMaterialProperty("_startPoint", 0.0); image.setMaterialProperty("_filledRange", 0.5); Parameters • key: - The material property key to write. • arg1: - The value to set.

Examples

constructor()

let obj = new APJS.Image();

Use Case

Example 1 — Detect tap on specific 2D buttons using TouchUtils.isScreenPointOnImage for accurate hit-testing. Supports pressed/normal visual states and multiple buttons.

@component()
export class ButtonTapHandler extends APJS.BasicScriptComponent {
  @serializeProperty
  private btn1Obj: APJS.SceneObject;
  @serializeProperty
  private btn2Obj: APJS.SceneObject;

  private btn1Image!: APJS.Image;
  private btn2Image!: APJS.Image;
  private initialized: boolean = false;

  private touchCallback = (event: APJS.IEvent) => {
    if (!this.initialized) return;
    const touchInfo = event.args[0] as APJS.TouchData;

    if (touchInfo.phase === APJS.TouchPhase.Began) {
      if (APJS.TouchUtils.isScreenPointOnImage(touchInfo.position, this.btn1Image)) {
        this.btn1Image.color = new APJS.Color(0.7, 0.7, 0.7, 1);
        this.onButton1Tap();
      } else if (APJS.TouchUtils.isScreenPointOnImage(touchInfo.position, this.btn2Image)) {
        this.btn2Image.color = new APJS.Color(0.7, 0.7, 0.7, 1);
        this.onButton2Tap();
      }
    } else if (touchInfo.phase === APJS.TouchPhase.Ended) {
      this.btn1Image.color = new APJS.Color(1, 1, 1, 1);
      this.btn2Image.color = new APJS.Color(1, 1, 1, 1);
    }
  };

  onUpdate(dt: number): void {
    if (!this.initialized && this.btn1Obj && this.btn2Obj) {
      this.btn1Image = this.btn1Obj.getComponent("Image") as APJS.Image;
      this.btn2Image = this.btn2Obj.getComponent("Image") as APJS.Image;
      APJS.EventManager.getGlobalEmitter().on(APJS.EventType.Touch, this.touchCallback);
      this.initialized = true;
    }
  }

  private onButton1Tap(): void {
    console.log("Button 1 tapped");
  }

  private onButton2Tap(): void {
    console.log("Button 2 tapped");
  }

  onDestroy(): void {
    APJS.EventManager.getGlobalEmitter().off(APJS.EventType.Touch, this.touchCallback);
  }
}

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;
    }
  }
}