ใช้คอนเทนเนอร์เชิงพื้นที่ใน Godot

อุปกรณ์ XR ที่รองรับ

คำแนะนำนี้จะช่วยคุณสร้างประสบการณ์การใช้งานสำหรับอุปกรณ์ XR ประเภทนี้

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

คอนเทนเนอร์เชิงมิติพื้นที่ช่วยให้แอปแสดงผลเนื้อหา OpenXR 3 มิติภายในกรอบล้อมรอบเชิงปริมาตร 3 มิติที่ระบบจัดการในโหมด Full Space หรือเปลี่ยนเป็นประสบการณ์การใช้งานแบบไม่จำกัดขอบเขตเต็มหน้าจอขณะรันไทม์

ทำตามคู่มือนี้เพื่อกำหนดค่าและใช้คอนเทนเนอร์เชิงพื้นที่ในโปรเจ็กต์

วิธีการทำงานของคอนเทนเนอร์เชิงพื้นที่

สิ่งที่จะเกิดขึ้นเมื่อเปิดใช้ Spatial Container ในการตั้งค่าโปรเจ็กต์มีดังนี้

• ฉาก 3 มิติที่ใช้งานอยู่ทั้งหมดจะอยู่ในคอนเทนเนอร์เชิงพื้นที่หลักรายการเดียวซึ่งมีศูนย์กลางอยู่ที่จุดเริ่มต้นของฉาก (0, 0, 0) คุณไม่จำเป็นต้องติดแท็กหรือกำหนดโหนด Node3D แต่ละโหนดเพื่อวางไว้ในคอนเทนเนอร์
• แอปจะเปิดขึ้นในโหมด Full Space ที่มีการจัดการโดยใช้โหมดขอบเขต (Bounded หรือ Immersive) และขนาดขอบเขตเริ่มต้นที่กำหนดค่าไว้ในการตั้งค่าโปรเจ็กต์ ในโหมดที่มีขอบเขต ระบบจะตัดเรขาคณิต 3 มิติในฉากที่ขยายออกนอกขนาดของกรอบล้อมรอบโดยอัตโนมัติ
• โดยค่าเริ่มต้น ระบบ Android XR จะมีตัวควบคุมหน้าต่างเพื่อให้ผู้ใช้สามารถจับ ย้าย และเปลี่ยนตำแหน่งคอนเทนเนอร์ที่มีขอบเขตในพื้นที่ 3 มิติ หรือย่อและปิดคอนเทนเนอร์ได้ ในรันไทม์ แอปของคุณสามารถปรับขนาดคอนเทนเนอร์ สลับระหว่างโหมดที่มีขอบเขต (OpenXRSpatialContainerState.BOUNDED) และโหมดใหญ่พิเศษแบบเต็มหน้าจอ (OpenXRSpatialContainerState.IMMERSIVE) และตอบสนองต่อการเปลี่ยนแปลงขอบเขตและสถานะโดยใช้ซิงเกิลตัน OpenXRSpatialContainerExtension

สิ่งที่ต้องมีก่อน

ก่อนเริ่มต้น โปรดตรวจสอบว่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์และอุปกรณ์เป้าหมายเป็นไปตามข้อกำหนดต่อไปนี้

• เวอร์ชัน Godot: Godot 4.8-dev ขึ้นไป
• การตั้งค่าโปรเจ็กต์: ทำตามขั้นตอนทั้งหมดในคู่มือการตั้งค่าโปรเจ็กต์ Godot Engine
• ปลั๊กอิน Godot OpenXR Vendors: ติดตั้งปลั๊กอิน Godot OpenXR Vendors เวอร์ชัน 5.2 ขึ้นไป ซึ่งจะเปิดใช้การรองรับส่วนขยายเฉพาะของ Android XR
• อุปกรณ์เป้าหมาย: อุปกรณ์ Android XR ที่รองรับ ระดับ API เชิงพื้นที่ 4 ขึ้นไป เมื่อรันไทม์ ให้เรียกใช้ OpenXRSpatialContainerExtension.is_enabled() เพื่อยืนยันว่าส่วนขยายพร้อมใช้งานในอุปกรณ์หรือไม่

