211 lines
4.9 KiB
Markdown
211 lines
4.9 KiB
Markdown
# 天梯系统API接口文档
|
||
|
||
## 概述
|
||
|
||
天梯系统API提供与玩家天梯等级、排行榜相关的接口。系统支持基于星星数的等级升降机制和王者分数机制。
|
||
|
||
## 接口列表
|
||
|
||
### 1. 获取排行榜
|
||
|
||
#### 接口地址
|
||
```
|
||
GET /ladder/leaderboard
|
||
```
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 响应数据
|
||
```json
|
||
[
|
||
{
|
||
"playerId": "string", // 玩家ID
|
||
"username": "string", // 玩家用户名
|
||
"avatar": "string", // 玩家头像
|
||
"rankId": "number", // 天梯等级ID
|
||
"rankScore": "number", // 王者分数（如果适用）
|
||
"stars": "number", // 星星数（如果适用）
|
||
"totalWins": "number", // 总胜利场次
|
||
"position": "number" // 排名位置
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
[
|
||
{
|
||
"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 |
|
||
|
||
#### 响应数据
|
||
```json
|
||
{
|
||
"position": "number" // 玩家在排行榜中的位置，未上榜为null
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"position": 5
|
||
}
|
||
```
|
||
|
||
### 3. 获取玩家天梯信息
|
||
|
||
#### 接口地址
|
||
```
|
||
GET /ladder/rank/:playerId
|
||
```
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --------- | ------ | ---- | ------ |
|
||
| playerId | string | 是 | 玩家ID |
|
||
|
||
#### 响应数据
|
||
对于开启王者分数机制的玩家：
|
||
```json
|
||
{
|
||
"rankName": "string", // 天梯阶级名称
|
||
"level": "number", // 天梯等级
|
||
"score": "number", // 王者分数
|
||
"isRankScore": "boolean" // 是否为王者分数机制
|
||
}
|
||
```
|
||
|
||
对于普通星星机制的玩家：
|
||
```json
|
||
{
|
||
"rankName": "string", // 天梯阶级名称
|
||
"level": "number", // 天梯等级
|
||
"stars": "number", // 当前星星数
|
||
"maxStars": "number", // 最大星星数
|
||
"isRankScore": "boolean" // 是否为王者分数机制
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
{
|
||
"rankName": "Gold",
|
||
"level": 5,
|
||
"score": 1250,
|
||
"isRankScore": true
|
||
}
|
||
```
|
||
|
||
### 4. 获取所有天梯配置
|
||
|
||
#### 接口地址
|
||
```
|
||
GET /ladder/config
|
||
```
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 响应数据
|
||
```json
|
||
[
|
||
{
|
||
"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" // 王者等级匹配时，扩大分数范围的间隔
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 响应示例
|
||
```json
|
||
[
|
||
{
|
||
"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
|
||
}
|
||
]
|
||
```
|
||
|
||
## 错误响应格式
|
||
|
||
所有接口在出错时都会返回以下格式的错误信息：
|
||
|
||
```json
|
||
{
|
||
"error": "string" // 错误描述
|
||
}
|
||
```
|
||
|
||
## 天梯系统机制说明
|
||
|
||
### 星星机制
|
||
- 玩家通过胜利获得星星，失败可能失去星星
|
||
- 当星星数达到当前等级上限时，玩家升级
|
||
- 当星星数为0且再次失败时，可能降级
|
||
|
||
### 王者分数机制
|
||
- 当玩家达到特定等级后开启王者分数机制
|
||
- 不再使用星星和等级升降，天梯等级固定
|
||
- 玩家首次进入该等级时，获得1000分的初始天梯分数
|
||
- 胜利加分规则：
|
||
- 若对手分数 > 玩家分数：加分 = MIN(对手分数 / 玩家分数, 3) * 20
|
||
- 若玩家分数 >= 对手分数：加20分
|
||
- 若对手未开启天梯分数：加20分
|
||
- 失败减分规则：
|
||
- 若失败方已有天梯分数：减20分（最低为0分）
|
||
- 若失败方未开启天梯分数：根据配置决定是否扣除1颗星星
|
||
|
||
### 排行榜规则
|
||
- 展示天梯等级最高的前100名玩家
|
||
- 排名优先级：天梯等级 > 天梯分数 > 当前天梯星星数 > 玩家胜场数
|
||
- 每天的00:00、12:00、18:00、22:00四个时间点刷新排行榜 |