Cara memuat konten 3D dalam scene AR saat runtime di xr-frame

Artikel ini menjelaskan secara detail mekanisme pemisahan antara resource loading dan node mounting di xr-frame. Dengan script dinamis, konten 3D dapat dipasang secara fleksibel di bawah node Block untuk mewujudkan AR.

Materi resmi

Panduan pengembangan xr-frame: dokumentasi resmi XR engine WeChat.
Contoh resmi xr-frame: berisi berbagai contoh penggunaan dasar dan lanjutan.

Materi resmi sudah cukup menjelaskan cara memuat konten 3D saat runtime. Artikel ini hanya menjelaskan secara singkat beberapa konten dan metode loading yang umum digunakan dalam scene AR.

Resource loading vs node mounting

Di xr-frame, menampilkan model 3D dibagi menjadi dua tahap:

Resource loading: mengunduh file model (misalnya .glb) dari jaringan atau lokal, lalu menguraikannya ke memori. Pada saat ini model sudah siap, tetapi belum terlihat di scene.
Node mounting: membuat node dalam scene tree dan mengaitkan resource yang sudah dimuat ke node tersebut. Baru pada saat ini model resmi muncul di rendering canvas.

Cara menggunakan kode untuk memuat konten 3D secara dinamis

Resource loading

Panggil loadAsset melalui sistem manajemen resource scene xr-frame untuk memuat resource secara manual.

type dalam parameter menunjukkan tipe resource, assetId menunjukkan id resource setelah dimuat, dan src menunjukkan url resource, biasanya alamat resource hosting server.

Catat assetId untuk mounting dan pelepasan resource berikutnya.
```
try {
    await scene.assets.loadAsset({type: 'gltf', assetId: 'panda', src: 'url/EasyARPanda.glb'});
} catch (err) {
    console.error(`Failed to load assets: ${err.message}`);
}
```

Node mounting

Gunakan element.addChild() untuk menempatkan model yang sudah dimuat di bawah ShadowRoot.

const root = scene.getElementById("shadow-root");
let panda = scene.createElement(xrFrameSystem.XRGLTF,
    {
        "model": "panda",
        "anim-autoplay": ""
    }
);
root.addChild(panda);

Elemen ShadowRoot adalah root node khusus xr-frame untuk mencegah pembuatan dan penghapusan node secara dinamis. Lihat node Shadow untuk detail.

Metode createXRNodeFromNodeAnnotation yang disediakan object plugin dapat membuat child node Block berdasarkan data EMA, sehingga konten 3D tampil pada posisi spasial yang benar.

const nodeAnnotation = annotation as easyar.ema.v0_5.Node;
const xrNode: xrfs.XRNode = easyarPlugin.createXRNodeFromNodeAnnotation(nodeAnnotation, blockHolder);
let panda = scene.createElement(xrFrameSystem.XRGLTF,
    {
        "model": "panda",
        "anim-autoplay": ""
    }
);
xrNode.addChild(panda);

Cara memasang konten langsung di bawah Block tanpa menggunakan annotation

Peringatan

Prasyarat penggunaan metode ini adalah Anda telah memverifikasi bahwa nilai LocalTransform tersebut dapat mencapai efek rendering yang diharapkan dalam sistem koordinat xr-frame.

Untuk situasi lain, gunakan fungsi annotation Unity Editor.

Dapatkan object node block pada scene tree melalui getBlockById(id). Jika node block yang sesuai tidak ada, berarti localization untuk Block ini belum pernah berhasil (node akan dibuat otomatis saat pertama kali berhasil localization ke Block tersebut). Anda dapat menggunakan holdBlock(blockInfo, blockTransformInput) untuk membuat node Block ini, atau menunggu localization callback memastikan localization Block berhasil sebelum mounting konten.

Kiat

Pilih node Block dalam scene tree Unity Editor dan catat ID yang ditampilkan di panel Inspector

BlockID di Unity Editor

Block ID juga dapat ditemukan di halaman cloud localization library

BlockID di localization library

const blockID = "aaaa1234-bbbb-cccc-dddd-eeeeee123456"
if (!blockHolder.getBlockById(blockParent.id)) {
    // tidak ada node Block; buat satu
    blockHolder.holdBlock({
        id: blockID
    })
}
let blockElement = blockHolder.getBlockById(blockParent.id).el;

Pasang model node di bawah Block tertentu, lalu gunakan position.setArray(), quaternion.set(), dan scale.setArray() untuk mengubah LocalTransform model node.

export interface LocalTransform {
    /** @description posisi */
    position: xrfs.Vector3;
    /** @description rotasi */
    rotation: xrfs.Quaternion;
    /** @description Scale */
    scale: xrfs.Vector3;
}

// anggap ada LocalTransform yang sudah diketahui di bawah Block
const targetTransform: LocalTransform;

blockElement.addChild(modelNode);
let modelTransform = modelNode.getComponent(xrFrameSystem.Transform);
    modelTransform.position.setArray([
        targetTransform.position.x,
        targetTransform.position.y,
        targetTransform.position.z
    ]);
    let annoRotation = new xrFrameSystem.Quaternion().setValue(
        targetTransform.rotation.x,
        targetTransform.rotation.y,
        targetTransform.rotation.z,
        targetTransform.rotation.w
    );
    modelTransform.quaternion.set(annoRotation);
    modelTransform.scale.setArray([
        targetTransform.scale.x,
        targetTransform.scale.y,
        targetTransform.scale.z
    ]);

Tipe resource yang didukung xr-frame

Texture, tekstur dan gambar
CubeTexture, tekstur kubus
VideoTexture, tekstur video
EnvData, environment
GLTF model
Keyframe, frame animation
Atlas

Metode loading detail untuk setiap resource dapat dilihat di dokumentasi resmi WeChat dan contoh resmi xr-frame

Catatan

Untuk format dan extension GLTF yang didukung, lihat instruksi resmi penggunaan GLTF xr-frame

Table of Contents