tcg-server/ladder-api.md

天梯系统API接口文档

概述

天梯系统API提供与玩家天梯等级、排行榜相关的接口。系统支持基于星星数的等级升降机制和王者分数机制。

接口列表

1. 获取排行榜

接口地址

GET /ladder/leaderboard

请求参数

无

响应数据

[
  {
    "playerId": "string",         // 玩家ID
    "username": "string",         // 玩家用户名
    "avatar": "string",           // 玩家头像
    "rankId": "number",           // 天梯等级ID
    "rankScore": "number",        // 王者分数（如果适用）
    "stars": "number",            // 星星数（如果适用）
    "totalWins": "number",        // 总胜利场次
    "position": "number"          // 排名位置
  }
]

响应示例

[
  {
    "playerId": "5f1a2b3c4d5e6f7g8h9i0j1k",
    "username": "Player1",
    "avatar": "avatar_01",
    "rankId": 5,
    "rankScore": 1250,
    "stars": 0,
    "totalWins": 128,
    "position": 1
  }
]

2. 获取玩家排名位置

接口地址

GET /ladder/position/:playerId

请求参数

参数名	类型	必填	说明
playerId	string	是	玩家ID

响应数据

{
  "position": "number"  // 玩家在排行榜中的位置，未上榜为null
}

响应示例

{
  "position": 5
}

3. 获取玩家天梯信息

接口地址

GET /ladder/rank/:playerId

请求参数

参数名	类型	必填	说明
playerId	string	是	玩家ID

响应数据

对于开启王者分数机制的玩家：

{
  "rankName": "string",    // 天梯阶级名称
  "level": "number",       // 天梯等级
  "score": "number",       // 王者分数
  "isRankScore": "boolean" // 是否为王者分数机制
}

对于普通星星机制的玩家：

{
  "rankName": "string",    // 天梯阶级名称
  "level": "number",       // 天梯等级
  "stars": "number",       // 当前星星数
  "maxStars": "number",    // 最大星星数
  "isRankScore": "boolean" // 是否为王者分数机制
}

响应示例

{
  "rankName": "Gold",
  "level": 5,
  "score": 1250,
  "isRankScore": true
}

4. 获取所有天梯配置

接口地址

GET /ladder/config

请求参数

无

响应数据

[
  {
    "Id": "number",           // 天梯ID
    "Rank": "number",         // 天梯阶级
    "RankName": "string",     // 天梯阶级名称
    "Level": "number",        // 天梯等级
    "BeginStar": "number",    // 升级后初始星星数
    "RankDownStar": "number", // 降级后初始星星数
    "MaxStar": "number",      // 当前等级的星星上限
    "WinGetStar": "number",   // 胜利时增加的星星数
    "ExtraGetStar": "number", // 连胜时额外增加的星星数
    "LoseLostStar": "number", // 是否失败时减少星星（1为是，0为否）
    "LoseRankDown": "number", // 是否失败导致等级下降（1为是，0为否）
    "RankScore": "number",    // 是否开启天梯分数机制（1为开启）
    "AITimes": "number",      // 等待多久后改为对战机器人
    "AIDeck": "string",       // 机器人卡组的RANK配置
    "WaitTime": "number",     // 扩大匹配范围的时间间隔
    "MaxWaitTime": "number"   // 王者等级匹配时，扩大分数范围的间隔
  }
]

响应示例

[
  {
    "Id": 1,
    "Rank": 1,
    "RankName": "Bronze",
    "Level": 1,
    "BeginStar": 0,
    "RankDownStar": 0,
    "MaxStar": 5,
    "WinGetStar": 1,
    "ExtraGetStar": 0,
    "LoseLostStar": 1,
    "LoseRankDown": 0,
    "RankScore": 0,
    "AITimes": 30,
    "AIDeck": "bronze_ai",
    "WaitTime": 10,
    "MaxWaitTime": 20
  }
]

错误响应格式

所有接口在出错时都会返回以下格式的错误信息：

{
  "error": "string"  // 错误描述
}

天梯系统机制说明

星星机制

• 玩家通过胜利获得星星，失败可能失去星星
• 当星星数达到当前等级上限时，玩家升级
• 当星星数为0且再次失败时，可能降级

王者分数机制

• 当玩家达到特定等级后开启王者分数机制
• 不再使用星星和等级升降，天梯等级固定
• 玩家首次进入该等级时，获得1000分的初始天梯分数
• 胜利加分规则：
  • 若对手分数 > 玩家分数：加分 = MIN(对手分数 / 玩家分数, 3) * 20
  • 若玩家分数 >= 对手分数：加20分
  • 若对手未开启天梯分数：加20分
• 失败减分规则：
  • 若失败方已有天梯分数：减20分（最低为0分）
  • 若失败方未开启天梯分数：根据配置决定是否扣除1颗星星

排行榜规则

• 展示天梯等级最高的前100名玩家
• 排名优先级：天梯等级 > 天梯分数 > 当前天梯星星数 > 玩家胜场数
• 每天的00:00、12:00、18:00、22:00四个时间点刷新排行榜