Xác định chú thích, tham số về độ trung thực và các chế độ cài đặt

Tài liệu này mô tả cách đặt chú thích, tham số về độ trung thực và chế độ cài đặt trong dự án.

Chú thích và tham số về độ trung thực

Chú thích cung cấp thông tin theo bối cảnh về những gì trò chơi đang làm khi một dấu kiểm được ghi lại. Tham số về độ trung thực phản ánh hiệu suất và các chế độ cài đặt đồ hoạ của trò chơi. Bạn xác định các tham số này bằng vùng đệm giao thức (protocol buffer). Vùng đệm giao thức là định dạng trung lập theo ngôn ngữ, có cấu trúc và trao đổi dữ liệu của Google. Để biết thêm thông tin về cách sử dụng vùng đệm giao thức trong trò chơi, hãy xem nội dung Giới thiệu về vùng đệm giao thức.

Bạn có thể xác định các chú thích và tham số về độ trung thực cho trò chơi trong tệp có tên là dev_tuningfork.proto. Tệp này nằm trong thư mục assets/tuningfork của dự án. Sau đây là ví dụ về ứng dụng minh hoạ:

syntax = "proto3";

package com.google.tuningfork;

enum InstrumentKey {
  CPU = 0;
  GPU = 1;
  SWAPPY_WAIT = 2;
  SWAPPY_SWAP = 3;
  CHOREOGRAPHER = 4;
}

enum Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  Level level = 1;
}

message FidelityParams {
  int32 num_spheres = 1;
  float tesselation_percent = 2;
}

Xin lưu ý những điều sau:

  • Gói phải là com.google.tuningfork.
  • Tên thông báo phải chính xác là AnnotationFidelityParams.
  • Bạn chỉ có thể sử dụng enums được xác định trong tệp này như một phần chú thích.
  • Bạn chỉ có thể sử dụng enums, int32s hoặc floats trong các trường FidelityParams.
  • Công cụ xác thực sẽ thực thi các quy ước này.

Các chế độ cài đặt

Tin nhắn Settings được xác định theo tuningfork.proto. Hãy xem ví dụ đầy đủ trong tệp sau:

gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt

Bạn phải xác định các chế độ cài đặt cho trò chơi của mình trong tệp có tên là tuningfork_settings.txt nằm trong thư mục assets/tuningfork của dự án. Bạn chỉ cần chỉ định các trường sau:

  • aggregation_strategy: Một thông báo gồm những nội dung như sau:

    • method: TIME_BASED để tải lên mỗi n mili giây hoặc TICK_BASED để tải lên theo từng n dấu kiểm.
    • intervalms_or_count: n cho trường method.
    • max_instrumentation_keys: Số khoá đo lường cần sử dụng. Hãy đặt thành 4 nếu bạn sử dụng thư viện Android Frame Pacing (Tốc độ khung hình Android).
    • annotation_enum_size: Một trường không bắt buộc do kích thước được tính khi khởi động từ phần mô tả.
  • api_key: Khoá API Dự án trên đám mây của ứng dụng, dùng để xác thực các yêu cầu đến điểm cuối. Để tạo khoá này, hãy xem mục Enable the API. Nếu bạn thấy lỗi kết nối trong logcat, hãy kiểm tra xem khoá API có chính xác hay không.

  • default_fidelity_parameters_filename: Tham số về độ trung thực mà bạn đã đặt được dùng khi khởi chạy (không bắt buộc nếu bạn đặt training_fidelity_params trong mã).

  • level_annotation_index: (Không bắt buộc) Chỉ mục trong các trường chú thích của số cấp.

Sau đây là ví dụ về cách trình bày văn bản:

aggregation_strategy: {method: TIME_BASED, intervalms_or_count: 10000,
  max_instrumentation_keys: 5, annotation_enum_size: [3,4]}
api_key: "API-KEY-FROM-GOOGLE-CLOUD-CONSOLE"
default_fidelity_parameters_filename: "dev_tuningfork_fidelityparams_3.bin"
level_annotation_index: 1

Đặt chú thích

Bạn cần đặt chú thích theo cách thủ công trong quá trình chơi. Bạn có thể thấy ví dụ về điều này trong ứng dụng minh hoạ khi ứng dụng tự động chuyển qua tất cả các màn chơi. Để biết thêm thông tin, hãy xem hàm SetAnnotations() trong insightsdemo.cpp.

