Mega 플러그인을 당신의 위챗 미니프로그램에 통합하기

이 문서는 xr-frame 미니프로그램 환경에서 Mega 플러그인 통합을 완료하는 과정을 안내합니다.

시작하기 전에

xr-frame 개발 가이드 및 xr-frame 공식 샘플을 참고하여 위챗 공식 XR-3D 엔진 사용법을 학습하세요. 내용은 다음과 같습니다:
- 일반 위챗 미니프로그램 페이지에서 xr-frame 컴포넌트를 도입하는 방법.
- xr-frame 컴포넌트와 미니프로그램 전통 컴포넌트 간 통신 방식.
- 장면에서 요소를 가져오거나 생성하고 Transform과 같은 일부 속성을 수정하는 방법.
- GLTF 모델과 같은 리소스 로드 및 해제.

글로벌 구성

미니프로그램 루트 디렉터리의 app.json 글로벌 구성 파일에 Mega 미니프로그램 플러그인 의존성을 추가하고, 의존성 로드를 주입 시 필요 시로 변경하세요.

{
  "lazyCodeLoading": "requiredComponents",
  "plugins": {
    "easyar-wechat-miniprogram": {
      "version": "2.0.2", //최신 플러그인 버전 사용
      "provider": "wx27fa3b52b5462e8f" // Mega 미니프로그램 플러그인 고정 ID
    }
  }
}

플러그인 로드

플러그인 인터페이스를 통해 플러그인을 도입하고, 플러그인이 올바르게 로드되었는지 확인하기 위해 플러그인의 일부 메서드를 직접 사용할 수 있습니다.

예를 들어, 위챗에서 제공하는 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를 지원하지 않습니다. 위챗 공식 문서를 참고하세요: https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/visionkit/plane.html`;
    wx.showModal({
        title: "기기 미지원",
        content: message,
        showCancel: false,
    });
    console.error(message);
    return;
}

이 예시에서는 먼저 위챗에서 제공하는 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 위챗 미니프로그램 플러그인의 타입 시스템 IMegaSystem을 가져올 수 있습니다.

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

이후 IMegaSystem에서 노출된 타입을 사용하여 타입 비교를 할 수 있습니다. 예를 들어 state를 mega.SessionState.Running과 비교하여 session 초기화 성공 여부를 판단할 수 있습니다:

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

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	Session 상태가 변경될 때 즉시 트리거됩니다. 파라미터는 Session의 새로운 상태로, Session 초기화 시작 및 성공 콜백 처리에 사용됩니다.
`MegaLocalizationResult`	MegaLocalizationResult	Mega 로컬라이제이션 결과를 수신한 렌더링 프레임 업데이트 완료 후 트리거됩니다. 이벤트 트리거 시, 해당 렌더링 프레임 내에서 EasyAR에 의해 제어되는 모든 Transform 변경이 완료되었습니다.
`PostSessionUpdate`	파라미터 없음	해당 렌더링 프레임에서 Session 업데이트 완료 후 즉시 트리거됩니다. 이때 해당 프레임 내에서 EasyAR에 의해 제어되는 모든 Transform 변경이 완료되었습니다.

AR Session

session 생성, 시작 및 소멸은 AR Session 프로세스 제어를 참고하세요.

sessionStateChange 이벤트 콜백을 통해 초기화 성공 여부를 확인합니다. 상태가 Running로 변경되면 ARSession이 준비되었음을 의미합니다.

WXML에서 bind:sessionStateChange="onSessionStateChange"를 통해 xr-frame 컴포넌트의 onSessionStateChange() 함수를 sessionStateChange 이벤트의 콜백으로 등록합니다:

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

xr-frame 컴포넌트의 콜백 함수 onSessionStateChange()에서 session 상태를 SessionState의 각 열거형과 비교하여 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);
}

위 코드에서 초기화 완료 후 콘솔에 "EasyAR Session initialized succeeded. Start running."이 출력되어야 합니다.

Table of Contents