เปิดใช้คอนเทนเนอร์เชิงพื้นที่ในการตั้งค่าโปรเจ็กต์

กำหนดค่าการตั้งค่าโปรเจ็กต์เพื่อเปิดใช้ OpenXR, คอนเทนเนอร์เชิงพื้นที่, สิทธิ์รันไทม์อัตโนมัติ และการส่งผ่านข้อมูลแบบผสมอัลฟ่า โดยทำดังนี้

1. เปิดโปรเจ็กต์ > การตั้งค่าโปรเจ็กต์
2. เปิดใช้ปุ่มสลับการตั้งค่าขั้นสูงที่มุมขวาบนของหน้าต่างการตั้งค่าโปรเจ็กต์
3. ไปที่ทั่วไป > XR > ตัวปรับเฉดสี แล้วเลือกเปิดใช้
4. ไปที่ทั่วไป > XR > OpenXR แล้วกำหนดการตั้งค่าต่อไปนี้
   • เลือกเปิดใช้เพื่อเปิด OpenXR สำหรับโปรเจ็กต์
   • ตั้งค่าโหมดการผสมสภาพแวดล้อมเป็นการผสมอัลฟ่า
5. นอกจากนี้ ในส่วน OpenXR ให้ไปที่ส่วนส่วนขยาย แล้วกำหนดการตั้งค่าต่อไปนี้
   • เลือกขอสิทธิ์รันไทม์โดยอัตโนมัติเพื่อให้แอปแจ้งผู้ใช้โดยอัตโนมัติเมื่อเริ่มต้นระบบสำหรับสิทธิ์ XR ที่ประกาศไว้ในไฟล์ Manifest ของ Android
   • ในส่วนย่อยคอนเทนเนอร์เชิงพื้นที่ ให้เลือกเปิดใช้
   • ตั้งค่าโหมดขอบเขตเป็นมีขอบเขตเพื่อเปิดในกรอบล้อมรอบ 3 มิติ หรือใหญ่พิเศษเพื่อเปิดในโหมดใหญ่พิเศษแบบเต็มหน้าจอ
   • ตั้งค่าขอบเขตเป็นขนาดความกว้าง ความสูง และความลึกเริ่มต้นในหน่วยเมตร เช่น Vector3(1.0, 1.0, 1.0)
6. ไปที่ทั่วไป > การแสดงผล > วิวพอร์ต แล้วเลือกพื้นหลังโปร่งใส

กำหนดค่าการส่งออก Android, สิทธิ์ และโหมด Full Space

ถัดไป ให้กำหนดค่าค่าที่กำหนดล่วงหน้าสำหรับการส่งออก Android, สิทธิ์ และโหมดเริ่มต้นกิจกรรมเพื่อให้แอปทำงานในโหมด Full Space โดยเปิดใช้คอนเทนเนอร์เชิงพื้นที่

กำหนดค่าค่าที่กำหนดล่วงหน้าสำหรับการส่งออก Android

1. ไปที่โปรเจ็กต์ > ส่งออก... แล้วเลือกค่าที่กำหนดล่วงหน้าสำหรับการส่งออก Android

2. ในส่วน Gradle Build ให้เลือกใช้ Gradle Build และตั้งค่า Min SDK เป็น 34 ขึ้นไป

   

3. ในส่วน XR Features ให้ตั้งค่า XR Mode เป็น OpenXR แล้วเลือก Enable AndroidXR Plugin

   

4. ในส่วนฟีเจอร์ Android XR ให้เลือกใช้ฟีเจอร์ทดลอง

เพิ่มสิทธิ์การทำความเข้าใจฉากสำหรับการล็อกพื้น

