Tổng quan

Steam hỗ trợ bảng xếp hạng cố định với các hạng mục được sắp xếp tự động. Những bảng xếp hạng này có thể dùng để hiển thị xếp hạng phạm vi toàn cầu và bạn bè trong trò chơi và trong trang cộng đồng. Mỗi tựa Steamworks có thể tạo đến 10.000 bảng xếp hạng, và mỗi bảng xếp hạng có thể được gọi ra ngay sau khi điểm số người chơi đã được đưa vào.

Với mỗi bảng xếp hạng, một người chơi chỉ có một mục xếp hạng. Không có giới hạn số người chơi trong mỗi bảng xếp hạng. Mỗi mục chứa một điểm số trên bảng xếp hạng (dạng int32) và có thể có thêm dữ liệu liên quan lên tới 64 int32. Dữ liệu liên quan có thể được dùng để trữ các thông tin đặc thù của trò chơi, như phiên chơi giúp tạo ra mục xếp hạng của người chơi. Dữ liệu này không được xếp hay phân tích bởi Steam, và được thay thế khi một mục xếp hạng mới được tạo cho người dùng.

Tất cả hàm của bảng xếp hạng nằm trong ISteamUserGameStats.h, và hai bảng xếp hạng mẫu đã được triển khai trong ví dụ Steamworks. Bạn cũng có thể xem và quản lý bảng xếp hạng cho trò chơi của mình trong quản trị trò chơi Steamworks.

Trước khi bắt đầu

Tất cả hàm không đồng bộ của bảng xếp hạng trả về một handle tới kết quả gọi API Steam. Bạn có thể tìm thêm thông tin về cách nhận các kết quả này trong mục "Kết quả trả về" (Call Result) của tài liệu Bắt đầu.

Tạo bảng xếp hạng

Mỗi ứng dụng sẽ có bảng xếp hạng riêng và bạn có thể thiết lập trong phần quản trị trò chơi của trang đối tác Steamworks, hoặc qua API.

Tạo qua web

Bạn có thể tạo và quản lý bảng xếp hạng trong mục quản trị ứng dụng Steamworks cho app ID của mình bằng cách vào Thống kê & Thành tựu -> Bảng xếp hạng.


Để xác định bảng xếp hạng, bạn phải điền các trường sau:

• Tên - Đặt một cái tên có nghĩa tới quá trình phát triển nội bộ.
  
• Tên cộng đồng - Nếu bảng xếp hạng xuất hiện trong trung tâm cộng đồng, nhập tên hiển thị công khai tại đây. Nếu để trống tên, bảng xếp hạng sẽ không xuất hiện.
  
• Phương pháp phân loại - Đặt thứ tự cho bảng xếp hạng. Khi xếp hạng theo vị trí, sử dụng thứ tự tăng dần. Khi xếp hạng theo số điểm cao nhất, dùng thứ tự giảm dần.
  
• Kiểu hiển thị - Xác định loại dữ liệu hiển thị trong bảng xếp hạng. Chọn số, giây hoặc mili giây.
  
• Viết - Nếu ở chế độ Trusted, điểm số bảng xếp hạng không thể được đặt bởi client, mà chỉ có thể thông qua WebAPI SetLeaderboardScore. Mặc định là false.
  
• Đọc - Nếu ở chế độ Friends, trò chơi chỉ có thể đọc điểm số bảng xếp hạng của bạn bè người dùng, nhưng WebAPI có thể đọc tất cả điểm số. Mặc định là false.

Tạo qua API

Bảng xếp hạng cho trò chơi của bạn có thể được tạo qua Quản trị ứng dụng Steamworks hoặc qua lập trình bằng cách gọi ISteamUserStats::FindOrCreateLeaderboard. Trong Steam, mọi bảng xếp hạng cho các tựa Steamworks được xác định bằng một tên độc nhất. Tên bảng xếp hạng chỉ được dùng để xác định trong API Steamworks, và không hiển thị cho người dùng qua cộng đồng Steam. Khi tạo bảng xếp hạng, bạn sẽ cần chọn:

• phương pháp phân loại - k_ELeaderboardSortMethodAscending (mục trên cùng là người dùng với điểm thấp nhất) hoặc k_ELeaderboardSortMethodDescending (mục trên cùng là người dùng với điểm cao nhất)
  
