Sử dụng vùng chứa không gian trong Godot

Các thiết bị XR được hỗ trợ

Hướng dẫn này giúp bạn xây dựng các trải nghiệm cho những loại thiết bị XR sau.

Tìm hiểu về các loại thiết bị XR →

Tìm hiểu về các loại thiết bị XR →

Vùng chứa không gian cho phép ứng dụng của bạn hiển thị nội dung OpenXR 3D bên trong một hộp giới hạn thể tích 3D do hệ thống quản lý ở Chế độ toàn bộ không gian hoặc chuyển đổi trong thời gian chạy thành trải nghiệm toàn màn hình không giới hạn.

Hãy làm theo hướng dẫn này để định cấu hình và sử dụng Spatial Containers trong dự án của bạn.

Cách hoạt động của vùng chứa không gian

Khi bạn bật Vùng chứa không gian trong phần cài đặt dự án:

• Toàn bộ cảnh 3D đang hoạt động của bạn được đặt bên trong một vùng chứa không gian chính duy nhất, nằm ở giữa gốc cảnh (0, 0, 0). Bạn không cần gắn thẻ hoặc chỉ định từng nút Node3D để đặt chúng vào trong vùng chứa.
• Ứng dụng của bạn sẽ chạy ở Chế độ toàn bộ không gian được quản lý bằng Chế độ ranh giới (Bounded hoặc Immersive) và kích thước Ranh giới ban đầu được định cấu hình trong phần cài đặt dự án. Ở chế độ giới hạn, hệ thống sẽ tự động cắt bớt mọi hình học 3D trong cảnh của bạn vượt ra ngoài kích thước của hộp giới hạn.
• Theo mặc định, hệ thống Android XR cung cấp các chế độ điều khiển cửa sổ để người dùng có thể lấy, di chuyển và đặt lại vị trí vùng chứa có giới hạn trong không gian 3D hoặc thu nhỏ và đóng vùng chứa đó. Trong thời gian chạy, ứng dụng của bạn có thể đổi kích thước vùng chứa, chuyển đổi giữa chế độ giới hạn (OpenXRSpatialContainerState.BOUNDED) và chế độ hiển thị tối đa toàn màn hình (OpenXRSpatialContainerState.IMMERSIVE), đồng thời phản ứng với các thay đổi về ranh giới và trạng thái bằng cách sử dụng singleton OpenXRSpatialContainerExtension.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo môi trường phát triển và thiết bị mục tiêu của bạn đáp ứng các yêu cầu sau:

• Phiên bản Godot: Godot 4.8-dev trở lên.
• Thiết lập dự án: Hoàn tất tất cả các bước trong hướng dẫn Thiết lập dự án Godot Engine.
• Trình bổ trợ nhà cung cấp Godot OpenXR: Cài đặt phiên bản 5.2 trở lên của Trình bổ trợ nhà cung cấp Godot OpenXR, cho phép hỗ trợ các tiện ích dành riêng cho Android XR.
• Thiết bị mục tiêu: Thiết bị Android XR hỗ trợ cấp độ API không gian 4 trở lên. Trong thời gian chạy, hãy gọi OpenXRSpatialContainerExtension.is_enabled() để xác minh xem tiện ích có hoạt động trên thiết bị hay không.

Bật vùng chứa không gian trong phần cài đặt dự án

Định cấu hình chế độ cài đặt dự án để bật OpenXR, Vùng chứa không gian, quyền khi bắt đầu chạy tự động và tính năng truyền qua kết hợp alpha:

1. Mở Project > Project Settings (Dự án > Cài đặt dự án).
2. Bật nút Advanced Settings (Cài đặt nâng cao) ở góc trên cùng bên phải của cửa sổ Project Settings (Cài đặt dự án).
3. Chuyển đến General > XR > Shaders (Chung > XR > Chương trình đổ bóng) rồi chọn Enabled (Đã bật).
4. Chuyển đến General > XR > OpenXR (Chung > XR > OpenXR) rồi định cấu hình các chế độ cài đặt sau:
   • Chọn Enabled (Đã bật) để bật OpenXR cho dự án.
   • Đặt Environment Blend Mode (Chế độ hoà trộn môi trường) thành Alpha Blend (Hoà trộn alpha).
