Mega プラグインを WeChat ミニプログラムに接続する

このドキュメントでは、xr-frame ミニプログラム環境への Mega プラグインの統合手順を説明します。

開始する前に

• xr-frame 開発ガイドおよびxr-frame 公式サンプルを参照し、WeChat 公式が提供する XR-3D エンジンの使用方法を学習してください。内容は以下の通りです：
  • 通常の WeChat ミニプログラムページで xr-frame コンポーネントを導入する方法。
  • xr-frame コンポーネントとミニプログラムの従来のコンポーネント間の通信方法。
  • シーンから要素を取得または作成し、Transform などのプロパティを変更する方法。
  • GLTF モデルなどのリソースの読み込みと解放。

グローバル設定

ミニプログラムのルートディレクトリにある app.json グローバル設定ファイルに、Mega ミニプログラムプラグインへの依存関係を追加し、依存関係のロードをオンデマンド注入に変更します。

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //最新のプラグインバージョンを使用
      "provider": "wx27fa3b52b5462e8f" // Mega ミニプログラムプラグイン固定 ID
    }
  }
}

プラグインのロード

プラグインインターフェースを通じてプラグインを導入し、プラグインの一部のメソッドを直接使用して、プラグインが正しくロードされていることを確認できます。

たとえば、WeChat が提供する requirePlugin(string path) インターフェースを使用して EasyARWechatMiniprogramPlugin を取得した後、その isMegaTrackerSupported メソッドを使用して、デバイスがサポートされているかどうかを判断します。

// typings ファイルがすでに導入されている場合
//const easyarPlugin: easyar.EasyARWechatMiniprogramPlugin = requirePlugin("easyar-wechat-miniprogram") as easyar.EasyARWechatMiniprogramPlugin;
const easyarPlugin = requirePlugin("easyar-wechat-miniprogram") as any;
// isMegaTrackerSupported を呼び出して、現在のデバイスがサポートされているかどうかを判断し、サポートされていない場合は警告を表示
if (!easyarPlugin.isMegaTrackerSupported()) {
    const message = `現在のデバイスは VK v1 および v2 をサポートしていません。WeChat 公式ドキュメントを参照してください：https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/visionkit/plane.html`;
    wx.showModal({
        title: "デバイスがサポートされていません",
        content: message,
        showCancel: false,
    });
    console.error(message);
    return;
}

この例では、まず WeChat が提供する requirePlugin(string path) インターフェースを使用して easyarPlugin、つまりプラグインが公開するインターフェースオブジェクトを取得し、その後、提供されている isMegaTrackerSupported メソッドを呼び出して、現在の実行環境で使用可能かどうかを判断しています。使用できない場合は警告を表示します。

型の導入

開発には Typescript の使用が推奨されます。

サンプルプロジェクト内のパス：/typings/types/easyar/lib.easyar.d.ts 。

プロジェクトの同じディレクトリにコピーし、/typings/types/index.d.ts でトリプルスラッシュディレクティブを使用して参照します：

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

型オブジェクトを使用する必要がある場合、getMegaSystem を使用して EasyAR Mega WeChat ミニプログラムプラグインの型システム IMegaSystem を取得できます。

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

その後、IMegaSystem で公開されている型を使用して型比較が可能です。たとえば、state が mega.SessionState.Running と等しいかどうかを比較して、セッションの初期化が成功したかどうかを判断できます：

const newState: easyar.SessionState = event.detail.value;
if (newState === mega.SessionState.Running) {
    console.log("EasyAR Session の初期化に成功しました。実行を開始します。");
}

xr-frame シーンの構築 (WXML)

ページの WXML ファイルでは、xr-easyar-mega コンポーネントは xr-scene の子ノードとして配置する必要があり、カメラとトラッカーの id を正しくバインドします。id が指定されていない場合、コンポーネントはシーンで最初に見つかった xr-camera および xr-ar-tracker コンポーネントを使用します。

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

[!警告] ar-system の planeMode は 1 に設定する必要があります

Mega プラグインのイベントコールバックを登録する

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

WXML で xr-frame Element プロキシが配信するイベントをバインドします。xr-frame のイベント配信メカニズムについては、xr-frame イベントメカニズムを参照してください。

プラグインが配信するイベントは次のとおりです：

イベント名	パラメータタイプ	説明
SessionStateChange	SessionState	セッションの状態が変更された直後にトリガーされます。パラメータはセッションの新しい状態で、セッションの初期化開始と成功のコールバックを処理するために使用されます。
MegaLocalizationResult	MegaLocalizationResult	Mega ローカライゼーション結果を受信し、レンダリングフレームの更新が完了した後にトリガーされます。イベントがトリガーされると、そのレンダリングフレーム内のすべての EasyAR 制御下の Transform 変更は完了しています。
PostSessionUpdate	パラメータなし	セッションがそのレンダリングフレームで更新を完了した直後にトリガーされます。この時点で、フレーム内のすべての EasyAR 制御下の Transform 変更は完了しています。

AR セッション

セッションの作成、開始、破棄については、AR セッション フロー制御を参照してください。

sessionStateChange イベントコールバックを通じて初期化が成功したかどうかを確認します。状態が Running に変わると、ARSession が準備完了と見なされます。

WXML で bind:sessionStateChange="onSessionStateChange" を使用して、xr-frame コンポーネント内の onSessionStateChange() 関数を sessionStateChange イベントのコールバックとして登録します：

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

xr-frame コンポーネント内のコールバック関数 onSessionStateChange() で、セッション状態を SessionState の各列挙値と比較して、セッションの現在の状態を判断できます。

onSessionStateChange(event) {
    const newState: easyar.SessionState = event.detail.value;
    console.log(`EasyAR セッションの状態が変更されました: ${mega.SessionState[newState]}`);
    let displayInfoStr: string = "";
    if (newState === mega.SessionState.None) {
        displayInfoStr = "EasyAR セッションは非アクティブです。";
    } else if (newState === mega.SessionState.Initializing) {
        displayInfoStr = "EasyAR セッションを初期化中...";
    } else if (newState === mega.SessionState.Running) {
        displayInfoStr = "EasyAR セッションの初期化に成功しました。実行を開始します。";
    }
    this.triggerEvent("sessionDisplayInfoEvent", displayInfoStr);
}

上記のコードでは、初期化が完了するとコンソールに "EasyAR セッションの初期化に成功しました。実行を開始します。" と表示されます。

関連トピック

• 完全な実行サンプルプロジェクト
• AR セッション フロー制御
• サンプルプロジェクトの説明