How to modify 3D content in an AR scene at XRFame mini program runtime

This article provides practical guidance on visibility strategy control under AR tracking, runtime Transform changes, and dynamic GLTF material updates.

Before you begin

• Be familiar with xr-frame runtime 3D content loading

How to configure runtime Block visibility control strategy

The visibility control strategy visibleStrategy of the BlockController component has three options:

Strategy	Description
VisibleWhileTracked	Default value. Display only when the Block is successfully tracked, and hide it when tracking is lost.
VisibleAfterFirstTracked	Once the Block has been successfully tracked once, keep it displayed even if tracking is later lost.
None	Visibility is not controlled by the engine and is maintained by the developer.

After BlockHolder calls holdBlock() to create a Block node under ShadowRoot, you can modify its visibility strategy.

For how to find the BlockID, refer to Mount content directly without using annotations.

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

// 修改策略为：一旦跟踪到就永久显示
block.visibleStrategy = BlockVisibleStrategy.VisibleAfterFirstTracked;

The default VisibleStrategy is VisibleWhileTracked, which means the content of the Block (including child nodes) is displayed if and only if the Block is being tracked by MegaTracker.

Content editing and modification methods

• Modify an object's Transform

  For an Element in the scene, you need to call its getComponent() method to obtain the corresponding Component before modifying it.

  const xrFrameSystem = wx.getXrFrameSystem();
  let transform = model.getComponent(xrFrameSystem.Transform);
  transform.position.setValue(1.0, 0.0, -1.0);
  /** 拷贝原本的四元数 */
  let originalQuaternion = modelTF.quaternion.clone();
  /** 绕Y旋转 180 度 */
  let targetQuaternion = originalQuaternion.multiply(new xrFrameSystem.Quaternion().setValue(0, 1, 0, 0));
  transform.quaternion.setValue(targetQuaternion);
  

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

• Replace texture

  Before replacing a texture, you need to manually load the texture resource itself by calling loadAsset through the resource management system of the xr-frame scene.

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

  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 uses the scene resource manager to load a textureAsset, and then uses it to replace the texture of the GLTF model.

• Replace registered material

  To replace a registered material, first call getAsset() through the resource management system of the xr-frame scene to obtain the material resource.

  Then obtain the model's GLTF property, and call setData on each mesh to change the material property to the target material.

  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 uses the scene resource manager to load the occlusion material easyar-occlusion registered by EasyAR, and then sets it as the material of the GLTF model.