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 komponen entitas 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 menetapkan parent atau menggunakan 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 menonaktifkan Entity, gunakan setEnabled(). Hal ini membuatnya tidak terlihat dan menghentikan semua pemrosesan yang dilakukan di dalamnya.

// Disable the entity.
entity.setEnabled(false)
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.

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

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

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

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. Dalam contoh ini, entity yang dapat dipindahkan dan dijangkarkan ke permukaan horizontal lantai atau 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)
MovableComponent.kt

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 membuat ResizableComponent, tentukan resizeEventListener yang menangani peristiwa update. Anda dapat merespons berbagai peristiwa ResizeState, 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.RESIZE_STATE_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)
ResizableComponent.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, tentukan pemroses yang menerima peristiwa input. Saat pengguna melakukan tindakan input apa pun, pendengar akan dipanggil dengan informasi input 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.SOURCE_HANDS && it.action == InputEvent.Action.ACTION_UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.Pointer.POINTER_TYPE_RIGHT) {
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.Pointer.POINTER_TYPE_LEFT) {
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)
InteractableComponent.kt