การสร้างและการแสดงผลคอนเทนเนอร์เชิงพื้นที่พื้นฐานไม่จำเป็นต้องใช้สิทธิ์รันไทม์ที่เป็นอันตราย (และระบบจะเพิ่ม android.permission.HEAD_TRACKING ลงในไฟล์ Manifest โดยอัตโนมัติเมื่อเปิดใช้ใช้ฟีเจอร์ทดลอง) อย่างไรก็ตาม หากแอปใช้ฟีเจอร์การทำความเข้าใจฉาก เช่น การล็อกและการตรึงคอนเทนเนอร์เชิงพื้นที่กับพื้นจริง แอปของคุณต้องประกาศและขอสิทธิ์ android.permission.SCENE_UNDERSTANDING_COARSE ขณะรันไทม์

ดูรายละเอียดเกี่ยวกับสิทธิ์ของ Android XR ได้ที่ทำความเข้าใจสิทธิ์สำหรับ XR หากแอปของคุณใช้การล็อกพื้นหรือการทำความเข้าใจฉาก ให้ประกาศและขอ android.permission.SCENE_UNDERSTANDING_COARSE:

1. ในโปรเจ็กต์ > ส่งออก... > Android ให้ไปที่สิทธิ์ > สิทธิ์ที่กำหนดเอง แล้วเพิ่ม android.permission.SCENE_UNDERSTANDING_COARSE

2. เมื่อเลือกขอสิทธิ์รันไทม์โดยอัตโนมัติในการตั้งค่าโปรเจ็กต์ > ทั่วไป > XR > OpenXR > ส่วนขยาย แอปจะขอสิทธิ์โดยอัตโนมัติเมื่อ OpenXR เริ่มทำงาน หากต้องการขอสิทธิ์ด้วยตนเองใน GDScript แทน ให้เรียกใช้ OS.request_permission():

   if not OS.get_granted_permissions().has("android.permission.SCENE_UNDERSTANDING_COARSE"):
       OS.request_permission("android.permission.SCENE_UNDERSTANDING_COARSE")
   

กำหนดค่าโหมด Full Space

คอนเทนเนอร์เชิงพื้นที่ใน Android XR รองรับเฉพาะโหมด Full Space (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED) เท่านั้น ตรวจสอบว่ากิจกรรม Android ประกาศ XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED ในเทมเพลตบิลด์ที่กำหนดเอง (android/build/AndroidManifest.xml ติดตั้งโดยใช้โปรเจ็กต์ > ติดตั้งเทมเพลตบิลด์ Android...)

<manifest ...>
    <application ...>
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED"
            tools:replace="android:value" />
        ...
    </application>
</manifest>

ทำงานกับคอนเทนเนอร์เชิงพื้นที่ใน GDScript

ซิงเกิลตัน OpenXRSpatialContainerExtension และคลาส OpenXRSpatialContainerState จะแสดงส่วนขยาย XR_EXT_spatial_container และ XR_EXT_spatial_container_self_rendering ใน GDScript ที่รันไทม์ ให้ใช้ OpenXRSpatialContainerExtension เพื่อตรวจสอบสถานะและขอบเขตของคอนเทนเนอร์เชิงพื้นที่หลัก ฟังสัญญาณคอนเทนเนอร์ และขอการเปลี่ยนระหว่างโหมด BOUNDED (กรอบล้อมรอบ 3 มิติ) และโหมด IMMERSIVE (มุมมองแบบเต็มหน้าจอที่ไม่มีขอบเขต)

เชื่อมต่อกับสัญญาณคอนเทนเนอร์เชิงพื้นที่

ตรวจสอบ OpenXRSpatialContainerExtension.is_enabled() เพื่อยืนยันว่าส่วนขยาย Spatial Container ได้รับการรองรับและทำงานอยู่ในอุปกรณ์ปัจจุบัน และเชื่อมต่อกับขอบเขตคอนเทนเนอร์และสัญญาณสถานะใน _ready()

