Mẫu

Các mẫu cho Android Game Development Extension (Tiện ích phát triển trò chơi dành cho Android) minh hoạ cách sử dụng các tính năng chính của tiện ích này. Chủ đề này mô tả các mẫu và chế độ cài đặt cần thiết để chạy các mẫu đó.

Các mẫu sau đây đang có sẵn trên trang tải xuống:

  • HelloJNI: một dự án mang tính giới thiệu.
  • Endless-Tunnel: một dự án chỉ dành cho Android.
  • Teapot: một dự án trên nhiều nền tảng dành cho Windows và Android.
  • AssemblyCode-Link-Objects: một dự án mẫu có mã nguồn tập hợp.

Trước khi bắt đầu

  • Cài đặt Android Game Development Extension và các mẫu. Hãy xem phần bắt đầu nhanh để biết thông tin chi tiết. Chủ đề này cũng mô tả cách tạo và chạy mẫu, đồng thời sử dụng phiên bản Android của mẫu Teapot làm ví dụ.

  • Hướng dẫn về cấu hình dự án mô tả cách định cấu hình chế độ cài đặt cho một dự án sử dụng tiện ích, chẳng hạn như thêm nền tảng Android và tệp APK.

HelloJNI

Mẫu HelloJNI là một dự án đơn giản hiển thị thông báo “Hello From JNI” (”JNI chào bạn”) trong cửa sổ ứng dụng. Dự án này sử dụng một bộ mã nguồn khác cho Windows và Android.

  • Thư mục mã nguồn Android và tập lệnh bản dựng Gradle: HelloJNI\AndroidPackaging
  • Mã nguồn Windows và thư mục dự án Visual Studio: HelloJNI

Khi bạn tạo dự án, Visual Studio sẽ chuyển các tuỳ chọn cài đặt sau đến tệp build.gradle ở cấp ứng dụng. Bạn có thể thay đổi các tuỳ chọn cài đặt này bằng cách sửa đổi các tập lệnh bản dựng Gradle.

  • MSBUILD_NDK_VERSION
  • MSBUILD_MIN_SDK_VERSION
  • MSBUILD_JNI_LIBS_SRC_DIR
  • MSBUILD_ANDROID_OUTPUT_APK_NAME
  • MSBUILD_ANDROID_GRADLE_BUILD_OUTPUT_DIR

Để thiết lập và chạy mẫu, hãy làm như sau:

  1. Trong Vision Studio, hãy mở và tạo bản dựng mẫu HelloJNI.
  2. Thêm nền tảng Android arm64-v8a. Để biết thêm thông tin, hãy xem Thêm một nền tảng Android.
  3. Thêm một mục APK Android vào nền tảng mới.
  4. Biên dịch dự án.
  5. Thêm các nền tảng Android sau đây rồi thêm một mục APK Android vào mỗi nền tảng đó: Android-armeabi-v7a, Android-x86, và Android-x86_64.
  6. Tạo bản dựng và chạy mẫu.

Endless-Tunnel

Mẫu Endless-Tunnel là một trò chơi Android trong đó người chơi thu thập các hình khối màu trắng trong khi cố gắng đến được cuối đường hầm. Mẫu này được chuyển từ một mẫu OpenGL trong kho lưu trữ Android NDK trên GitHub. Mẫu này không cung cấp phiên bản Windows của trò chơi.

Mẫu này đã được định cấu hình các tuỳ chọn cài đặt và nền tảng Android, vì vậy bạn có thể tạo bản dựng và chạy dự án trong Visual Studio mà không cần sửa đổi. Khi bạn mở giải pháp của mẫu này, Solution Explorer (Trình khám phá giải pháp) sẽ cho thấy các mô-đun sau:

  • endless-tunnel: mô-đun ứng dụng hiển thị logic trò chơi.
  • glm: snapshot (bản sao thực tế của trạng thái) của OpenGL Math repo được tạo dưới dạng thư viện tĩnh.
  • native_app_glue: một trình bao bọc NDK giao tiếp với đối tượng NativeActivity.

Teapot

Mẫu Teapot này sẽ cho thấy một ấm trà cổ điển được kết xuất bằng OpenGL ES và chuyển sang Android Game Development Extension để minh hoạ các tính năng sau:

  • Phát triển dự án trên nhiều nền tảng: bạn có thể tạo mẫu Teapot cho Windows và Android.
  • Sử dụng gói Android tuỳ chỉnh: tập lệnh bản dựng Gradle đã được chuyển đến thư mục gốc của mẫu, nơi đặt tệp Teapot.sln.
  • Tích hợp bản dựng Ninja thử nghiệm để cho phép mở dự án trong Android Studio.
  • Các cấu hình Android tuỳ chỉnh minh hoạ cách sử dụng Address Sanitizer (ASan) và Hardware Address Sanitizer (HWAsan).