5. Cũng trong phần OpenXR, hãy chuyển đến mục Extensions (Tiện ích) và định cấu hình các chế độ cài đặt sau:
   • Chọn Automatically Request Runtime Permissions (Tự động yêu cầu quyền khi bắt đầu chạy) để ứng dụng của bạn tự động nhắc người dùng khi khởi động về mọi quyền XR được khai báo trong tệp kê khai Android.
   • Trong tiểu mục Vùng chứa không gian, hãy chọn Đã bật.
   • Đặt Bounds Mode (Chế độ ranh giới) thành Bounded (Có ranh giới) để chạy trong hộp giới hạn 3D hoặc Immersive (Chế độ hiển thị tối đa) để chạy ở chế độ hiển thị tối đa toàn màn hình.
   • Đặt Bounds (Ranh giới) thành kích thước chiều rộng, chiều cao và chiều sâu ban đầu tính bằng mét, chẳng hạn như Vector3(1.0, 1.0, 1.0).
6. Chuyển đến General > Rendering > Viewport (Chung > Hiển thị > Khung nhìn) rồi chọn Transparent Background (Nền trong suốt).

Định cấu hình chế độ xuất, quyền và Chế độ toàn bộ không gian cho Android

Tiếp theo, hãy định cấu hình chế độ cài đặt sẵn, quyền và chế độ bắt đầu hoạt động cho tính năng xuất Android để ứng dụng của bạn chạy ở Chế độ toàn bộ không gian khi bật Vùng chứa không gian.

Định cấu hình giá trị đặt trước để xuất sang Android

1. Chuyển đến Project > Export... (Dự án > Xuất...) rồi chọn giá trị đặt trước cho việc xuất Android.

2. Trong phần Gradle Build (Bản dựng Gradle), hãy chọn Use Gradle Build (Sử dụng bản dựng Gradle) rồi đặt Min SDK (SDK tối thiểu) thành 34 trở lên.

   

3. Trong phần XR Features (Tính năng XR), hãy đặt XR Mode (Chế độ XR) thành OpenXR rồi chọn Enable AndroidXR Plugin (Bật trình bổ trợ AndroidXR).

   

4. Trong phần Tính năng Android XR, hãy chọn Sử dụng tính năng thử nghiệm.

Thêm quyền hiểu biết về cảnh để khoá sàn

Việc tạo và kết xuất vùng chứa không gian cơ bản không yêu cầu quyền khi bắt đầu chạy nguy hiểm (và android.permission.HEAD_TRACKING được tự động thêm vào tệp kê khai khi bạn bật Sử dụng tính năng thử nghiệm). Tuy nhiên, nếu ứng dụng của bạn sử dụng các tính năng hiểu cảnh, chẳng hạn như khoá và neo vùng chứa không gian vào sàn thực tế, thì ứng dụng phải khai báo và yêu cầu quyền android.permission.SCENE_UNDERSTANDING_COARSE trong thời gian chạy.

Hãy xem bài viết Tìm hiểu về các quyền cho XR để biết thông tin chi tiết về các quyền của Android XR. Nếu ứng dụng của bạn sử dụng tính năng khoá sàn hoặc hiểu cảnh, hãy khai báo và yêu cầu android.permission.SCENE_UNDERSTANDING_COARSE:

1. Trong Project > Export... (Dự án > Xuất...) > Android, hãy chuyển đến Permissions > Custom Permissions (Quyền > Quyền tuỳ chỉnh) rồi thêm android.permission.SCENE_UNDERSTANDING_COARSE.

2. Khi bạn chọn Automatically Request Runtime Permissions (Tự động yêu cầu quyền khi bắt đầu chạy) trong phần Project Settings > General > XR > OpenXR > Extensions (Cài đặt dự án > Chung > XR > OpenXR > Tiện ích), ứng dụng của bạn sẽ tự động yêu cầu quyền khi OpenXR khởi động. Nếu bạn cần yêu cầu cấp quyền theo cách thủ công trong GDScript, hãy gọi OS.request_permission():

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