OpenXRSpatialContainerExtension จะส่งสัญญาณสถานะต่อไปนี้สำหรับคอนเทนเนอร์เชิงพื้นที่

• spatial_container_visibility_changed: แสดงพร้อมกับ (spatial_container, is_visible) เมื่อคอนเทนเนอร์แสดง (true) หรือซ่อน (false) หยุดการอัปเดตภาพเคลื่อนไหว เสียง หรือการจำลองชั่วคราวเมื่อ is_visible เป็น false
• spatial_container_interactability_changed: แสดงพร้อมกับ (spatial_container, is_interactive) เมื่อคอนเทนเนอร์ได้รับ (true) หรือสูญเสีย (false) โฟกัสอินพุตของผู้ใช้ เปิดหรือปิดใช้การไฮไลต์แบบอินเทอร์แอกทีฟและการจัดการอินพุตเมื่อโฟกัสเปลี่ยนไป
• spatial_container_bounds_mode_changed: แสดงพร้อมกับ (spatial_container, bounds_mode) เมื่อคอนเทนเนอร์สลับระหว่าง OpenXRSpatialContainerState.BOUNDED และ OpenXRSpatialContainerState.IMMERSIVE สลับภาพสภาพแวดล้อม (เช่น สกายบ็อกซ์หรือโหมดส่งผ่าน) และตัวควบคุม UI เฉพาะโหมด

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_bounds_mode_changed.connect(
            _on_bounds_mode_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_visibility_changed.connect(
            _on_visibility_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_interactability_changed.connect(
            _on_interactability_changed
        )

func _on_visibility_changed(_rid: RID, is_visible: bool) -> void:
    # Pause or resume simulation and audio based on visibility
    pass

func _on_interactability_changed(_rid: RID, is_interactive: bool) -> void:
    # Enable or disable input handling and focus highlights
    pass

ปรับขนาดเนื้อหา 3 มิติให้พอดีกับขอบเขตคอนเทนเนอร์

เมื่ออยู่ในโหมด BOUNDED ให้ปรับขนาดเนื้อหา 3 มิติให้เท่ากันตามขนาดที่เล็กที่สุดของ bounds เพื่อให้คงสัดส่วนภาพไว้และพอดีกับด้านที่เล็กที่สุดของคอนเทนเนอร์เสมอ เมื่อเปลี่ยนไปใช้โหมด IMMERSIVE ให้คืนค่าฉากเป็นสเกล 1:1 ดังนี้

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    var uniform_scale: float = min(bounds.x, bounds.y, bounds.z)
    content_root.scale = Vector3.ONE * uniform_scale

func _on_bounds_mode_changed(
    _rid: RID, bounds_mode: OpenXRSpatialContainerState.BoundsMode
) -> void:
    if bounds_mode == OpenXRSpatialContainerState.IMMERSIVE:
        content_root.scale = Vector3.ONE

สลับระหว่างโหมดจำกัดขอบเขตและโหมดใหญ่พิเศษ

เรียกใช้ request_main_spatial_container_bounds_mode ด้วย OpenXRSpatialContainerState.BOUNDED หรือ OpenXRSpatialContainerState.IMMERSIVE เพื่อสลับระหว่างปริมาตร 3 มิติที่มีขอบเขตกับมุมมองสมจริงแบบเต็มหน้าจอ

# Request transitioning to immersive mode (or pass BOUNDED to return)
OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
    OpenXRSpatialContainerState.IMMERSIVE
)

ดูเพิ่มเติม

• สร้างด้วยคอนเทนเนอร์เชิงพื้นที่
• ทำความเข้าใจสิทธิ์สำหรับ XR
• เพิ่มการรองรับ Android XR ลงในโปรเจ็กต์ Godot XR ที่มีอยู่

OpenXR™ และโลโก้ OpenXR เป็นเครื่องหมายการค้าของ The Khronos Group Inc. และจดทะเบียนเป็นเครื่องหมายการค้าในจีน สหภาพยุโรป ญี่ปุ่น และสหราชอาณาจักร