Trong trường hợp này, chú thích chỉ chỉ định số của màn chơi.

message Annotation {
  Level level = 1;
}

Xác định mức độ chất lượng

Sử dụng mức chất lượng để chú thích cho các phiên, qua đó bạn có thể xác định liệu thiết bị có đang chạy ở mức chất lượng quá cao (dẫn đến hiệu suất thấp hơn) hay quá thấp (dẫn đến giảm độ trung thực không cần thiết).

Bạn phải xác định ít nhất một và tốt hơn là vài mức độ chất lượng cho trò chơi của mình. Mức độ chất lượng tương ứng với một thực thể của thông báo FidelityParams. Các mức độ này phải được cung cấp theo thứ tự tăng dần về độ trung thực với định dạng tên tệp như sau:

dev_tuningfork_fidelityparams_i.txt

Trong đó i là chỉ mục bắt đầu từ 1 với giá trị tối đa là 15. Các tệp này phải nằm trong thư mục assets/tuningfork của dự án. Dự án mẫu đưa ra một ví dụ về cấu trúc này trong thư mục gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/.

Giới thiệu về vùng đệm giao thức

Thư viện Tuning Fork sử dụng định dạng bộ đệm giao thức của Google cho các chế độ cài đặt, chú thích và tham số về độ trung thực. Đây là một giao thức đa ngôn ngữ được xác định rõ ràng cho dữ liệu có cấu trúc có thể mở rộng. Để biết thêm thông tin, hãy xem tài liệu về Bộ đệm giao thức.

Proto2 so với proto3

Phiên bản của định dạng vùng đệm giao thức được đặt ở dòng đầu tiên của tệp:

syntax="proto2";

Proto2 và proto3 là hai phiên bản vùng đệm giao thức thường dùng. Cả hai đều sử dụng cùng một định dạng wire nhưng tệp định nghĩa không tương thích. Những điểm khác biệt chính giữa hai phiên bản bao gồm:

  • Chúng tôi không còn cho phép từ khoá optionalrequired trong proto3.
  • Mọi thứ đều hiệu quả optional trong proto3.
  • Các extension không được hỗ trợ trong proto3.

Hãy dùng proto3 trong các tệp proto vì các tệp này có thể được biên dịch thành C#. Proto2 cũng hoạt động cùng với bộ tính năng có giới hạn dùng trong thư viện Tuning Fork.

Biểu diễn văn bản so với biểu diễn nhị phân

Định dạng wire protobuf nhị phân được xác định rõ và ổn định trên các phiên bản protobuf khác nhau (mã được tạo không phải). Ngoài ra, còn có một định dạng văn bản mà phiên bản đầy đủ của thư viện protobuf có thể tạo và đọc. Định dạng này không được xác định rõ, nhưng ổn định cho một tập hợp các tính năng có giới hạn trong thư viện Tuning Fork. Bạn có thể chuyển đổi giữa các định dạng nhị phân và văn bản bằng cách sử dụng trình biên dịch protoc. Lệnh sau đây chuyển đổi một protobuf văn bản thành nhị phân:

protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin

Bạn phải đưa tệp nhị phân thay vì tệp văn bản vào trong tệp APK vì thư viện protobuf đầy đủ có kích thước vài MB; việc tạo thư viện Tuning Fork sẽ phụ thuộc vào việc tăng kích thước trò chơi lên một mức tương tự.

Full (đầy đủ) so với Lite (thu gọn) so với Nano (siêu nhỏ)

Cũng như thư viện protobuf đầy đủ, có một phiên bản thu gọn giúp giảm kích thước mã bằng cách xoá một số tính năng như phản chiếu, FileDescriptors và truyền trực tuyến cả hai chiều từ các định dạng văn bản. Phiên bản này vẫn yêu cầu thêm vài MB dung lượng mã bổ sung, vì vậy, thư viện Tuning Fork sẽ sử dụng nội bộ thư việnnanopb. Mã nguồn cho thư viện này có trong Dự án nguồn mở Android trong external/nanopb-c và là một phần của nhánh gamesdk. Sử dụng thư viện này trong trò chơi nếu kích thước mã gặp vấn đề.

Các tệp CMake trong gamesdk/src/protobuf có thể giúp bạn tích hợp cả ba phiên bản của protobuf. Các mẫu sử dụng kết hợp cả nanopb và probuf đầy đủ.