Định cấu hình chế độ Toàn bộ không gian

Vùng chứa không gian trên Android XR chỉ hỗ trợ Chế độ toàn bộ không gian (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Hãy đảm bảo hoạt động Android của bạn khai báo XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED trong mẫu bản dựng tuỳ chỉnh (android/build/AndroidManifest.xml, được cài đặt bằng cách sử dụng Project > Install Android Build Template... (Dự án > Cài đặt mẫu bản dựng 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>

Làm việc với vùng chứa không gian trong GDScript

Lớp singleton OpenXRSpatialContainerExtension và lớp OpenXRSpatialContainerState hiển thị các tiện ích XR_EXT_spatial_container và XR_EXT_spatial_container_self_rendering cho GDScript. Trong thời gian chạy, hãy sử dụng OpenXRSpatialContainerExtension để kiểm tra trạng thái và giới hạn của vùng chứa không gian chính, theo dõi tín hiệu của vùng chứa và yêu cầu chuyển đổi giữa chế độ BOUNDED (hộp giới hạn 3D) và chế độ IMMERSIVE (chế độ xem toàn màn hình không giới hạn).

Kết nối với tín hiệu của vùng chứa không gian

Kiểm tra OpenXRSpatialContainerExtension.is_enabled() để xác minh rằng tiện ích Spatial Container được hỗ trợ và đang hoạt động trên thiết bị hiện tại, đồng thời kết nối với các tín hiệu trạng thái và ranh giới vùng chứa trong _ready().

OpenXRSpatialContainerExtension phát ra các tín hiệu trạng thái sau đây cho vùng chứa không gian:

• spatial_container_visibility_changed: Được phát ra cùng với (spatial_container, is_visible) khi vùng chứa xuất hiện (true) hoặc bị ẩn (false). Tạm dừng ảnh động, âm thanh hoặc nội dung cập nhật mô phỏng khi is_visible là false.
• spatial_container_interactability_changed: Được phát ra cùng với (spatial_container, is_interactive) khi vùng chứa nhận được (true) hoặc mất (false) tiêu điểm đầu vào của người dùng. Bật hoặc tắt tính năng đánh dấu tương tác và xử lý hoạt động đầu vào khi tiêu điểm thay đổi.
• spatial_container_bounds_mode_changed: Được phát ra cùng với (spatial_container, bounds_mode) khi vùng chứa chuyển đổi giữa OpenXRSpatialContainerState.BOUNDED và OpenXRSpatialContainerState.IMMERSIVE. Bật/tắt hình ảnh môi trường (chẳng hạn như hộp bầu trời hoặc chế độ nhìn xuyên qua) và các thành phần điều khiển trên giao diện người dùng theo chế độ cụ thể.

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

Điều chỉnh tỷ lệ nội dung 3D theo ranh giới vùng chứa

Khi ở chế độ BOUNDED, hãy điều chỉnh tỷ lệ nội dung 3D một cách đồng nhất theo kích thước nhỏ nhất của bounds để nội dung đó giữ nguyên tỷ lệ khung hình và luôn vừa với cạnh nhỏ nhất của vùng chứa. Khi chuyển sang chế độ IMMERSIVE, hãy khôi phục cảnh về tỷ lệ 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

Chuyển đổi giữa chế độ giới hạn và chế độ hiển thị tối đa

Gọi request_main_spatial_container_bounds_mode bằng OpenXRSpatialContainerState.BOUNDED hoặc OpenXRSpatialContainerState.IMMERSIVE để chuyển đổi giữa chế độ xem 3D có giới hạn và chế độ xem toàn màn hình:

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

Xem thêm

• Xây dựng bằng vùng chứa không gian
• Tìm hiểu về các quyền đối với XR
• Thêm tính năng hỗ trợ Android XR vào một dự án Godot XR hiện có

OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của Khronos Group Inc. và được đăng ký làm nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.