Quá trình triển khai mẫu Teapot được chia thành nhiều phần. Đây là cách thường dùng cho các ứng dụng và trò chơi lớn trên nhiều nền tảng:

  • Mô-đun GameApplication: xác định các hành động của người dùng và trạng thái ứng dụng, chẳng hạn như người dùng xoay ấm trà hoặc cập nhật số liệu thống kê về ứng dụng.
  • Mô-đun GameEngine: triển khai mô-đun kết xuất cốt lõi.

Để thiết lập và chạy mẫu trên Android, hãy xem phần "bắt đầu nhanh". Để thiết lập mẫu và chạy mẫu đó trên Windows:

  1. Cài đặt GLEW:
    1. Tải GLEW xuống và giải nén.
    2. Sao chép các tệp nhị phân từ $your-glew-directory\bin\Release\x64 vào %SystemRoot%\system32.
  2. Cài đặt freeglut:
    1. Tải freeglut xuống và giải nén.
    2. Sao chép $your-freeglut-directory\bin\x86\freeglut.dll vào %SystemRoot%\system32.
  3. Thêm các phần phụ thuộc dự án freeglut:
    1. Mở Teapot.sln trong Visual Studio.
    2. Trong trình đơn, hãy nhấp vào Debug (Gỡ lỗi) > x64 > Local Windows Debugger (Trình gỡ lỗi cục bộ Windows).
    3. Trong Solution Explorer (Trình khám phá giải pháp), hãy nhấp chuột phải vào GameApplication rồi chọn Properties (Thuộc tính) > C/C++ > General (Chung) > Additional Include Directories (Thư mục bổ sung).
    4. Thêm $your-freeglut-dir\include vào đường dẫn.
      Ảnh chụp màn hình hộp thoại Additional Include Directories (Thư mục bổ sung).
    5. Nhấp vào Ok.
    6. Chọn Linker (Trình liên kết) > General (Chung) > Additional Library Directories (Thư mục thư viện bổ sung).
    7. Thêm $your-freeglut-dir\lib\x64 vào đường dẫn. Ảnh chụp màn hình hộp thoại Additional Library Directories (Thư mục thư viện bổ sung).
    8. Nhấp vào Ok.
    9. Chọn Linker (Trình liên kết) > General (Chung) > Additional Library Directories (Thư mục thư viện bổ sung).
    10. Thêm freeglut.lib vào đường dẫn.
    11. Nhấp vào Ok.
  4. Thêm các phần phụ thuộc dự án GLEW:
    1. Trong ngăn Solution Explorer (Trình khám phá giải pháp), hãy nhấp chuột phải vào GameApplication rồi chọn Properties (Thuộc tính) > C/C++ > General (Chung) > Additional Include Directories (Thư mục bổ sung).
    2. Thêm $your-glew-dir\include vào đường dẫn.
    3. Nhấp vào Ok.
    4. Chọn Linker (Trình liên kết) > General (Chung) > Additional Library Directories (Thư mục thư viện bổ sung).
    5. Thêm $your-glew-dir\lib\Release\x86 vào đường dẫn.
    6. Nhấp vào Ok.
    7. Chọn Linker (Trình liên kết) > General (Chung) > Additional Library Directories (Thư mục thư viện bổ sung).
    8. Thêm glew32.lib vào đường dẫn.
    9. Nhấp vào Ok.
  5. Chạy mẫu trên Windows:
    1. Trên thanh công cụ Visual Studio, hãy nhấp vào nút chạy Local Windows Debugger (Trình gỡ lỗi cục bộ Windows).
    2. Mẫu sẽ có dạng như sau:
      Ảnh chụp màn hình mẫu Teapot chạy trên Windows.

Đây là dự án mẫu minh hoạ cách tạo thư viện gốc Android từ tập hợp và mã nguồn C/C++. Đây là các thành phần chính:

  • AssemblyCode-Link-Objects: thư viện gốc của Android chính, được tạo từ C++ và mã nguồn tập hợp.
  • StaticLib: thư viện tĩnh của trình trợ giúp, thư viện này xuất hàm from_static_lib_assembly_code_as.

