Membuat, mengontrol, dan mengelola entity

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

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

Menggunakan grafik adegan untuk membuat dan mengontrol entitas

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

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

Sistem komponen entitas

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

Tentang ActivitySpace

Setiap Session memiliki ActivitySpace yang dibuat secara otomatis dengan Session. ActivitySpace adalah Entity tingkat teratas dalam grafik adegan.

ActivitySpace merepresentasikan 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 titik asal) dan dengan satuan meter yang sesuai dengan dunia nyata. Asal untuk ActivitySpace agak arbitrer (karena pengguna dapat mereset posisi ActivitySpace dalam dunia nyata), oleh karena itu, sebaiknya posisikan konten relatif satu sama lain, bukan relatif terhadap asal.

Bekerja dengan Entity

Entitas adalah inti dari SceneCore. Sebagian besar hal yang dilihat dan berinteraksi dengan pengguna adalah entitas yang merepresentasikan panel, model 3D, dan lainnya.

Karena ActivitySpace adalah node tingkat teratas dari grafik adegan, secara default, semua entity baru ditempatkan langsung ke ActivitySpace. Anda dapat memindahkan entitas di sepanjang grafik adegan dengan memanggil setParent() atau addChild().

Entitas memiliki beberapa perilaku default untuk hal-hal yang bersifat universal bagi semua entitas, 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 di-cascade ke semua turunannya. Misalnya, menyesuaikan Pose dari Entity induk akan membuat semua turunannya memiliki penyesuaian yang sama. Melakukan perubahan pada Entity turunan tidak akan memengaruhi induknya.

Pose merepresentasikan lokasi dan rotasi Entitas dalam ruang 3D. Lokasinya adalah Vector3 yang terdiri dari posisi numerik x, y, z. Rotasi direpresentasikan oleh Quaternion. Posisi Entity selalu relatif terhadap entity induknya. Dengan kata lain, Entity yang posisinya adalah (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))
Entities.kt

Untuk mengubah visibilitas Entity, gunakan setHidden().

// Hide the entity
entity.setHidden(true)
Entities.kt

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

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

Menambahkan perilaku umum ke entitas

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

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

MovableComponent memungkinkan Entity dapat dipindahkan oleh pengguna. Anda juga dapat menentukan apakah entitas dapat dijangkarkan ke jenis permukaan seperti permukaan horizontal atau vertikal, atau permukaan semantik tertentu seperti meja, dinding atau langit-langit. Untuk menentukan opsi penahan, tentukan serangkaian AnchorPlacement saat membuat MovableComponent.

Berikut adalah contoh entitas yang dapat dipindahkan dan ditambatkan ke permukaan vertikal mana pun dan hanya permukaan horizontal lantai dan langit-langit.

val anchorPlacement = AnchorPlacement.createForPlanes(
    planeTypeFilter = setOf(PlaneSemantic.FLOOR, PlaneSemantic.TABLE),
    planeSemanticFilter = setOf(PlaneType.VERTICAL)
)

val movableComponent = MovableComponent.create(
    session = session,
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)
Entities.kt

Saat pengguna memindahkan entitas, parameter scaleInZ akan otomatis menyesuaikan skala entitas saat entitas bergerak menjauhi pengguna dengan cara yang serupa dengan cara panel diskalakan oleh sistem di ruang beranda. Karena sifat "berjenjang" dari sistem komponen entity, skala induk akan memengaruhi semua turunannya.

Menggunakan ResizableComponent untuk membuat Entity dapat diubah ukurannya oleh pengguna

ResizableComponent memungkinkan pengguna mengubah ukuran Entity. ResizableComponent mencakup isyarat interaksi visual yang mengundang 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 diubah ukurannya secara proporsional satu sama lain.

Saat menggunakan ResizableComponent, Anda harus menentukan ResizeListener untuk merespons peristiwa pengubahan ukuran tertentu seperti onResizeUpdate atau onResizeEnd.

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

val resizableComponent = ResizableComponent.create(session)
resizableComponent.minimumSize = Dimensions(177f, 100f, 1f)
resizableComponent.fixedAspectRatio = 16f / 9f // Specify a 16:9 aspect ratio

resizableComponent.addResizeListener(
    executor,
    object : ResizeListener {
        override fun onResizeEnd(entity: Entity, finalSize: Dimensions) {

            // update the size in the component
            resizableComponent.size = finalSize

            // update the Entity to reflect the new size
            (entity as SurfaceEntity).canvasShape = SurfaceEntity.CanvasShape.Quad(finalSize.width, finalSize.height)
        }
    },
)

entity.addComponent(resizableComponent)
Entities.kt

Gunakan InteractableComponent untuk merekam peristiwa input pengguna

InteractableComponent memungkinkan Anda merekam peristiwa input dari pengguna, seperti saat pengguna berinteraksi atau mengarahkan kursor ke Entity. Saat membuat InteractableComponent, Anda harus menentukan InputEventListener untuk menerima peristiwa input. Saat pengguna melakukan tindakan input apa pun, metode onInputEvent akan dipanggil dengan informasi input spesifik yang diberikan dalam parameter InputEvent.

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

Cuplikan kode berikut menunjukkan contoh penggunaan InteractableComponent untuk memperbesar ukuran entity dengan tangan kanan dan memperkecil 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_TYPE_RIGHT) {
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.POINTER_TYPE_LEFT) {
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)
Entities.kt