Membuat, mengontrol, dan mengelola entity

Perangkat XR yang kompatibel
Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.
Mempelajari jenis perangkat XR →
Headset XR
Kacamata XR Berkabel
Mempelajari jenis perangkat XR →

Jetpack XR SDK memungkinkan Anda menggunakan Jetpack SceneCore untuk membuat, mengontrol, dan mengelola Entity instance seperti model 3D, video stereoskopik, dan PanelEntity menggunakan Jetpack SceneCore.

Jetpack SceneCore mengadopsi dua pola arsitektur umum untuk mendukung pengembangan 3D: grafik scene dan sistem komponen entity (ECS).

Menggunakan grafik scene untuk membuat dan mengontrol entity

Untuk membuat dan mengontrol objek dalam ruang 3D, Anda dapat menggunakan Session API Jetpack SceneCore's untuk mendapatkan akses ke grafik scene. Grafik scene selaras dengan dunia nyata pengguna dan memungkinkan Anda mengatur entity 3D seperti panel dan model 3D ke dalam struktur hierarkis, serta menyimpan status entity tersebut.

Setelah mendapatkan akses ke grafik scene, Anda dapat menggunakan API di Jetpack Compose untuk XR guna membuat UI spasial (misalnya, SpatialPanel dan Orbiter instance) dalam grafik scene. Untuk konten 3D seperti model 3D, Anda dapat mengakses Sesi secara langsung. Untuk mempelajari lebih lanjut, lihat Tentang ActivitySpace di halaman ini.

Sistem komponen entity

Sistem komponen entity mengikuti prinsip komposisi atas inheritance. Anda dapat memperluas perilaku entity dengan melampirkan komponen yang menentukan perilaku, yang memungkinkan Anda menerapkan perilaku yang sama ke berbagai jenis entity. Untuk mengetahui informasi selengkapnya, lihat Menambahkan perilaku umum ke entity di halaman ini.

Tentang ActivitySpace

Setiap Session memiliki ActivitySpace yang otomatis dibuat dengan Session. ActivitySpace adalah Entity tingkat atas dalam grafik scene.

ActivitySpace mewakili ruang 3 dimensi dengan sistem koordinat tangan kanan (sumbu x mengarah ke kanan, sumbu y mengarah ke atas, dan sumbu z mengarah ke belakang relatif terhadap asal) dan dengan meter untuk unit yang cocok dengan dunia nyata. Asal untuk ActivitySpace agak arbitrer (karena pengguna dapat mereset posisi ActivitySpace dalam dunia nyata), sehingga sebaiknya posisikan konten relatif satu sama lain, bukan relatif terhadap asal.

Bekerja dengan Entity

Entity adalah pusat SceneCore. Hampir semua yang dilihat dan berinteraksi dengan pengguna adalah entity yang mewakili panel, model 3D, dan lainnya.

Karena ActivitySpace adalah node tingkat atas dari grafik scene, secara default, semua entity baru ditempatkan langsung ke ActivitySpace. Anda dapat memindahkan entity di sepanjang grafik scene dengan menetapkan parent atau menggunakan addChild().

Entity memiliki beberapa perilaku default untuk hal-hal yang bersifat universal bagi semua entity, seperti mengubah posisi, rotasi, atau visibilitas. Subclass Entity tertentu, seperti GltfModelEntity, memiliki perilaku tambahan yang mendukung subclass.

Memanipulasi Entity

Saat Anda membuat perubahan pada properti Entity yang termasuk dalam class Entity dasar, perubahan tersebut akan diterapkan ke semua turunannya. Misalnya, menyesuaikan Pose dari Entity induk akan menghasilkan semua turunannya memiliki penyesuaian yang sama. Membuat perubahan di Entity turunan tidak akan memengaruhi induknya.

Pose mewakili lokasi dan rotasi Entity dalam ruang 3D. Lokasinya adalah Vector3 yang terdiri dari posisi numerik x, y, z. Rotasi diwakili oleh Quaternion. Posisi Entity selalu relatif terhadap entity induknya. Dengan kata lain, Entity yang posisinya (0, 0, 0) akan ditempatkan di asal entity induknya.

// Place the entity forward 2 meters
val newPosition = Vector3(0f, 0f, -2f)
// Rotate the entity by 180 degrees on the up axis (upside-down)
val newOrientation = Quaternion.fromEulerAngles(0f, 0f, 180f)
// Update the position and rotation on the entity
entity.setPose(Pose(newPosition, newOrientation))

Untuk menonaktifkan Entity, gunakan setEnabled(). Tindakan ini akan membuatnya tidak terlihat dan menghentikan semua pemrosesan yang dilakukan di dalamnya.

// Disable the entity.
entity.setEnabled(false)

Untuk mengubah ukuran Entity sambil mempertahankan bentuk keseluruhannya, gunakan setScale().

// Double the size of the entity
entity.setScale(2f)

Menambahkan perilaku umum ke entity

Anda dapat menggunakan komponen berikut untuk menambahkan perilaku umum ke entity:

Membuat instance komponen harus dilakukan melalui metode pembuatan yang sesuai di class Session. Misalnya, untuk membuat ResizableComponent, panggil ResizableComponent.create().