Dự án hỗ trợ nhiều cấu trúc. Mỗi cấu trúc được hỗ trợ đều có các tệp nguồn riêng triển khai các hàm được xuất từ StaticLib. Bạn chỉ nên đưa vào các tệp nguồn tập hợp cho những nền tảng mà bạn đang xây dựng. Dự án này đưa các tệp tập hợp vào trong bản dựng bằng cách sử dụng công cụ tạo bản dựng tuỳ chỉnh.

Cách thiết lập và tạo mẫu:

  1. Trong Visual Studio, hãy xác minh rằng bạn đã định cấu hình các công cụ tạo bản dựng tuỳ chỉnh cho các tệp tập hợp:
    1. Trong Solution Explorer (Trình khám phá giải pháp), nhấp chuột phải vào tệp tập hợp rồi nhấp vào Properties (Thuộc tính). Thao tác này sẽ mở ra hộp thoại Properties Pages (Trang thuộc tính) cho tệp.
    2. Chọn cấu hình và nền tảng, chẳng hạn như All configurations (Tất cả cấu hình) cho Android-arm64-v8a.
    3. Đảm bảo rằng General (Chung) > Exclude from Build (Loại trừ khỏi bản dựng) được đặt thành No (Không).
    4. Đảm bảo rằng General (Chung) > Item Type (Loại mục) được đặt thành Custom Build Tool (Công cụ xây dựng tuỳ chỉnh).
    5. Nhấp vào Apply (Áp dụng) nếu có các thay đổi để áp dụng.
    6. Đảm bảo rằng Configuration Properties (Thuộc tính cấu hình) > Custom Build Tools (Công cụ xây dựng tuỳ chỉnh) > Command Line (Dòng lệnh): đã đặt thành $(AsToolExe) -o "$(IntDir)%(FileName).o" %(FullPath). NDK bao gồm một trình tập hợp riêng cho từng cấu trúc CPU và $(AsToolExe) liên kết tới trình kết hợp chính xác. Mẫu này sử dụng chuỗi công cụ NDK để tạo cả hai dự án Android x86 và x86_64. Nếu bạn muốn dùng yasm cho nền tảng Android x86_64, hãy dùng $(YasmToolExe).
    7. Đảm bảo rằng Configuration Properties (Thuộc tính cấu hình) > Custom Build Tools (Công cụ xây dựng tuỳ chỉnh) > Outputs (Đầu ra): đã đặt thành $(IntDir)%(FileName).o. Chuỗi này phải được đưa vào trong tuỳ chọn cài đặt Command Line (Dòng lệnh).
    8. Đảm bảo rằng Configuration Properties (Thuộc tính cấu hình) > Custom Build Tools (Công cụ xây dựng tuỳ chỉnh) > Link Objects (Liên kết đối tượng): được đặt thành Yes.

    Ví dụ: tuỳ chọn cài đặt Android-arm64-v8a sẽ tương tự như ảnh chụp màn hình sau đây:

    Ảnh chụp màn hình của Property Page (Trang thuộc tính) cho Custom Build Tools (Công cụ tạo bản dựng tuỳ chỉnh).
  2. Tạo bản dựng dự án. Thao tác này sẽ tạo tệp libAssmeblyCodeLinkObjects.so:
    1. Mở tệp AssemblyCode-Link-Objects.sln.
    2. Trong trình đơn, hãy nhấp vào Build (Xây dựng) > Build Solution (Giải pháp xây dựng).
  3. Để xác nhận rằng các hàm này được xuất đúng cách sang thư viện Android, hãy dùng công cụ NDK nm.exe:
    1. Trong dòng lệnh, hãy chuyển đến thư mục mẫu.
    2. Truy cập vào vị trí thư viện Android do bản dựng của bạn tạo ra. Vị trí mặc định tương tự với $sample_dir\$solution_configuration\$solution_platform\$platform$sample_dir\Debug\Android-arm64-v8a\arm64-v8a đối với nền tảng arm64-v8a.
    3. Xác minh rằng phần biểu tượng đã xuất có chứa các hàm bằng cách chạy lệnh sau:
        …\ndk\toolschains\llvm\prebuilt\windows-x86_64\aarch64-linux-android\bin\nm.exe --defined-only …\Debug\Android-arm64-v8a\arm64-v8a\libAssmeblyCodeLinkObjects.so
      

      Trong đầu ra, bạn sẽ thấy danh sách các ký hiệu bao gồm:

         T from_shared_object_assembly_code_as
         T from_static_lib_assembly_code_as