squidGame/tgx-games-server/docs/apiPrivate/tsapi.md

# TSRPC API 接口文档

## 通用说明

- 所有请求方法均为 `POST`
- 所有请求均需加入以下 Header :
    - `Content-Type: application/json`

## 目录

- game
    - [CreateRoom](#/game/CreateRoom)
    - [GetAllUserLocations](#/game/GetAllUserLocations)
    - [@en get all room states on this server, will be called by match server periodically](#/game/GetRoomStates)
    - [@en kick user](#/game/KickUser)
- master
    - [GetGameServerList](#/master/GetGameServerList)
    - [GetMatchServerList](#/master/GetMatchServerList)
    - [GetUserLocation](#/master/GetUserLocation)
    - [ReportServerState](#/master/ReportServerState)
    - [UpdateUserLocation](#/master/UpdateUserLocation)
    - [UserLoginPrepare](#/master/UserLoginPrepare)
- match
    - [CancelMatch](#/match/CancelMatch)
    - [CreateRoomOnMinLoadServer](#/match/CreateRoomOnMinLoadServer)
    - [GetRoomListByType](#/match/GetRoomListByType)
    - [GetRoomServerState](#/match/GetRoomServerState)
    - [StartMatch](#/match/StartMatch)
- [CheckServerAlive](#/CheckServerAlive)

---

## game

### CreateRoom <a id="/game/CreateRoom"></a>

**路径**
- POST `/game/CreateRoom`

**请求**
```ts
interface ReqCreateRoom {
    roomId: string,
    displayId: string,
    roomName: string,
    gameType: string,
    password: string
}
```

**响应**
```ts
interface ResCreateRoom {
    roomId: string
}
```

**配置**
```ts
{
  "allowGuest": true
}
```

---

### GetAllUserLocations <a id="/game/GetAllUserLocations"></a>

**路径**
- POST `/game/GetAllUserLocations`

**请求**
```ts
interface ReqGetAllUserLocations {

}
```

**响应**
```ts
interface ResGetAllUserLocations {
    locations: {
        uid: string,
        roomId?: string,
        gameType?: string
    }[]
}
```

---

### @en get all room states on this server, will be called by match server periodically <a id="/game/GetRoomStates"></a>

@zh 获取当前服务器上所有的房间状态，匹配服会按一定间隔调用

**路径**
- POST `/game/GetRoomStates`

**请求**
```ts
interface ReqGetRoomStates {

}
```

**响应**
```ts
interface ResGetRoomStates {
    internalUrl: string,
    publicUrl: string,
    connNum: /*uint*/ number,
    rooms: {
        id: string,
        displayId: string,
        gameType: string,
        name: string,
        userNum: /*uint*/ number,
        maxUserNum: /*uint*/ number,
        playerNum: /*uint*/ number,
        maxPlayerNum: /*uint*/ number,
        /** 为 undefined 代表不在匹配中 */
        startMatchTime?: /*uint*/ number,
        updateTime: /*uint*/ number,
        password?: string
    }[],
    gameTypes: string[],
    disabled?: boolean
}
```

---

### @en kick user <a id="/game/KickUser"></a>

@zh 踢人

**路径**
- POST `/game/KickUser`

**请求**
```ts
interface ReqKickUser {
    uid: string,
    reason: string
}
```

**响应**
```ts
interface ResKickUser {

}
```

---

## master

### GetGameServerList <a id="/master/GetGameServerList"></a>

**路径**
- POST `/master/GetGameServerList`

**请求**
```ts
interface ReqGetGameServerList {

}
```

**响应**
```ts
interface ResGetGameServerList {
    serverList: {
        /**
        * @en server type
        * @zh 服务器类型
        */
        type: number,
        /**
        * @en server ip
        * @zh 服务器 IP
        */
        ip: string,
        /**
        * @en server port
        * @zh 服务器 端口
        */
        port: number,
        interalUrl?: string,
        /**
        * @en server public url, for client connection
        * @zh 服务器对外 URL，用于客户端通信
        */
        publicUrl?: string,
        userNum?: number,
        roomNum?: number,
        lastUpdateTime?: number
    }[]
}
```

---

### GetMatchServerList <a id="/master/GetMatchServerList"></a>

**路径**
- POST `/master/GetMatchServerList`

**请求**
```ts
interface ReqGetMatchServerList {

}
```

**响应**
```ts
interface ResGetMatchServerList {

}
```

---

### GetUserLocation <a id="/master/GetUserLocation"></a>

**路径**
- POST `/master/GetUserLocation`

**请求**
```ts
interface ReqGetUserLocation {
    uid: string
}
```

**响应**
```ts
interface ResGetUserLocation {
    serverUrl?: string,
    roomId?: string,
    gameType?: string
}
```

---

### ReportServerState <a id="/master/ReportServerState"></a>

**路径**
- POST `/master/ReportServerState`

**请求**
```ts
interface ReqReportServerState {
    /**
    * @en server info, for cluster load balance and server list display
    * @zh 服务器信息，用于集群负载均衡，以及服务器列表显示
    */
    state: {
        /**
        * @en server type
        * @zh 服务器类型
        */
        type: number,
        /**
        * @en server ip
        * @zh 服务器 IP
        */
        ip: string,
        /**
        * @en server port
        * @zh 服务器 端口
        */
        port: number,
        interalUrl?: string,
        /**
        * @en server public url, for client connection
        * @zh 服务器对外 URL，用于客户端通信
        */
        publicUrl?: string,
        userNum?: number,
        roomNum?: number,
        lastUpdateTime?: number
    }
}
```

**响应**
```ts
interface ResReportServerState {

}
```

---

### UpdateUserLocation <a id="/master/UpdateUserLocation"></a>

**路径**
- POST `/master/UpdateUserLocation`

**请求**
```ts
interface ReqUpdateUserLocation {
    uid: string,
    serverUrl?: string,
    roomId?: string,
    gameType?: string
}
```

**响应**
```ts
interface ResUpdateUserLocation {

}
```

---

### UserLoginPrepare <a id="/master/UserLoginPrepare"></a>

**路径**
- POST `/master/UserLoginPrepare`

**请求**
```ts
interface ReqUserLoginPrepare {
    uid: string,
    serverUrl: string
}
```

**响应**
```ts
interface ResUserLoginPrepare {

}
```

---

## match

### CancelMatch <a id="/match/CancelMatch"></a>

**路径**
- POST `/match/CancelMatch`

**请求**
```ts
interface ReqCancelMatch {
    uid: string
}
```

**响应**
```ts
interface ResCancelMatch {

}
```

---

### CreateRoomOnMinLoadServer <a id="/match/CreateRoomOnMinLoadServer"></a>

**路径**
- POST `/match/CreateRoomOnMinLoadServer`

**请求**
```ts
interface ReqCreateRoomOnMinLoadServer {
    uid: string,
    roomName: string,
    gameType: string,
    password: string
}
```

**响应**
```ts
interface ResCreateRoomOnMinLoadServer {
    serverUrl: string,
    roomId: string
}
```

---

### GetRoomListByType <a id="/match/GetRoomListByType"></a>

**路径**
- POST `/match/GetRoomListByType`

**请求**
```ts
interface ReqGetRoomListByType {
    gameType: string
}
```

**响应**
```ts
interface ResGetRoomListByType {
    roomList: {
        id: string,
        displayId: string,
        gameType: string,
        name: string,
        userNum: /*uint*/ number,
        maxUserNum: /*uint*/ number,
        playerNum: /*uint*/ number,
        maxPlayerNum: /*uint*/ number,
        /** 为 undefined 代表不在匹配中 */
        startMatchTime?: /*uint*/ number,
        updateTime: /*uint*/ number,
        password?: string
    }[]
}
```

---

### GetRoomServerState <a id="/match/GetRoomServerState"></a>

**路径**
- POST `/match/GetRoomServerState`

**请求**
```ts
interface ReqGetRoomServerState {
    roomId: string
}
```

**响应**
```ts
interface ResGetRoomServerState {
    state: {
        id: string,
        displayId: string,
        gameType: string,
        name: string,
        userNum: /*uint*/ number,
        maxUserNum: /*uint*/ number,
        playerNum: /*uint*/ number,
        maxPlayerNum: /*uint*/ number,
        /** 为 undefined 代表不在匹配中 */
        startMatchTime?: /*uint*/ number,
        updateTime: /*uint*/ number,
        password?: string
    } | undefined,
    serverInternalUrl: string | undefined,
    serverPublicUrl: string | undefined
}
```

---

### StartMatch <a id="/match/StartMatch"></a>

**路径**
- POST `/match/StartMatch`

**请求**
```ts
interface ReqStartMatch {
    uid: string,
    type: string,
    immediate?: boolean
}
```

**响应**
```ts
interface ResStartMatch {
    roomId: string,
    gameType: string,
    token: string,
    time: number,
    serverUrl: string
}
```

---

## CheckServerAlive <a id="/CheckServerAlive"></a>

**路径**
- POST `/CheckServerAlive`

**请求**
```ts
interface ReqCheckServerAlive {

}
```

**响应**
```ts
interface ResCheckServerAlive {

}
```