Untuk menambahkan perilaku komponen tertentu ke Entity, gunakan metode addComponent().

Menggunakan MovableComponent untuk membuat Entity dapat dipindahkan pengguna

The MovableComponent memungkinkan Entity dapat dipindahkan oleh pengguna.

Peristiwa pergerakan dikirim ke komponen saat dekorasi berinteraksi. Perilaku sistem default, yang dibuat dengan MovableComponent.createSystemMovable(), memindahkan Entity saat the dekorasi ditarik:

val movableComponent = MovableComponent.createSystemMovable(session)
entity.addComponent(movableComponent)

Parameter scaleInZ opsional (secara default, ditetapkan ke true), membuat Entity otomatis menyesuaikan skalanya saat dipindahkan dari pengguna, dengan cara yang sama seperti panel yang diskalakan oleh sistem di ruang utama. Karena sifat "berjenjang" dari sistem komponen entity, skala induk akan memengaruhi semua turunannya.

Anda juga dapat menentukan apakah entity dapat di-anchor ke jenis permukaan seperti permukaan horizontal atau vertikal, atau permukaan semantik tertentu seperti meja, dinding, atau langit-langit. Untuk menentukan opsi anchor, tentukan kumpulan AnchorPlacement saat membuat MovableComponent. Dalam contoh ini, entity yang dapat dipindahkan dan di-anchor ke lantai atau permukaan horizontal meja:

val anchorPlacement = AnchorPlacement.createForPlanes(
    anchorablePlaneOrientations = setOf(PlaneOrientation.VERTICAL),
    anchorablePlaneSemanticTypes = setOf(PlaneSemanticType.FLOOR, PlaneSemanticType.TABLE)
)

val movableComponent = MovableComponent.createAnchorable(
    session = session,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)

Menggunakan ResizableComponent untuk membuat Entity dapat diubah ukurannya oleh pengguna

The ResizableComponent memungkinkan pengguna mengubah ukuran Entity. ResizableComponent menyertakan petunjuk interaksi visual yang meminta pengguna untuk mengubah ukuran Entity. Saat membuat ResizableComponent, Anda dapat menentukan ukuran minimum atau maksimum (dalam meter). Anda juga memiliki opsi untuk menentukan rasio aspek tetap saat mengubah ukuran sehingga lebar dan tinggi berubah ukuran secara proporsional satu sama lain.

Saat membuat ResizableComponent, tentukan resizeEventListener yang menangani peristiwa update. Anda dapat merespons peristiwa ResizeState yang berbeda, seperti RESIZE_STATE_ONGOING atau RESIZE_STATE_END.

Berikut adalah contoh penggunaan ResizableComponent dengan rasio aspek tetap pada SurfaceEntity:

val resizableComponent = ResizableComponent.create(session) { event ->
    if (event.resizeState == ResizeEvent.ResizeState.END) {
        // update the Entity to reflect the new size
        surfaceEntity.shape = SurfaceEntity.Shape.Quad(FloatSize2d(event.newSize.width, event.newSize.height))
    }
}
resizableComponent.minimumEntitySize = FloatSize3d(177f, 100f, 1f)
resizableComponent.isFixedAspectRatioEnabled = true // Maintain a fixed aspect ratio when resizing

surfaceEntity.addComponent(resizableComponent)

Menggunakan InteractableComponent untuk menangkap peristiwa input pengguna

The InteractableComponent memungkinkan Anda menangkap peristiwa input dari pengguna, seperti saat pengguna berinteraksi atau mengarahkan kursor ke Entity. Saat membuat InteractableComponent, tentukan pemroses yang menerima peristiwa input. Saat pengguna melakukan tindakan input apa pun, pemroses akan dipanggil dengan informasi input yang diberikan dalam InputEvent parameter.

Untuk mengetahui daftar lengkap semua konstanta InputEvent, lihat dokumentasi referensi.

Cuplikan kode berikut menunjukkan contoh penggunaan InteractableComponent untuk menambah ukuran entity dengan tangan kanan dan mengurangi dengan tangan kiri.

val executor = Executors.newSingleThreadExecutor()
val interactableComponent = InteractableComponent.create(session, executor) {
    // when the user disengages with the entity with their hands
    if (it.source == InputEvent.Source.HANDS && it.action == InputEvent.Action.UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.Pointer.RIGHT) {
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.Pointer.LEFT) {
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)

Membuat model 3D kustom saat runtime

Custom Mesh API memungkinkan Anda membuat bentuk 3D secara terprogram langsung dalam kode, bukan memuat aset statis seperti file glTF. Dengan membuat geometri kustom dengan cepat, Anda dapat merender data prosedural, bentuk kustom dinamis, dan lingkungan 3D yang tampaknya tidak terbatas seperti medan yang terus dibuat saat pengguna menjelajah. Selain itu, pembuatan mesh saat runtime berkontribusi pada ukuran biner yang lebih kecil dengan menghilangkan kebutuhan untuk mengemas variasi aset 3D tunggal yang tak terhitung jumlahnya.