SDK · Unity/.NET

im.balala.unity-sdk 是 imcore IM 服务端的 Unity / .NET 客户端 SDK（Unity 2021.3+，.NET Standard 2.1，C# 9）。基于 async/await 的 WebSocket + JSON， 协议命令与 DTO 从 clients/protocol.yaml 生成，与其他四端 SDK 同一 wire 契约。核心程序集无 UnityEngine 依赖，可在任意 .NET 项目复用。

引入（UPM）

Unity Package Manager → Install package from tarball → 下载页的 imcore-sdk-unity-<版本>.tar.gz；或源码方式在 Packages/manifest.json 中加 "im.balala.unity-sdk": "file:../clients/unity"。

包内两个程序集：Imcore.SDK（协议核心）与 Imcore.Unity（主线程回调、 PlayerPrefs 存储、暂停/恢复生命周期适配）。

用法

using Imcore.Sdk;
using Imcore.Unity;

// 在 Unity 主线程调用：回调全部封送回主线程
var im = ImcoreUnity.CreateClient(o =>
{
    o.Url = "wss://your-host/acc";
    o.Auth = new AuthConfig(
        token: "<jwt>",
        login: new LoginPayload(userId: "1001", userName: "alice"));
});
ImcoreUnity.AttachLifecycle(im); // 应用暂停断开、恢复重连

im.StatusChanged += s => Debug.Log($"imcore: {s}"); // Idle/Connecting/Open/Authenticated/Closed/ReauthRequired
using var sub = im.On(Cmd.ChatMessage, payload =>
    Debug.Log($"msg {payload["text"]?.AsString()}"));

// ConnectAsync 在服务端确认登录后才返回；登录被拒（如 token 无效）会抛
// RequestError —— 务必包裹。
try
{
    await im.ConnectAsync();
    await im.Dm.SendAsync(targetUserId: "1002", text: "hi");
    var history = await im.Dm.HistoryAsync(targetUserId: "1002", limit: 20);

    // 任意尚未封装的命令的逃生通道：
    await im.RequestAsync("chat_group_create",
        JsonValue.Object().Set("name", JsonValue.Of("team")));
    await im.SendAsync("chat_dm_typing",
        JsonValue.Object().Set("targetUserID", JsonValue.Of("1002")));
}
catch (RequestError e)
{
    Debug.LogError($"imcore error: {e.Message}");
}

离线队列

断线或未登录时用 SendQueuedAsync：消息写入 PlayerPrefs（可换自定义 IKeyValueStorage），重连登录成功后自动补发；im.Offline 提供手动 flush/重试/清空。

能力范围（首期）

传输内核 + seq 关联的请求/响应 + 登录确认门控的 connect + 类型化的 DM/群/聊天室 API + 离线发送队列 + Unity 生命周期适配。不含： Unity UIKit、HTTP 媒体上传、本地聊天缓存、WebGL 内置通道（可注入自定义 IWebSocketChannel）与 E2EE。

核心协议层由 dotnet test 全量覆盖；Imcore.Unity 适配层在编辑器内 验证。接入前请先对你自己的部署验证。