• kiểu hiển thị - ELeaderboardDisplayType được dùng để mô tả mục đích của điểm số bảng xếp hạng, và chỉ được dùng bởi cộng đồng để định dạng điểm số bảng xếp hạng khi hiển thị

Nếu bạn chọn chỉ tạo bảng xếp hạng qua Quản trị ứng dụng, bạn có thể dùng ISteamUserStats::FindLeaderboard để lấy handle của bảng xếp hạng. FindLeaderboard và FindOrCreateLeaderboard là các hàm không đồng bộ, và trả về handle cho bảng xếp hạng được chọn qua kết quả trả về từ ISteamUserStats::LeaderboardFindResult_t.

Khi bảng xếp hạng được tạo, bạn có thể thay đổi phương pháp phân loại và kiểu hiển thị cho bảng xếp hạng thông qua Quản trị trò chơi. Khi FindOrCreateLeaderboard được gọi cho một bảng xếp hạng hiện có, tham số của phương pháp phân loại và kiểu hiển thị sẽ được phớt lờ.

Đăng tải điểm số

Để đăng tải điểm số bảng xếp hạng, chỉ cần gọi ISteamUserStats::UploadLeaderboardScore và đưa vào handle của bảng xếp hạng mong muốn (lấy qua FindLeaderboard), điểm số của người dùng và bất kỳ dữ liệu liên quan nào được tạo khi thiết lập điểm số mới (nếu có). Nếu điểm số bảng xếp hạng của người dùng được cập nhật, các dữ liệu liên quan được đưa vào ISteamUserStats::UploadLeaderboardScore sẽ thay thế các dữ liệu được lưu trước đó. Bạn có thể chọn giữa hai phương pháp cập nhật khi tải lên điểm số bảng xếp hạng của người dùng:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest - Steam sẽ so sánh điểm số mới của người dùng với điểm số đã lưu trong bảng xếp hạng, rồi giữ lại điểm số tốt nhất (điểm số thấp nhất nếu bảng xếp hạng được xếp theo thứ tự tăng dần; điểm số cao nhất nếu bảng xếp hạng được xếp theo thứ tự giảm dần).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Steam sẽ luôn thay thế điểm số của người dùng trong bảng xếp hạng với điểm số mới.
  
• ISteamUserStats::UploadLeaderboardScore là một cuộc gọi không đồng bộ, và kết quả của việc tải lên được trả về trong kết quả gọi LeaderboardScoreUploaded_t. Kết quả chứa một mục đánh dấu nếu điểm số của người dùng đã thay đổi, cũng như điểm số cũ và xếp hạng toàn cầu mới. Khi đã tải lên, bảng xếp hạng Steamworks được cập nhật ngay lập tức để phản ánh điểm số mới, và thứ tự mục xếp hạng mới có thể được lấy bằng DownloadLeaderboardEntries.

Đính kèm nội dung do người dùng tạo

Sau khi điểm số được đăng tải, bạn có thể chọn đính kèm nội dung do người dùng tạo cho mục xếp hạng. Để làm thế, chỉ cần gọi ISteamUserStats::AttachLeaderboardUGC. Nội dung có thể là bản phát lại khi người dùng đạt số điểm đó hoặc một bóng ma để so tài. Handle đính kèm sẽ khả dụng khi lấy mục xếp hạng và có thể được tải về bởi người dùng khác. Để tạo và tải về nội dung do người dùng tạo, hãy xem tài liệu về Steam Cloud.

Khi đính kèm, nội dung sẽ khả dụng ngay cả khi file lưu trên đám mây bị thay đổi hay xóa bởi người dùng.

Lấy các mục xếp hạng

ISteamUserStats::DownloadLeaderboardEntries được dùng để lấy các mục xếp hạng thông qua handle bảng xếp hạng lấy từ ISteamUserStats::FindLeaderboard.

Khi bạn đã lấy được mọi mục tải về từ GetDownloadedLeaderboardEntry, nội dung của mục sẽ được làm trống và SteamLeaderboardEntries_t trong LeaderboardScoresDownloaded_t sẽ không còn hợp lệ.

Lấy thông tin bảng xếp hạng

Dùng handle bảng xếp hạng được trả về từ FindLeaderboard, bạn có thể lấy thông tin về bảng xếp hạng qua các API sau:

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType