Tài liệu Steamworks
Thuộc tính linh động của vật phẩm kho đồ Steam
Xin giới thiệu tính năng mới toanh trên Dịch vụ kho đồ Steam: lưu trữ tùy ý thuộc tính string (chuỗi), integer (số nguyên), boolean, hoặc float trên bất kỳ bản sao nào của vật phẩm.

Các thuộc tính này tương tự như nhãn theo từng vật phẩm. Tuy vậy, khác với nhãn theo từng vật phẩm bất khả xâm phạm, các thuộc tính này có sự linh động vì ta có thể thay đổi chúng thông qua lệnh gọi API Web bảo mật hoặc qua API Steamworks.

Cũng khác với thẻ vật phẩm, thuộc tính vật phẩm linh động bị xóa khi vật phẩm được trao đổi. Thuộc tính vật phẩm linh động hiện giờ không hiển thị khi kiểm tra vật phẩm trong kho đồ Steam của người dùng hoặc trên chợ cộng đồng Steam.

Truy xuất thuộc tính vật phẩm


Thuộc tính vật phẩm linh động được tự động gửi cùng các thuộc tính khác của vật phẩm đến phần mềm Steam và có thể lấy bằng cách gọi ISteamInventory::GetResultItemProperty với tên thuộc tính dynamic_props. Bộ nhớ đệm được cung cấp sẽ được lấp bằng string đại diện JSON cho tất cả thuộc tính linh động mà vật phẩm có. Chuỗi được phân tích ra sao là tùy thuộc ứng dụng.

Với bất kỳ lệnh gọi API Web nào trả vật phẩm về dưới dạng JSON, key dyamic_props sẽ hướng về đối tượng JSON đầy đủ chứa các thuộc tính vật phẩm linh động.

Chỉnh sửa thuộc tính vật phẩm


Từ một máy chủ an toàn, bạn có thể sửa đổi vật phẩm bằng cách dùng IInventoryService/ModifyItemsAPI Web và key bảo mật của nhà phát hành.

Bạn cũng có thể chỉnh sửa thuộc tính vật phẩm từ phần mềm Steam thông qua API Steamworks và gọi lệnh ISteamInventory::StartUpdateProperties, ISteamInventory::RemoveProperty, ISteamInventory::SetProperty, and ISteamInventory::SubmitUpdateProperties. Tuy nhiên, trước hết bạn cần cho vào danh sách trắng các thuộc tính có thể cài đặt được từ phần mềm tại trang thiết lập Dịch vụ kho đồ Steam ở trang đối tác. Chúng tôi khuyên bạn chỉ thêm vào danh sách trắng các thuộc tính bạn an tâm dùng với cài đặt phần mềm không tin cậy (tức là người dùng có thể giả mạo tin nhắn để đặt giá trị thành bất cứ cái gì họ muốn).

Hiện tại có thể sửa đổi tối đa 100 vật phẩm cho mỗi người dùng trong một lệnh gọi. Lệnh này có giới hạn tốc độ tùy theo mỗi người dùng, nên bạn sẽ cần gộp các chỉnh sửa lại và gửi đi vào thời điểm thích hợp cho trò chơi. Ngoài ra mỗi vật phẩm còn có giới hạn tối đa 1024 byte JSON tại thời điểm này.

Áp dụng các hạn chế

Như đã đề cập phía trên, bạn có thể thêm vào danh sách trắng vài thuộc tính nhất định để có thể cài đặt chúng từ phần mềm. Nhưng bạn cũng có thể hạn chế thêm những thuộc tính nào có thể cài đặt được bằng cách yêu cầu vật phẩm mục tiêu có một cặp tag_category:tag_value cụ thể hoặc cho bất kỳ giá trị tag_category nào. Sử dụng các hạn chế thẻ này kết hợp với API phần mềm, bạn có thể cho phép phần mềm đặt thuộc tính chỉ trên các vật phẩm nếu hợp lý (tức là, một cái nón sẽ không thể dùng để tính số lần giết, nhưng bệ phóng tên lửa thì được). Các thẻ bắt buộc này có thể xuất hiện trên vật phẩm hoặc trên định nghĩa vật phẩm liên quan.

Ví dụ


Giả sử bạn muốn theo dõi số lần một người dùng phóng tên lửa. Có vài cách để làm, nhưng dù chọn cách nào, bạn cũng đều sẽ muốn quản lý việc sửa hàng loạt thuộc tính, vì lệnh gọi điều chỉnh các thuộc tính vật phẩm bị giới hạn tốc độ như đã nêu trên.

API Web

Trên máy chủ trò chơi an toàn, bạn có thể tích lũy các số liệu đó và ĐĂNG kết quả lên API Web IInventoryService/ModifyItems vào cuối màn chơi hoặc lúc thích hợp, bằng cách dùng key bảo mật của nhà phát hành.

Ví dụ về dữ liệu biểu mẫu cho lệnh gọi POST:
appid: 480 key: "0123456789abcdeffedcba9876543210" input_json:{ "steamid" : "1234", "timestamp" : 1513274037, "updates" : [] }

API Steamworks

Nếu bạn muốn dùng API Steamworks để chỉnh sửa thuộc tính vật phẩm (xin nhắc lại là không an toàn đâu), trước tiên bạn cần thêm chúng vào danh sách trắng cho ứng dụng.

Như ví dụ trên, khi ván đấu vừa kết thúc hoặc lúc có thời gian thích hợp, bạn có thể bắt đầu cập nhật, cài đặt thuộc tính, và gửi bản cập nhật về Steam.

SteamInventoryUpdateHandle_t updateHandle = SteamInventory()->StartUpdateProperties(); SteamInventory()->SetProperty( updateHandle, nItemID, "num_times_fired", nNumTimesFired ); SteamInventoryResult_t resultUpdate; SteamInventory()->SubmitUpdateProperties( updateHandle, &resultUpdate );

Sau đó, trong handle gọi lại cho SteamInventoryResultReady_t, bạn sẽ nhận được kết quả của lệnh gọi để cập nhật các thuộc tính vật phẩm đó.

Bản địa hóa

Các thuộc tính linh động thường không hiển thị trong chế độ xem web ở ba lô người dùng. Tuy nhiên, bạn có thể dùng giá trị trong mô tả vật phẩm nếu chỉ định tên thuộc tính linh động làm token thay thế.

Sử dụng ví dụ trên, chuỗi mô tả của bạn trong định nghĩa vật phẩm có thể là như sau:
Bệ phóng tên lửa này đã bắn %num_times_fired% lần.

Mô tả trên trang web sẽ như sau:
Bệ phóng tên lửa này đã bắn 100 lần.

Token thay thế (tức các chuỗi khớp với biểu thức chính quy này "%([a-zA-Z0-9.-_]+)") mà không có thuộc tính linh động tương ứng sẽ tự động bị loại trừ. Nếu bạn đặt cấu hình thuộc tính linh động trên trang Dịch vụ kho đồ Steam dưới mục "Thuộc tính linh động" và đặt trường "type", thì integer (số nguyên) và float sẽ thay vào đó thay thành 0, và thuộc tính bool sẽ đổi thành "false".