CC-Framework.BriskGameServer/Brisk Unity SDK 快速开始.md

# Brisk Unity SDK 快速开始

本文档用于说明当前仓库内这套 Brisk Unity SDK 的最小接入方式。

## 1. 当前能力

当前 SDK 已经打通以下主链路：

- 初始化 `Brisk.InitializeAsync`
- 本地会话恢复
- 登录与登出
- 玩家信息
- 动态配置
- 公告
- 排行榜
- 云存档
- 玩家空间

当前主要源码位于：

- `Assets/BriskSdk/Runtime`

最小示例脚本位于：

- `Assets/BriskSdk/Samples/QuickStart/BriskQuickStartSample.cs`

## 2. 最小初始化

```csharp
await Brisk.InitializeAsync(new BriskOptions
{
    BaseUrl = "https://brisk.lightyears.ltd",
    GameKey = "demo-game",
    ClientVersion = Application.version,
    DeviceId = SystemInfo.deviceUniqueIdentifier
});
```

说明：

- `BaseUrl` 必填
- `GameKey` 必填
- `ClientVersion` 可选但强烈建议传
- `DeviceId` 可选但建议传

## 3. 登录示例

按稳定用户 ID 登录：

```csharp
await Brisk.Auth.LoginWithUserIdAsync("tap", "tap_user_10001", new BriskProfile
{
    Nickname = "Player One"
});
```

按 code 登录：

```csharp
await Brisk.Auth.LoginWithCodeAsync("tap", "third-party-code");
```

## 4. 常用调用示例

读取当前玩家：

```csharp
var me = await Brisk.Player.GetMeAsync();
```

读取动态配置：

```csharp
var config = await Brisk.Config.GetCurrentAsync();
```

读取排行榜：

```csharp
var top = await Brisk.Leaderboard.GetTopAsync("season-score", 20);
var meRank = await Brisk.Leaderboard.GetMeAsync("season-score");
await Brisk.Leaderboard.SubmitScoreAsync("season-score", 128);
```

上传云存档：

```csharp
var bytes = System.Text.Encoding.UTF8.GetBytes("{\"save\":1}");
await Brisk.Archive.UploadAsync(1, bytes);
```

读取玩家空间：

```csharp
var space = await Brisk.Space.GetByLoginIdentityAsync("tap", "tap_user_10001");
```

## 5. 默认错误 UI

当前 SDK 已内置默认错误展示器：

- 维护中
- 封号
- 登录态失效

如果未自定义 `ErrorPresenter`，SDK 会自动使用默认 IMGUI 弹窗进行展示。

如需替换：

```csharp
Brisk.SetErrorPresenter(myPresenter);
```

接口为：

```csharp
public interface IBriskErrorPresenter
{
    void ShowBlockingError(BriskBlockingException exception);
    void ShowAuthExpired(BriskAuthExpiredException exception);
}
```

如需在阻断错误确认后执行你自己的退出逻辑：

```csharp
await Brisk.InitializeAsync(new BriskOptions
{
    BaseUrl = "...",
    GameKey = "...",
    ExitHandler = () => Application.Quit()
});
```

## 6. 示例脚本使用方式

当前项目已提供：

- `Assets/BriskSdk/Samples/QuickStart/BriskQuickStartSample.cs`
- `Assets/Scenes/BriskQuickStartScene.unity`

使用方式：

1. 当前仓库是原始 Unity 开发工程，可直接打开 `Assets/Scenes/BriskQuickStartScene.unity`
2. 运行后会看到一个 IMGUI 调试面板，可直接测试初始化、登录、玩家、配置、公告、排行榜、云存档、空间等完整流程
3. 勾选 `AutoRunOnStart`
4. 如需更换环境参数，可在 Inspector 里修改 `BaseUrl`、`GameKey`、`LoginProvider`、`LoginUserId` 等字段后再运行

也可以在组件右键菜单里执行：

- `Run Brisk Sample`

## 7. 当前实现状态

当前 SDK 已实现主流程，但还建议后续继续补：

- 更细粒度的业务异常类型
- 弱网策略
- 更完整的接入文档与注释