Integrate the mega plugin into your wechat mini program

This document will walk you through the integration of the mega plugin in the xr-frame mini program environment.

Before you start

Refer to the xr-frame development guide and xr-frame official examples to learn how to use the official XR-3D engine provided by WeChat, including:
- How to introduce xr-frame components in regular WeChat mini program pages.
- Communication methods between xr-frame components and traditional mini program components.
- How to get or create an element from the scene and modify properties like Transform.
- Loading and releasing resources, such as GLTF models.

Global configuration

Add the dependency for the mega mini program plugin in the app.json global configuration file under the mini program root directory, and change dependency loading to requiredComponents.

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //Use the latest plugin version
      "provider": "wx27fa3b52b5462e8f" // Fixed id for the mega mini program plugin
    }
  }
}

Load the plugin

You can introduce the plugin through the plugin interface and directly use some of its methods to verify that the plugin has been loaded correctly.

For example, use WeChat's requirePlugin(string path) interface to obtain EasyARWechatMiniprogramPlugin, then use its isMegaTrackerSupported method to determine if the device is supported.

//If typings files have been imported
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//Call isMegaTrackerSupported to determine if the current device is supported, if not, prompt with a popup
if (!easyarPlugin.isMegaTrackerSupported()) {
    const message = `The current device does not support VK v1 and v2, please refer to the official WeChat documentation: https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/visionkit/plane.html`;
    wx.showModal({
        title: "Device not supported",
        content: message,
        showCancel: false,
    });
    console.error(message);
    return;
}

In this example, first obtain easyarPlugin through WeChat's requirePlugin(string path) interface, then call its provided isMegaTrackerSupported method to determine if the current runtime environment is available. If not, prompt with a popup.

Import types

It is recommended to use Typescript for development.

Sample project path: /typings/types/easyar/lib.easyar.d.ts.

Copy to the same directory in your project, and reference it with triple-slash directives in /typings/types/index.d.ts:

/// <reference path="./easyar/lib.easyar.d.ts" />

When type objects are needed, you can obtain the type system IMegaSystem of the EasyAR mega WeChat mini program plugin through getMegaSystem.

const mega: easyar.IMegaSystem = easyarPlugin.getMegaSystem();

You can then use the types exposed in IMegaSystem for type comparison. For example, compare state with mega.SessionState.Running to determine if the session initialization was successful:

const newState: easyar.SessionState = event.detail.value;
if (newState === mega.SessionState.Running) {
    console.log("EasyAR Session initialized succeeded. Start running.");
}

xr-frame scene setup (WXML)

In the WXML file of the page, the xr-easyar-mega component must be a child node of xr-scene, and correctly bind the id of the camera and tracker. If id is not filled, the component will use the first xr-camera and xr-ar-tracker components found in the scene.

<xr-scene id="xr-scene" ar-system="modes:Plane; planeMode: 1" bind:ready="handleReady">
    <xr-easyar-mega
        id="easyar-mega"
        camera-id="xrCamera"
        ar-tracker-id="xrARTracker"
    ></xr-easyar-mega>
    <xr-node>
        <xr-ar-tracker id="xrARTracker" mode="Plane"></xr-ar-tracker>
        <xr-camera id="xrCamera" node-id="xrCamera" clear-color="0.925 0.925 0.925 1" background="ar" is-ar-camera></xr-camera>
    </xr-node>
    <xr-shadow id="shadow-root" node-id="xrShadow"></xr-shadow>
</xr-scene>

Caution

The planeMode of ar-system must be set to 1

Register mega plugin event callbacks

<xr-easyar-mega
    id="easyar-mega"
    camera-id="xrCamera"
    ar-tracker-id="xrARTracker"
    bind:sessionStateChange="onSessionStateChange"
    bind:megaLocalizationResult="onMegaLocalizationResult"
    bind:postSessionUpdate="onPostSessionUpdate"
></xr-easyar-mega>

Bind events dispatched by the xr-frame element proxy in WXML. For xr-frame event dispatching mechanism, refer to xr-frame event mechanism.

Events dispatched by the plugin include:

Event name	Parameter type	Description
`SessionStateChange`	SessionState	Triggered immediately when the session state changes. The parameter is the new state of the session, used to handle session initialization start and success callbacks.
`MegaLocalizationResult`	MegaLocalizationResult	Triggered after the rendering frame that received the mega localization result completes its update. When this event triggers, all transform changes controlled by EasyAR within that rendering frame have been completed.
`PostSessionUpdate`	No parameters	Triggered immediately after the session completes its update in the rendering frame. At this point, all transform changes controlled by EasyAR within that frame have been completed.

AR Session

For session creation, start, and destruction, see AR session process control.

Confirm whether initialization is successful through the sessionStateChange event callback. When the state changes to Running, it can be considered that the ARSession is ready.

Register the onSessionStateChange() function in the xr-frame component as a callback for the sessionStateChange event in WXML via bind:sessionStateChange="onSessionStateChange":

<xr-easyar-mega
    bind:sessionStateChange="onSessionStateChange"
></xr-easyar-mega>

In the callback function onSessionStateChange() in the xr-frame component, compare the session state with each enumeration of SessionState to determine the current session state.

onSessionStateChange(event) {
    const newState: easyar.SessionState = event.detail.value;
    console.log(`EasyAR Session state changed to: ${mega.SessionState[newState]}`);
    let displayInfoStr: string = "";
    if (newState === mega.SessionState.None) {
        displayInfoStr = "EasyAR Session is inactive.";
    } else if (newState === mega.SessionState.Initializing) {
        displayInfoStr = "EasyAR Session is initializing...";
    } else if (newState === mega.SessionState.Running) {
        displayInfoStr = "EasyAR Session initialized succeeded. Start running.";
    }
    this.triggerEvent("sessionDisplayInfoEvent", displayInfoStr);
}

In the above code, after initialization completes, the console should print "EasyAR Session initialized succeeded. Start running."

Table of Contents