KCP-Sync-Core：确定性状态同步与客户端预测实验平台

KCP-Sync-Core 是一个基于 Unity 的状态同步参考实现，用于验证固定 Tick、Q16.16 定点模拟、快照插值、客户端预测、服务器校正、回滚重演和可配置弱网条件之间的协作边界。当前拓扑采用单进程 loopback transport，适用于算法回归、故障复现与性能测量，不覆盖真实 Socket 或 Dedicated Server 部署。

简体中文 HUD	English HUD

实现范围

• 独立固定 Tick 逻辑层，不依赖 MonoBehaviour.Update、Time.deltaTime 或 Transform 参与权威计算。
• 客户端立即消费本地输入进行预测；服务器状态到达后按确认 Tick 清理输入并执行 reconciliation。
• 客户端输入通过内置的 kcp2k 低层状态机（ACK、RTO、快速重传）传递；世界快照走不可靠时序通道，避免旧快照造成队头阻塞。
• 远端实体使用快照环形缓冲、插值播放与简单的 jitter-buffer time dilation。
• 逻辑坐标与渲染坐标分离，校正后的视觉对象以临界阻尼弹簧（SmoothDamp）追赶，避免硬瞬移；该平滑只存在于表现层。
• 可在运行时调整基础延迟、抖动和丢包率，并对比预测开启/关闭时的手感差异。
• 核心序列化、定点运算和模拟代码位于不引用 UnityEngine 的 KcpSyncCore.Core 程序集，可独立测试。

快速运行

项目使用 Unity 6000.3.9f1。

1. 用 Unity Hub 打开本目录。
2. 选择菜单 KCP Sync Core > Build Demo Scene。该命令会生成 Assets/KcpSyncCore/Scenes/KcpSyncLab.unity，写入 Build Settings，并同步项目标识与版本号。
3. 打开生成的场景并进入 Play Mode。
4. 进入 Play Mode 后按下表操作。HUD 可直接调整延迟、抖动和丢包率，也可用快捷键切换预设与中英文。

控制表

输入	功能
WASD / 方向键	移动本地玩家；输入会量化后进入固定 Tick 模拟。
J	跳跃。
Space	开火；本地立即播放预测弹道反馈，命中结果由同步会话推进。
P	开启/关闭客户端预测，用于和纯延迟状态流做 A/B 对比。
R	注入一次权威位置校正，观察 reconciliation 与视觉平滑追赶。
F1	LAN 预设：18 ms 基础延迟、±2 ms 抖动、0% 丢包。
F2	4G 预设：105 ms 基础延迟、±38 ms 抖动、5% 丢包。
F3	Chaos 预设：200 ms 基础延迟、±80 ms 抖动、12% 丢包。
L	在简体中文和 English HUD 之间切换。
鼠标 / 触控板	操作 HUD 的弱网滑杆、预设按钮和语言切换按钮。

中英文切换 / Language

HUD 支持简体中文和 English。可以点击 HUD 内的语言按钮，也可以按 L 即时切换。首次运行且尚无已保存偏好时，界面会依据系统语言选择初始语言；用户切换后会通过 PlayerPrefs 记住选择，后续启动优先恢复该偏好。

语言切换只影响 Runtime/Presentation 的静态文本和界面显示，不改变输入、网络包、状态哈希或权威模拟结果。字体加载与界面文本生成不属于后文所述的 Core 0 B 热路径测量范围。

构建与测试

本地构建会生成 Builds/macOS/KcpSyncCoreDemo.app。Builds/ 是可复现产物，不纳入 Git 历史；可通过菜单 KCP Sync Core > Build macOS Development Player 或下面的批处理入口生成：

"/Applications/Unity/Hub/Editor/6000.3.9f1/Unity.app/Contents/MacOS/Unity" \
  -batchmode -quit \
  -projectPath "$PWD" \
  -executeMethod KcpSyncCore.Editor.BuildAutomation.BuildMacBatch \
  -logFile "$PWD/Builds/macOS/build.log"

也可以在 CI 或终端中生成场景：

"/Applications/Unity/Hub/Editor/6000.3.9f1/Unity.app/Contents/MacOS/Unity" \
  -batchmode -quit \
  -projectPath "$PWD" \
  -executeMethod KcpSyncCore.Editor.DemoSceneBuilder.Execute \
  -logFile -

运行 EditMode 测试：

mkdir -p "$PWD/TestResults"

"/Applications/Unity/Hub/Editor/6000.3.9f1/Unity.app/Contents/MacOS/Unity" \
  -batchmode \
  -projectPath "$PWD" \
  -runTests -testPlatform EditMode \
  -testResults "$PWD/TestResults/editmode.xml" \
  -logFile "$PWD/TestResults/editmode.log"

当前共有 12 个 EditMode 测试，覆盖 Q16.16 运算、序列化 roundtrip、逐 Tick 一致性、1,200 Tick replay rolling hash、弱网队列调度、KCP 重传、ISyncTransport 注入边界、历史缓冲诊断、本地化文本切换和长时间 Tick 回归。弱网 soak 测试还会在指定运行时下检查预热后的 CoreAllocatedBytesLastTick；该断言不代表整个 Unity Player 均无托管分配。

架构

输入采样 (Unity Runtime)
        │ PlayerInput + Tick
        ▼
客户端固定 Tick ───────► 预测状态 / 未确认输入环形缓冲
        │                                │
        │ 弱网注入                       │ Server Ack
        ▼                                ▼
服务器固定 Tick ───────► 权威快照 ─────► 校验 / 回滚 / 重演
                                             │
                                             ▼
                                       视觉平滑追赶

• Assets/KcpSyncCore/Core：纯 C# 逻辑与数据结构；程序集启用 noEngineReferences。
• Assets/KcpSyncCore/Runtime：Unity 输入、Tick 驱动、场景表现和 HUD 数据注入。
• Assets/KcpSyncCore/Editor：可重复生成 Demo 场景与构建配置。
• Assets/KcpSyncCore/Tests：确定性、序列化、弱网队列和模拟一致性测试。

更详细的边界与数据流见 ARCHITECTURE.md。

可重复实验与观测指标

建议在固定初始状态下运行以下对照，并记录 ServerAckTick、校正次数、校正误差、输入重传量、队列高水位和快照缓冲深度：

1. 0 ms / 0% loss：建立无弱网注入的基线，记录预测状态与权威状态之间的误差。
2. 150–200 ms / 30 ms jitter / 10% loss：观察确认延迟、重传次数和 reconciliation 误差分布。
3. 保持弱网参数不变并关闭预测：测量输入到可见状态更新之间的延迟及更新间隔。
4. 按 R 注入权威校正：观察逻辑状态重演结果与渲染状态平滑追赶之间的分离。

故障分析可沿单个 Tick 的生命周期进行：输入采样与量化、客户端预测、可靠输入传输、服务器推进、快照确认、历史裁剪和未确认输入重演。自动化测试用于检查当前运行环境和给定输入序列下的状态一致性；视觉平滑仍需结合帧时间、误差曲线和运行时采样单独评估。

托管分配测量边界

本文中的 0 B 仅指预热后，由 SyncSession.Step 内部测量的固定 Tick、定点状态推进、环形缓冲和二进制序列化路径。该结果依赖 Unity 版本、运行时、脚本后端和采样窗口，不覆盖 Editor、Profiler、IMGUI、字体初始化、日志或场景创建。

建议在 Development Player 中关闭 Deep Profile，先预热数秒，再用 Profiler 的 GC Alloc 列和 ProfilerRecorder 只包围核心 Tick/Serialize 调用测量；同时记录测试平台、脚本后端和采样窗口。若 HUD 导致噪声，应先关闭 HUD 再采样。不要把 Editor 总分配量当作核心算法结论。

KCP 集成范围

项目按 MIT 许可内置 kcp2k V1.41 的低层 KCP 状态机，默认 SyncSession 使用 KcpLoopbackTransport。客户端输入通过 KCP send window、ACK、RTO 和重传路径传递；世界快照使用独立的不可靠时序通道，以避免过期快照造成可靠流队头阻塞。第三方版本与范围见 Assets/KcpSyncCore/ThirdParty/THIRD_PARTY_NOTICES.md。

底层 datagram 当前是单进程、确定性的内存弱网实现。因此现有结果覆盖模拟延迟、抖动和丢包条件下的 KCP 状态机行为，不覆盖 Socket I/O、跨进程时钟、真实 MTU、带宽竞争、会话认证或 Dedicated Server 部署。生产化时可保留协议与 Tick 语义，将 ISyncTransport 的 datagram 边界替换为 Socket/Relay，并补充 MTU 探测、超时与重连、限带宽、抓包和双进程 soak。

限制与后续工作

• 当前拓扑为单进程客户端/服务器 loopback，不包含生产级 UDP 或 Dedicated Server。
• 定点数降低了浮点实现差异造成的数值分歧，但跨平台确定性仍取决于溢出策略、系统执行顺序、碰撞算法、随机数和编译后端。
• 弱网模拟器当前覆盖延迟、抖动和丢包；乱序、重复包、带宽限制、突发丢包和进程暂停尚未纳入模型。

License

项目自有源码使用 MIT License。内置的 kcp2k 低层核心与 Noto Sans SC 字体继续适用各自许可证，版本、来源和使用范围见 Assets/KcpSyncCore/ThirdParty/THIRD_PARTY_NOTICES.md。