You've already forked CC-Framework.BriskGameServer
275 lines
6.9 KiB
Markdown
275 lines
6.9 KiB
Markdown
# Brisk Unity SDK接入文档
|
||
|
||
## 1. 这份文档适合做什么
|
||
|
||
这份文档用于说明当前 Brisk Unity SDK 的接入结构与推荐调用方式。
|
||
|
||
当前 SDK 已采用静态总入口：
|
||
|
||
- `Brisk.InitializeAsync(...)`
|
||
- `Brisk.Auth.xxx`
|
||
- `Brisk.Player.xxx`
|
||
- `Brisk.Config.xxx`
|
||
- `Brisk.Announcements.xxx`
|
||
- `Brisk.Leaderboard.xxx`
|
||
- `Brisk.Archive.xxx`
|
||
- `Brisk.Space.xxx`
|
||
|
||
## 2. 初始化模型
|
||
|
||
Unity 客户端初始化建议持有：
|
||
|
||
- `baseUrl`
|
||
- `gameKey`（必填）
|
||
- `clientVersion`（推荐传入；服务端接口当前可选，但会影响版本命中）
|
||
- `deviceId`（推荐传入；`bootstrap` 接口当前可选）
|
||
|
||
不再需要项目级 `channel / platform`。
|
||
|
||
示例：
|
||
|
||
```csharp
|
||
var options = new BriskOptions {
|
||
BaseUrl = "https://brisk.lightyears.ltd",
|
||
GameKey = "demo-game",
|
||
ClientVersion = Application.version,
|
||
DeviceId = SystemInfo.deviceUniqueIdentifier
|
||
};
|
||
```
|
||
|
||
## 3. 登录模型
|
||
|
||
登录属于独立模块，不属于初始化参数。
|
||
|
||
Unity 登录接口建议统一成：
|
||
|
||
```csharp
|
||
Task<LoginResult> LoginAsync(
|
||
string loginProvider,
|
||
string loginUserId = null,
|
||
string code = null,
|
||
string nickname = null,
|
||
string avatarUrl = null,
|
||
Dictionary<string, object> profileJson = null
|
||
)
|
||
```
|
||
|
||
说明：
|
||
|
||
- `loginProvider`：如 `tap`
|
||
- `loginUserId`：平台返回的稳定唯一用户 ID
|
||
- `code`：如果平台走 code 兑换模式则传这个
|
||
- `loginUserId` 和 `code` 二选一
|
||
- `nickname / avatarUrl / profileJson` 为可选同步资料
|
||
|
||
## 4. 推荐接入顺序
|
||
|
||
1. `BootstrapAsync()`
|
||
2. 从第三方 SDK 获取：
|
||
- `loginProvider`
|
||
- `loginUserId` 或 `code`
|
||
- 可选昵称、头像、扩展资料
|
||
3. `LoginAsync(...)`
|
||
4. 保存 `accessToken`
|
||
5. 拉取：
|
||
- `GetMeAsync()`
|
||
- `GetCurrentConfigAsync()`
|
||
- `ListAnnouncementsAsync()`
|
||
6. 进入业务模块
|
||
|
||
## 5. 身份模型建议
|
||
|
||
Unity SDK 内建议同时保存两套身份：
|
||
|
||
- 外部身份：
|
||
- `LoginProvider`
|
||
- `LoginUserId`
|
||
- 内部身份：
|
||
- `PlayerId`
|
||
- `ProjectAccountId`
|
||
|
||
原因：
|
||
|
||
- 跨系统跳转、和第三方 SDK 共存时，外部身份更方便
|
||
- 游戏内高频接口仍以内部 `player_id` 为主更自然
|
||
|
||
## 6. 空间跳转建议
|
||
|
||
如果排行榜头像点击来自第三方平台，推荐直接支持：
|
||
|
||
```csharp
|
||
Task<SpaceInfo> GetSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)
|
||
Task<SpaceStats> GetSpaceStatsByLoginIdentityAsync(string loginProvider, string loginUserId)
|
||
Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)
|
||
```
|
||
|
||
这样可以避免 Unity 侧先做一次平台 ID 到 Brisk `player_id` 的映射查询。
|
||
|
||
## 7. 排行榜模块建议
|
||
|
||
客户端侧建议封装：
|
||
|
||
- `GetRankTopAsync(rankKey, limit)`
|
||
- `GetRankMeAsync(rankKey)`
|
||
- `GetRankAroundMeAsync(rankKey, range)`
|
||
- `SubmitScoreAsync(rankKey, score)`
|
||
- `GetCurrentSeasonAsync(rankKey)`
|
||
- `GetSeasonHistoryAsync(rankKey, limit)`
|
||
- `GetSeasonHistoryDetailAsync(rankKey, seasonId, limit)`
|
||
|
||
榜单项需要暴露：
|
||
|
||
- `Rank`
|
||
- `PlayerId`
|
||
- `ProjectAccountId`
|
||
- `LoginProvider`
|
||
- `LoginUserId`
|
||
- `Score`
|
||
- `Nickname`
|
||
- `AvatarUrl`
|
||
|
||
## 8. 云存档模块建议
|
||
|
||
云存档适合承载真实游戏数据。
|
||
|
||
原因：
|
||
|
||
- 上传下载是二进制流
|
||
- 天然适配 bytes
|
||
- 可直接存：
|
||
- JSON bytes
|
||
- protobuf bytes
|
||
- msgpack bytes
|
||
- 压缩后的存档二进制
|
||
|
||
当前 SDK 已提供：
|
||
|
||
- `GetArchiveSlotsAsync()`
|
||
- `GetArchiveMetaAsync(slotNo)`
|
||
- `UploadAsync(slotNo, byte[], baseVersion, checksum)`
|
||
- `UploadTextAsync(slotNo, text, baseVersion, checksum)`
|
||
- `UploadJsonAsync(slotNo, payload, baseVersion, checksum)`
|
||
- `DownloadArchiveAsync(slotNo)`
|
||
- `DownloadTextAsync(slotNo)`
|
||
- `DownloadJsonAsync(slotNo)`
|
||
|
||
推荐上层使用策略：
|
||
|
||
- 文本存档：优先直接用 `UploadTextAsync / DownloadTextAsync`
|
||
- JSON 存档：优先直接用 `UploadJsonAsync / DownloadJsonAsync`
|
||
- 二进制存档：继续用 `UploadAsync / DownloadAsync`
|
||
|
||
其中：
|
||
|
||
- SDK 会自动计算上传用 `checksum`
|
||
- 手动传 `checksum` 时也可以带 `sha256:` 前缀，SDK 会自动归一化
|
||
|
||
## 9. 玩家空间模块建议
|
||
|
||
玩家空间适合承载公开展示数据或空间自定义内容，不再限制为 JSON。
|
||
|
||
推荐放：
|
||
|
||
- 简介文本
|
||
- 头像展示字段
|
||
- 成就展示摘要
|
||
- 公开资料卡
|
||
- 小型二进制空间内容
|
||
- 文本、JSON、protobuf、msgpack 等自定义格式
|
||
|
||
当前 SDK / 接口核心是：
|
||
|
||
- `UploadMySpaceContentAsync(baseVersion, contentType, checksum, byte[])`
|
||
- `DownloadSpaceContentByPlayerIdAsync(playerId)`
|
||
- `DownloadSpaceContentByLoginIdentityAsync(loginProvider, loginUserId)`
|
||
- `GetSpaceByPlayerIdAsync(playerId)`
|
||
- `GetSpaceByLoginIdentityAsync(loginProvider, loginUserId)`
|
||
- `LikeSpaceAsync(playerId)`
|
||
- `LikeSpaceByLoginIdentityAsync(loginProvider, loginUserId)`
|
||
- `GetMyVisitsAsync(limit)`
|
||
|
||
当前 SDK 额外提供了一个极简便捷入口：
|
||
|
||
- `Brisk.Space.UpdateMyAsync(payload, baseVersion, contentType, checksum)`
|
||
|
||
它的行为是：
|
||
|
||
- `payload` 为 `string` 时，自动按 `text/plain` 上传
|
||
- `payload` 为 `byte[]` 时，自动按 `application/octet-stream` 上传
|
||
- `payload` 为其他对象时，自动序列化为 JSON 并按 `application/json` 上传
|
||
|
||
建议 SDK 暴露两层模型：
|
||
|
||
- 空间主信息：
|
||
- `ContentExists`
|
||
- `ContentVersion`
|
||
- `ContentType`
|
||
- `ContentSizeBytes`
|
||
- `ContentChecksum`
|
||
- `LikeCount`
|
||
- `VisitCount`
|
||
- 空间内容本体：
|
||
- 原始 `byte[]`
|
||
- 下载响应头中的 `X-Space-Version`
|
||
- 下载响应头中的 `X-Space-Checksum`
|
||
|
||
如果上层业务追求最省事，可以直接用 `UpdateMyAsync(string)` 或 `UpdateMyAsync(object)`；
|
||
如果业务自己管理编码、压缩、protobuf、msgpack 等格式，则继续走 `byte[]` 上传下载接口。
|
||
|
||
## 10. 动态配置建议
|
||
|
||
动态配置拆为两层：
|
||
|
||
- `feature_flags`
|
||
- 适合直接做开关或 key-value 判断
|
||
- `dynamic_config`
|
||
- 适合结构化配置对象
|
||
|
||
Unity SDK 可以考虑：
|
||
|
||
- 把 `feature_flags` 映射成 `Dictionary<string, object>`
|
||
- 把 `dynamic_config` 保留原始 JSON，并允许上层自行反序列化
|
||
|
||
## 11. 错误与登录态处理
|
||
|
||
SDK 需要统一处理：
|
||
|
||
- HTTP 非 2xx
|
||
- 业务码非 0
|
||
- 401 / 登录态失效
|
||
- 维护模式
|
||
- 玩家被封禁
|
||
- 存档版本冲突
|
||
|
||
建议统一抛出：
|
||
|
||
```csharp
|
||
public sealed class BriskApiException : Exception {
|
||
public int HttpStatus { get; }
|
||
public int Code { get; }
|
||
public string ServerMessage { get; }
|
||
}
|
||
```
|
||
|
||
## 12. Unity 侧最小落地清单
|
||
|
||
第一版 SDK 至少要覆盖：
|
||
|
||
1. 初始化
|
||
2. 登录换票
|
||
3. 登录态保存
|
||
4. 玩家信息读取
|
||
5. 动态配置读取
|
||
6. 公告读取与已读
|
||
7. 排行榜提交与读取
|
||
8. 云存档上传下载
|
||
9. 玩家空间读取、写入、点赞
|
||
10. 按 `login_provider + login_user_id` 访问空间
|
||
|
||
## 13. 配套文件
|
||
|
||
- API 总文档：
|
||
- [Brisk API接口与示例文档.md](/F:/OtherWork/BriskGameSerivce/Brisk%20API%E6%8E%A5%E5%8F%A3%E4%B8%8E%E7%A4%BA%E4%BE%8B%E6%96%87%E6%A1%A3.md)
|
||
- OpenAPI：
|
||
- [openapi.yaml](/F:/OtherWork/BriskGameSerivce/openapi.yaml)
|