How to modify 3D content in AR scenes during runtime in XRFame mini-program

This article provides a practical guide for controlling visibility strategies under AR tracking, runtime Transform modifications, and dynamic GLTF material updates.

Before you begin

• Familiarize yourself with xr-frame runtime 3D content loading

How to configure visibility control strategy for runtime blocks

The BlockController component's visibility control strategy visibleStrategy has three types:

Strategy	Description
VisibleWhileTracked	Default value. Display only when the Block is successfully tracked, hide when tracking is lost.
VisibleAfterFirstTracked	Once the Block is successfully tracked, it remains visible even if tracking is lost.
None	Visibility is not controlled by the engine, maintained by the developer.

Modify its visibility strategy after BlockHolder calls holdBlock() to create a Block node under ShadowRoot.

Refer to mounting content without annotations for how to find BlockID.

const blockInfo: easyar.BlockInfo = { id: blockId };
blockHolder.holdBlock(blockInfo);
const block = blockHolder.getBlockById(blockInfo.id);

// Modify strategy to: display permanently once tracked
block.visibleStrategy = BlockVisibleStrategy.VisibleAfterFirstTracked;

The default VisibleStrategy is VisibleWhileTracked, meaning content (including child nodes) is displayed only when the Block is tracked by MegaTracker.

Content editing and modification methods

• Modifying object's Transform

  For Element in the scene, call its getComponent() method to obtain the corresponding Component for modification.

  const xrFrameSystem = wx.getXrFrameSystem();
  let transform = model.getComponent(xrFrameSystem.Transform);
  transform.position.setValue(1.0, 0.0, -1.0);
  /** Copy original quaternion */
  let originalQuaternion = modelTF.quaternion.clone();
  /** Rotate 180 degrees around Y-axis */
  let targetQuaternion = originalQuaternion.multiply(new xrFrameSystem.Quaternion().setValue(0, 1, 0, 0));
  transform.quaternion.setValue(targetQuaternion);
  

  In this example, the program obtains xrFrameSystem.Transform of model, then modifies its position and rotation angle.

• Replacing textures

  Before replacing textures, manually load the texture resource through xr-frame's scene asset management system using loadAsset.

  Then obtain the model's GLTF property, and call the setTexture() method for each mesh's material.

  const textureAsset = await scene.assets.loadAsset({
      type: 'texture',
      assetId: `texture01`,
      src: 'some-texture-url.png',
  });
  model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {
      m.material.setTexture('u_baseColorMap', textureAsset.value);
  });
  

  In this example, the program first loads a textureAsset using the scene's asset manager, then uses it to replace the texture of the GLTF model.

• Replacing registered materials

  To replace registered materials, first obtain the material resource using the xr-frame scene's asset management system getAsset().

  Then obtain the model's GLTF property, and modify the material property for each mesh by calling setData.

  let occlusionMaterial = scene.assets.getAsset("material", "easyar-occlusion");
  model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {
      m.setData({ material: occlusionMaterial });
  });
  

  In this example, the program first loads EasyAR's registered occlusion material easyar-occlusion using the scene's asset manager, then sets it as the material for the GLTF model.