Integrate the mega plugin into your WeChat mini program

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

Before you begin

Refer to the xr-frame development guide and xr-frame official examples to learn how to use the XR-3D engine provided by WeChat, including:
- How to introduce the xr-frame component in a regular WeChat Mini Program page.
- The communication methods between the xr-frame component and traditional Mini Program components.
- How to retrieve or create an element from a scene and modify certain properties such as Transform.
- Loading and releasing resources, such as GLTF models.

Global configuration

In the app.json global configuration file in the root directory of the mini-program, add the dependency for the Mega mini-program plugin, and change the dependency loading to on-demand injection.

{
  "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
    }
  }
}

Loading the plugin

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

For example, after obtaining the EasyARWechatMiniprogramPlugin using the requirePlugin(string path) interface provided by WeChat, you can use its isMegaTrackerSupported method to check if the device supports it.

//if the typings file has been imported
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
//call isMegaTrackerSupported to check if the current device supports it, and show a prompt if not supported
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, the easyarPlugin (the interface object exposed by the plugin) is first obtained through the requirePlugin(string path) interface provided by WeChat. Then, its provided isMegaTrackerSupported method is called to check if it is available in the current runtime environment. If not, a prompt is displayed.

Introducing types

It is recommended to use Typescript for development.

The path in the sample project: /typings/types/easyar/lib.easyar.d.ts.

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

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

When you need to use type objects, you can obtain the type system IMegaSystem of the EasyAR Mega WeChat Mini Program plugin through getMegaSystem.

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

After that, you can use the types exposed in IMegaSystem for type comparison. For example, you can 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 the id of the camera and tracker must be correctly bound. If the id is not filled in, 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 event callbacks for the Mega plugin

<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 the events dispatched by the xr-frame Element proxy in WXML. For the event dispatch mechanism of xr-frame, refer to xr-frame event mechanism.

The events dispatched by the plugin are:

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 the callback for Session initialization start and success.
`MegaLocalizationResult`	MegaLocalizationResult	Triggered after the rendering frame with Mega localization results is updated. When the event is triggered, all Transform changes controlled by EasyAR in this rendering frame have been completed.
`PostSessionUpdate`	No parameters	Triggered immediately after the Session is updated in the rendering frame. At this time, all Transform changes controlled by EasyAR in this frame have been completed.

Ar session

The creation, startup, and destruction of a session can be found in AR session flow control.

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

In WXML, register the onSessionStateChange() function in the xr-frame component as the callback for the sessionStateChange event through 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 the enumerations of SessionState to determine the current state of the session.

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 is completed, the console should print "EasyAR Session initialized succeeded. Start running."

Table of Contents