> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 基于事件的排行榜概述
> XBOX Live 基于事件的排行榜如何通过 XBOX 用户群体的全局排名或玩家好友之间的社交排名来比较玩家。
本主题介绍排行榜如何通过显示某个游戏的特定统计数据来比较玩家。
排行榜是一种有趣的方式，可以吸引玩家并激发他们之间的竞争。XBOX 服务提供了适合硬核玩家（针对整个 XBOX 用户群体的 *全局* 排名）和休闲玩家（针对玩家好友的 *社交* 排名）的功能。
你可以使用两种类型的排行榜：全局排行榜和社交排行榜。
它们的概念非常相似，但在配置和目的上存在根本差异。
## 全局排行榜与社交排行榜
### 全局排行榜
* 全局排行榜对整个 XBOX 用户群进行排名，且必须进行配置。
* 全局排行榜是你在服务中的引入时（游戏发布前或发布后的任何时间）配置的预定义视图。
### 社交排行榜
* 社交排行榜是动态生成的，用于对玩家的好友进行排名。
* 社交排行榜仅包含玩家社交图谱中的玩家。
* 社交排行榜不需要在引入时预定义，因为该服务会根据现有的用户统计信息在运行时动态生成排行榜。
## 理解排行榜
排行榜有两个主要组成部分。
* 用于排名的值（在 XBOX 服务中，这始终是玩家的[统计信息实例](/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview#defining-stat-instances)）。
* 排序顺序（值越高或越低越好）。
### 作为排名值的统计信息
排行榜派生自玩家的统计信息。为你需要的内容定义正确的统计规则至关重要。在设计游戏时，请记住你希望玩家参与哪些排行榜的排名。
## 全局排行榜
全局排行榜跟踪整个 XBOX 社区中玩家记录的最佳分数。全局排行榜的主要区别在于，它们在引入时通过指定排行榜标识名称、排名统计信息和排序顺序（升序或降序）来预定义。
游戏可以定义无限数量的全局排行榜，并可以随时通过服务配置添加更多排行榜。每个全局排行榜的最大记录数目前限制为 10,000 个条目。这意味着对于"最佳"分数未排名进入前 10,000 位的玩家，他们的分数不会出现在排行榜中。
一次可以读取多达 100 个排行榜条目（玩家 XUID、玩家代号、全局排名和分数）的"页"，并指定该页的起始排名，或者检索围绕指定玩家代号为中心的排行榜条目。结果始终是"历来所有时间"范围；尚不支持按日、周和月查看。
可以通过 XBOX Services API（XSAPI）或我们的 REST API 使用 `GET (/scids/{scid}/leaderboards/{leaderboardname})` 访问全局排行榜。
以下屏幕截图显示了如何为赛车游戏配置示例排行榜。
## 社交排行榜
社交排行榜是激励休闲玩家与好友进行比较和排名的绝佳方式。即使他们不在社区的最高排名中，他们仍然可以有动力去击败他们认识的玩家。社交排行榜是根据任何现有的用户统计信息动态创建的。因此，它们不需要在引入时预定义，并且仅包含某个特定玩家的社交图谱中的玩家。
社交排行榜的主要优势在于它们不是预定义的。你可以为游戏的任何统计信息创建社交排行榜。调用方在请求社交排行榜时可以指定两项内容：统计信息实例和排序顺序（默认为按评分降序）。结果始终限定为"历来所有时间"；不支持按日、周、月查看。
与全局排行榜一样，调用方可以一次读取多达 100 个排行榜条目（玩家 XUID、玩家代号、全局排名和分数）的"页"，并指定该页的起始排名。
可以通过 XSAPI 或我们的 REST API 使用 `GET (/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite})` 访问社交排行榜。
## 带社交视图的全局排行榜
因为社交排行榜是动态创建的，所以检索社交排行榜比检索全局排行榜要花费更长的时间。对于你的游戏基于一组常见条件频繁检索社交排行榜的场景，你可以创建全局排行榜，并且只检索排行榜中与玩家社交图谱相关的条目。
这比社交排行榜检索时间更快，因为该排行榜已存在于 XBOX 服务服务器上。这也会导致较小的有效负载，因为结果限定为用户的社交图谱。这种类型的排行榜是全局排行榜。因此，必须在游戏的服务配置中定义。
带社交视图的全局排行榜可以使用正常的全局排行榜请求 `GET (/scids/{scid}/leaderboards/{leaderboardname})` 访问，并将以下查询附加到 URL：`&viewTarget=people&view=people`。
为了支持多列排行榜视图，可以使用统计信息元数据。游戏可以为排行榜统计信息定义元数据字段，这些字段可以在查询排行榜排名时返回。游戏不应使用批量用户统计信息 URI 来实现相同的行为，因为隐私设置可能会阻止访问统计信息。
## 多列排行榜
在某些情况下，你需要在排行榜中添加更多列以为统计信息提供更多信息。例如，对于击败最多敌人的排行榜，你可能希望添加玩家使用的武器、发生地点的地图、击败最多的敌人类型以及击杀/死亡比。
XBOX 排行榜内置了多列支持。你可以轻松获取这些类型的排名。唯一的先决条件是排行榜使用的统计信息定义了统计上下文，这将作为附加元数据使用。例如，对于 FastestLap 统计信息，你可能希望将这些附加属性配置为统计上下文。以下是它们可能的样子的屏幕截图。
现在该统计信息将带上下文持久化，如果检索多列排行榜，它看起来类似于以下表格。
| 运算符 | 值 (FastestLap) | CarModel | WeatherCondition | TrackId |
| ------- | -------------- | -------- | ---------------- | ------- |
| SUM | 常量或字段 | Model A | Rainy | 9 |
| MIN | 字段 | Model A | Sunny | 9 |
| MAX | 字段 | Model B | Sunny | 2 |
| REPLACE | 常量或字段 | Model C | Cloudy | 1 |
多列排行榜目前在全局排行榜和带社交视图的全局排行榜中受支持。但是，如果你想创建多列 *社交* 排行榜，可以使用批量用户统计信息调用来获取所有带上下文的统计信息，然后手动创建排行榜。
多列排行榜只能通过 REST API 使用正常的全局排行榜请求 `GET (/scids/{scid}/leaderboards/{leaderboardname})` 访问，并将以下查询附加到 URL：`&include=valuemetadata`。
## 带精选统计信息的排行榜显示位置
排行榜通过显示某个游戏的所选统计信息来比较玩家。
排行榜是激励玩家之间竞争的绝佳方式。排行榜让玩家保持参与，努力超越他们以前的最佳分数和好友的分数。
* 精选统计信息的排行榜始终显示在游戏的官方俱乐部中。
* 精选统计信息的排行榜有时显示在其他 XBOX 体验中，例如玩家个人资料中的成就视图。
* 你还可以使用已配置的精选统计信息在游戏内创建排行榜。
## 选择合适的排行榜
排行榜对应于你定义的统计信息。
你应该选择对应于玩家可以努力改进的成就的排行榜。
例如，赛车游戏中的"最佳单圈时间"是一个不错的排行榜，因为玩家希望努力改进他们的最佳单圈时间。
其他示例是射击游戏中的击杀/死亡比或格斗游戏中的最大连击数。
## 何时显示排行榜
你可以随时在游戏中显示排行榜。
你应该选择排行榜不会干扰游戏玩法或游戏流程的时间。
例如，回合之间和比赛之后是显示排行榜的好时机。
## 编程指南
有多个可用于获取排行榜当前状态的 Leaderboard API。
所有 API 都是异步的且不阻塞。
发出请求以获取排行榜数据，并继续你的常规游戏处理。
从服务返回排行榜结果后，你可以在适当的时候显示结果。
在你要显示排行榜之前稍微提前从服务请求排行榜数据。这可以防止玩家在等待排行榜显示时被阻塞。
## 另请参阅
[基于事件的与游戏管理的统计信息](/services/xbox-services/player-data/stats-leaderboards/live-stats-eb-vs-tm#update-frequency)。
## Related topics
- [基于事件的统计信息和排行榜](/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/live-statslb-eb-nav.md)
- [基于事件的排行榜示例代码](/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-leaderboards-eb-howto.md)
- [基于事件的排行榜的门户配置](/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/config/live-eb-leaderboards-portal.md)
- [基于事件的统计信息和排行榜门户配置](/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/config/live-statslb-eb-config-nav.md)
- [基于事件的统计信息与排行榜示例代码](/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/how-to/live-statslb-eb-howto-nav.md)