1480 lines
50 KiB
Markdown
1480 lines
50 KiB
Markdown
# 框架接口与协议层（共享层）实现计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 落地客户端与服务端共用的「框架共享层」：第 5 节接口契约 + 手写二进制网络协议编解码 + 确定性随机数；一份源码两端各编一次（A1），`dotnet test` 全绿，先不接任何具体小游戏。
|
||
|
||
**Architecture:** 共享源码的**唯一规范副本**放在 `Client/Assets/Framework/Shared/`，带一个 `noEngineReferences: true` 的 asmdef（编译期强制「绝不引用 UnityEngine」，对应设计 §2.1 的依赖铁律，且本程序集**不进** HybridCLR 热更列表 —— 框架接口类型常驻、不随小游戏卸载，对应 §4.2）。服务端 .NET 工程通过 `<Compile Include="..\..\Client\Assets\Framework\Shared\**\*.cs" />` **链接同一批 .cs**，不拷贝。绝大部分 TDD 在 .NET 侧用 xUnit 完成（编解码 / 随机数 / 帧封装的往返与边界），无需打开 Unity；Unity 侧只做一次 asmdef 集成与编译核对。
|
||
|
||
**Tech Stack:** C# 9（语言级别对齐 Unity）· 共享库 `netstandard2.1`（API 面对齐 Unity/HybridCLR）· 测试 `net10.0` + xUnit · 手写二进制编解码（varint/zigzag，无反射，AOT/WASM 友好）· .NET SDK 10.0.201（已安装）。
|
||
|
||
---
|
||
|
||
## 背景锁定（来自架构设计与代码勘察）
|
||
|
||
- 设计文档：`docs/superpowers/specs/2026-06-18-csharp-hotfix-minigame-architecture-design.md`，本计划落地其 §9 路线**第 1 步**。
|
||
- 客户端唯一热更程序集是 `XWorld.Link`（`Client/ProjectSettings/HybridCLRSettings.asset` 的 `hotUpdateAssemblies`）。本共享层**不加入**该列表（常驻不热更）。
|
||
- `Server/` 目录目前为空，本计划在其中新建首批 .NET 工程。
|
||
- RPS 现为 Lua（`Client/Assets/RockPaperScissors/script/`），本步骤**不改动它**；只为后续 §9 第 5 步用 C# 重写打地基。
|
||
- 已确认 `dotnet` 可用：`10.0.201`（SDK 9 与 10 均在）。
|
||
|
||
## 命名与依赖约定（贯穿全计划，务必一致）
|
||
|
||
- 命名空间：SDK 契约与基础类型 → `XWorld.Framework`；协议编解码 → `XWorld.Framework.Protocol`。
|
||
- 程序集名：`XWorld.Framework.Shared`（Unity asmdef 名与 .NET `AssemblyName` 一致）。
|
||
- 共享库**只允许** `netstandard2.1` API + C# 9 语法。禁止：`UnityEngine`、`System.IO`/socket 等平台 API、`record`/顶级语句/`init`-only 之外的 C# 10+ 语法。
|
||
- `byte[] Encode()` / `static T Decode(byte[])` 是所有线网 DTO 的统一约定；所有多字节整数一律**小端**，浮点 4 字节小端。
|
||
|
||
## 文件结构（先定边界，再拆任务）
|
||
|
||
规范源码（Unity 与 .NET 共用同一批文件）：
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `Client/Assets/Framework/Shared/Framework.Shared.asmdef` | Unity 程序集定义（`noEngineReferences: true`，不入热更列表） |
|
||
| `Client/Assets/Framework/Shared/Capabilities.cs` | 平台能力接口：`IRandom` `ITimer` `ILogger` `IStorage` |
|
||
| `Client/Assets/Framework/Shared/GameTypes.cs` | 基础值类型：`PlayerInfo` `RoomConfig` `NetMessage` `StepResult<,>` |
|
||
| `Client/Assets/Framework/Shared/IGameLogic.cs` | Core 纯逻辑契约 `IGameLogic<TState,TInput,TEvent>` |
|
||
| `Client/Assets/Framework/Shared/IGameClient.cs` | 客户端薄层入口 `IGameClient` `IGameClientCtx` `IAssetLoader` |
|
||
| `Client/Assets/Framework/Shared/IGameServerRoom.cs` | 服务端薄层入口 `IGameServerRoom` `IRoomCtx` |
|
||
| `Client/Assets/Framework/Shared/DeterministicRandom.cs` | `IRandom` 的确定性实现（SplitMix64，可快照种子状态） |
|
||
| `Client/Assets/Framework/Shared/Protocol/PacketWriter.cs` | 低层写入器：varint/zigzag/string/blob/单精度 |
|
||
| `Client/Assets/Framework/Shared/Protocol/PacketReader.cs` | 低层读取器（与 Writer 对偶，越界抛 `FormatException`） |
|
||
| `Client/Assets/Framework/Shared/Protocol/FrameCodec.cs` | 帧信封 `Channel`/`Frame`/`FrameCodec`（Framework vs Game 双通道） |
|
||
| `Client/Assets/Framework/Shared/Protocol/FrameworkMessages.cs` | 框架控制消息：opcode 枚举 + 各 DTO 的 Encode/Decode |
|
||
|
||
.NET 工程（链接上面的源码 + 测试）：
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `Server/Framework.Shared/Framework.Shared.csproj` | `netstandard2.1` 类库，`<Compile Include>` 链接规范源码 |
|
||
| `Server/Framework.Shared.Tests/Framework.Shared.Tests.csproj` | `net10.0` + xUnit 测试工程 |
|
||
| `Server/Framework.Shared.Tests/PacketCodecTests.cs` | PacketWriter/Reader 往返与边界测试 |
|
||
| `Server/Framework.Shared.Tests/FrameCodecTests.cs` | 帧封装往返测试 |
|
||
| `Server/Framework.Shared.Tests/DeterministicRandomTests.cs` | 随机数确定性 / 范围 / 可复现测试 |
|
||
| `Server/Framework.Shared.Tests/FrameworkMessagesTests.cs` | 各控制消息往返测试 |
|
||
| `Server/Server.sln` | 解决方案，聚合上述两个工程 |
|
||
|
||
---
|
||
|
||
## Task 1: 搭建 .NET 工程骨架（库 + 测试 + 解决方案）
|
||
|
||
**Files:**
|
||
- Create: `Server/Framework.Shared/Framework.Shared.csproj`
|
||
- Create: `Server/Framework.Shared.Tests/Framework.Shared.Tests.csproj`
|
||
- Create: `Server/Server.sln`
|
||
- Create（占位规范源码目录）: `Client/Assets/Framework/Shared/`
|
||
|
||
- [ ] **Step 1: 用模板生成两个工程与解决方案**
|
||
|
||
在仓库根 `D:/UD/AI/AIC#Project` 执行：
|
||
|
||
```bash
|
||
dotnet new classlib -n Framework.Shared -o Server/Framework.Shared -f netstandard2.1
|
||
dotnet new xunit -n Framework.Shared.Tests -o Server/Framework.Shared.Tests
|
||
dotnet new sln -n Server -o Server
|
||
dotnet sln Server/Server.sln add Server/Framework.Shared/Framework.Shared.csproj
|
||
dotnet sln Server/Server.sln add Server/Framework.Shared.Tests/Framework.Shared.Tests.csproj
|
||
rm -f Server/Framework.Shared/Class1.cs Server/Framework.Shared.Tests/UnitTest1.cs
|
||
mkdir -p "Client/Assets/Framework/Shared/Protocol"
|
||
```
|
||
|
||
- [ ] **Step 2: 改写 `Server/Framework.Shared/Framework.Shared.csproj` 为「链接规范源码」**
|
||
|
||
完整替换文件内容：
|
||
|
||
```xml
|
||
<Project Sdk="Microsoft.NET.Sdk">
|
||
|
||
<PropertyGroup>
|
||
<TargetFramework>netstandard2.1</TargetFramework>
|
||
<LangVersion>9.0</LangVersion>
|
||
<Nullable>disable</Nullable>
|
||
<ImplicitUsings>disable</ImplicitUsings>
|
||
<AssemblyName>XWorld.Framework.Shared</AssemblyName>
|
||
<RootNamespace>XWorld.Framework</RootNamespace>
|
||
<!-- 不编译本目录下的 .cs，规范源码全部来自 Client/Assets/Framework/Shared -->
|
||
<EnableDefaultCompileItems>false</EnableDefaultCompileItems>
|
||
</PropertyGroup>
|
||
|
||
<ItemGroup>
|
||
<Compile Include="..\..\Client\Assets\Framework\Shared\**\*.cs" />
|
||
</ItemGroup>
|
||
|
||
</Project>
|
||
```
|
||
|
||
- [ ] **Step 3: 让测试工程引用库**
|
||
|
||
在 `Server/Framework.Shared.Tests/Framework.Shared.Tests.csproj` 的 `</Project>` 之前加入（模板已含 xUnit 包引用，只补 ProjectReference）：
|
||
|
||
```xml
|
||
<ItemGroup>
|
||
<ProjectReference Include="..\Framework.Shared\Framework.Shared.csproj" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
- [ ] **Step 4: 放一个临时探针源码文件，验证链接链路通**
|
||
|
||
创建 `Client/Assets/Framework/Shared/_Probe.cs`：
|
||
|
||
```csharp
|
||
namespace XWorld.Framework
|
||
{
|
||
internal static class _Probe
|
||
{
|
||
public const int Value = 42;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 还原 + 构建，确认两端工程都能编**
|
||
|
||
Run: `dotnet build Server/Server.sln -v minimal`
|
||
Expected: `Build succeeded`，0 error。若报 `netstandard2.1` 目标包缺失，先确认 SDK 自带（10.x 自带 netstandard2.1 参考包，正常无需额外安装）。
|
||
|
||
- [ ] **Step 6: 删除探针并提交骨架**
|
||
|
||
```bash
|
||
rm -f "Client/Assets/Framework/Shared/_Probe.cs"
|
||
git init 2>/dev/null; git add Server "Client/Assets/Framework/Shared"
|
||
git commit -m "chore(framework): scaffold shared layer netstandard2.1 lib + xunit tests linking canonical sources"
|
||
```
|
||
|
||
> 注：仓库当前非 git 仓库（环境探测 `Is a git repository: false`）。若团队已有版本库，跳过 `git init`，按实际仓库提交。
|
||
|
||
---
|
||
|
||
## Task 2: 平台能力接口与基础值类型（编译核对）
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/Capabilities.cs`
|
||
- Create: `Client/Assets/Framework/Shared/GameTypes.cs`
|
||
|
||
> 纯声明，无运行时行为，用 `dotnet build` 核对（TDD 的红/绿留给后续有行为的任务）。
|
||
|
||
- [ ] **Step 1: 写 `Capabilities.cs`**
|
||
|
||
```csharp
|
||
namespace XWorld.Framework
|
||
{
|
||
// 服务端权威随机 / 客户端用服务端下发的种子复现
|
||
public interface IRandom
|
||
{
|
||
int Next(int maxExclusive); // 返回 [0, maxExclusive)
|
||
}
|
||
|
||
public interface ITimer
|
||
{
|
||
float Now { get; } // 单调递增的秒
|
||
}
|
||
|
||
public interface ILogger
|
||
{
|
||
void Info(string message);
|
||
void Warn(string message);
|
||
void Error(string message);
|
||
}
|
||
|
||
// 仅服务端注入；客户端 ctx 不提供
|
||
public interface IStorage
|
||
{
|
||
byte[] Load(string key); // 不存在返回 null
|
||
void Save(string key, byte[] data);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 写 `GameTypes.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
using System.Collections.Generic;
|
||
|
||
namespace XWorld.Framework
|
||
{
|
||
public sealed class PlayerInfo
|
||
{
|
||
public int PlayerId;
|
||
public string Name;
|
||
public bool IsAI;
|
||
}
|
||
|
||
public sealed class RoomConfig
|
||
{
|
||
public string GameId;
|
||
public int Version;
|
||
public ulong Seed; // 权威随机种子，两端共用以复现
|
||
public int PlayerCount;
|
||
public IReadOnlyDictionary<string, string> Params; // 小游戏自定义参数，可为 null
|
||
}
|
||
|
||
// 一条小游戏业务消息（承载在帧的 Game 通道里）
|
||
public readonly struct NetMessage
|
||
{
|
||
public readonly ushort Opcode;
|
||
public readonly byte[] Payload;
|
||
|
||
public NetMessage(ushort opcode, byte[] payload)
|
||
{
|
||
Opcode = opcode;
|
||
Payload = payload ?? Array.Empty<byte>();
|
||
}
|
||
}
|
||
|
||
// Core.Step 的纯函数式返回：新状态 + 本步事件
|
||
public readonly struct StepResult<TState, TEvent>
|
||
{
|
||
public readonly TState State;
|
||
public readonly IReadOnlyList<TEvent> Events;
|
||
|
||
public StepResult(TState state, IReadOnlyList<TEvent> events)
|
||
{
|
||
State = state;
|
||
Events = events ?? Array.Empty<TEvent>();
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 构建核对**
|
||
|
||
Run: `dotnet build Server/Server.sln -v minimal`
|
||
Expected: `Build succeeded`，0 error/warning。
|
||
|
||
- [ ] **Step 4: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/Capabilities.cs" "Client/Assets/Framework/Shared/GameTypes.cs"
|
||
git commit -m "feat(framework): platform capability interfaces and core value types"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: 三个入口契约接口（编译核对）
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/IGameLogic.cs`
|
||
- Create: `Client/Assets/Framework/Shared/IGameClient.cs`
|
||
- Create: `Client/Assets/Framework/Shared/IGameServerRoom.cs`
|
||
|
||
- [ ] **Step 1: 写 `IGameLogic.cs`（Core 纯逻辑契约）**
|
||
|
||
```csharp
|
||
namespace XWorld.Framework
|
||
{
|
||
// 平台无关、纯函数式的权威逻辑；两端共用做权威计算与客户端预演
|
||
public interface IGameLogic<TState, TInput, TEvent>
|
||
{
|
||
TState CreateInitial(RoomConfig config, IRandom random);
|
||
StepResult<TState, TEvent> Step(TState state, TInput input, IRandom random);
|
||
byte[] Encode(TState state); // 快照编解码，两端共用
|
||
TState Decode(byte[] data);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 写 `IGameClient.cs`（客户端薄层入口）**
|
||
|
||
```csharp
|
||
namespace XWorld.Framework
|
||
{
|
||
// 资源加载抽象，避免共享层引用 UnityEngine；客户端实现里再转成具体 Unity 对象
|
||
public interface IAssetLoader
|
||
{
|
||
object Load(string path); // 返回值由客户端薄层按需强转
|
||
}
|
||
|
||
public interface IGameClientCtx
|
||
{
|
||
IAssetLoader Assets { get; }
|
||
ILogger Logger { get; }
|
||
void Send(NetMessage message); // 发往服务端（Game 通道）
|
||
void Exit(); // 请求退出当前小游戏
|
||
}
|
||
|
||
public interface IGameClient
|
||
{
|
||
void OnEnter(IGameClientCtx ctx);
|
||
void OnNetMessage(NetMessage message);
|
||
void OnUpdate(float deltaTime);
|
||
void OnExit();
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 写 `IGameServerRoom.cs`（服务端薄层入口）**
|
||
|
||
```csharp
|
||
using System.Collections.Generic;
|
||
|
||
namespace XWorld.Framework
|
||
{
|
||
public interface IRoomCtx
|
||
{
|
||
IRandom Random { get; } // 权威随机
|
||
ITimer Timer { get; }
|
||
ILogger Logger { get; }
|
||
IStorage Storage { get; }
|
||
void Broadcast(NetMessage message);
|
||
void SendTo(int playerId, NetMessage message);
|
||
void EndRoom(); // 由小游戏逻辑请求结束本房间
|
||
}
|
||
|
||
public interface IGameServerRoom
|
||
{
|
||
void OnRoomStart(IReadOnlyList<PlayerInfo> players, IRoomCtx ctx);
|
||
void OnMessage(int playerId, NetMessage message);
|
||
void OnTick(float deltaTime); // 10-20Hz，内部调用 Core.Step + 广播快照
|
||
void OnRoomEnd();
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 构建核对**
|
||
|
||
Run: `dotnet build Server/Server.sln -v minimal`
|
||
Expected: `Build succeeded`，0 error。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/IGameLogic.cs" "Client/Assets/Framework/Shared/IGameClient.cs" "Client/Assets/Framework/Shared/IGameServerRoom.cs"
|
||
git commit -m "feat(framework): game logic / client / server room entry contracts"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: 低层编解码 PacketWriter / PacketReader（TDD 核心）
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/Protocol/PacketWriter.cs`
|
||
- Create: `Client/Assets/Framework/Shared/Protocol/PacketReader.cs`
|
||
- Test: `Server/Framework.Shared.Tests/PacketCodecTests.cs`
|
||
|
||
- [ ] **Step 1: 先写失败测试 `PacketCodecTests.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
using Xunit;
|
||
using XWorld.Framework.Protocol;
|
||
|
||
namespace XWorld.Framework.Tests
|
||
{
|
||
public class PacketCodecTests
|
||
{
|
||
[Theory]
|
||
[InlineData(0u)]
|
||
[InlineData(1u)]
|
||
[InlineData(127u)]
|
||
[InlineData(128u)]
|
||
[InlineData(16384u)]
|
||
[InlineData(uint.MaxValue)]
|
||
public void VarUInt_RoundTrips(uint value)
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarUInt(value);
|
||
var r = new PacketReader(w.ToArray());
|
||
Assert.Equal(value, r.ReadVarUInt());
|
||
Assert.False(r.HasMore);
|
||
}
|
||
|
||
[Theory]
|
||
[InlineData(0)]
|
||
[InlineData(1)]
|
||
[InlineData(-1)]
|
||
[InlineData(int.MaxValue)]
|
||
[InlineData(int.MinValue)]
|
||
public void VarInt_RoundTrips(int value)
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarInt(value);
|
||
var r = new PacketReader(w.ToArray());
|
||
Assert.Equal(value, r.ReadVarInt());
|
||
}
|
||
|
||
[Theory]
|
||
[InlineData(0L)]
|
||
[InlineData(-1234567890123L)]
|
||
[InlineData(long.MaxValue)]
|
||
[InlineData(long.MinValue)]
|
||
public void VarLong_RoundTrips(long value)
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarLong(value);
|
||
var r = new PacketReader(w.ToArray());
|
||
Assert.Equal(value, r.ReadVarLong());
|
||
}
|
||
|
||
[Fact]
|
||
public void MixedSequence_RoundTrips_InOrder()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteBool(true);
|
||
w.WriteByte(200);
|
||
w.WriteUInt16(50000);
|
||
w.WriteVarInt(-42);
|
||
w.WriteSingle(3.14159f);
|
||
w.WriteString("héllo 世界");
|
||
w.WriteBytes(new byte[] { 1, 2, 3, 0, 255 });
|
||
|
||
var r = new PacketReader(w.ToArray());
|
||
Assert.True(r.ReadBool());
|
||
Assert.Equal((byte)200, r.ReadByte());
|
||
Assert.Equal((ushort)50000, r.ReadUInt16());
|
||
Assert.Equal(-42, r.ReadVarInt());
|
||
Assert.Equal(3.14159f, r.ReadSingle(), 5);
|
||
Assert.Equal("héllo 世界", r.ReadString());
|
||
Assert.Equal(new byte[] { 1, 2, 3, 0, 255 }, r.ReadBytes());
|
||
Assert.False(r.HasMore);
|
||
}
|
||
|
||
[Fact]
|
||
public void EmptyAndNull_String_Bytes_RoundTripAsEmpty()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteString(null);
|
||
w.WriteString("");
|
||
w.WriteBytes(null);
|
||
w.WriteBytes(Array.Empty<byte>());
|
||
|
||
var r = new PacketReader(w.ToArray());
|
||
Assert.Equal("", r.ReadString());
|
||
Assert.Equal("", r.ReadString());
|
||
Assert.Empty(r.ReadBytes());
|
||
Assert.Empty(r.ReadBytes());
|
||
}
|
||
|
||
[Fact]
|
||
public void ReadPastEnd_Throws()
|
||
{
|
||
var r = new PacketReader(Array.Empty<byte>());
|
||
Assert.Throws<FormatException>(() => r.ReadByte());
|
||
}
|
||
|
||
[Fact]
|
||
public void ReadBytes_WithBogusLength_Throws()
|
||
{
|
||
// 长度前缀声称 10 字节，实际无数据
|
||
var w = new PacketWriter();
|
||
w.WriteVarUInt(10);
|
||
var r = new PacketReader(w.ToArray());
|
||
Assert.Throws<FormatException>(() => r.ReadBytes());
|
||
}
|
||
|
||
// —— 畸形 varint 拒绝（C# 移位掩码导致的静默损坏防护）——
|
||
|
||
[Fact]
|
||
public void ReadVarUInt_SixthByte_Throws()
|
||
{
|
||
// 5 个延续字节后还有第 6 字节 → 过长，必须抛异常而非静默损坏
|
||
var r = new PacketReader(new byte[] { 0xFF, 0xFF, 0xFF, 0xFF, 0x8F, 0x00 });
|
||
Assert.Throws<FormatException>(() => r.ReadVarUInt());
|
||
}
|
||
|
||
[Fact]
|
||
public void ReadVarUInt_LastByteOverflow_Throws()
|
||
{
|
||
// 第 5 字节 0x10 表示值超过 uint.MaxValue
|
||
var r = new PacketReader(new byte[] { 0xFF, 0xFF, 0xFF, 0xFF, 0x10 });
|
||
Assert.Throws<FormatException>(() => r.ReadVarUInt());
|
||
}
|
||
|
||
[Fact]
|
||
public void ReadVarLong_EleventhByte_Throws()
|
||
{
|
||
var r = new PacketReader(new byte[] { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x81, 0x00 });
|
||
Assert.Throws<FormatException>(() => r.ReadVarLong());
|
||
}
|
||
|
||
[Fact]
|
||
public void ReadVarLong_LastByteOverflow_Throws()
|
||
{
|
||
// 第 10 字节 0x02 表示值超过 ulong 的 64 位
|
||
var r = new PacketReader(new byte[] { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x02 });
|
||
Assert.Throws<FormatException>(() => r.ReadVarLong());
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试，确认编译失败/红**
|
||
|
||
Run: `dotnet test Server/Server.sln`
|
||
Expected: 编译失败（`PacketWriter`/`PacketReader` 不存在）。
|
||
|
||
- [ ] **Step 3: 写 `PacketWriter.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
using System.Collections.Generic;
|
||
using System.Text;
|
||
|
||
namespace XWorld.Framework.Protocol
|
||
{
|
||
// 手写小端二进制写入器：varint(LEB128) + zigzag，无反射，AOT/WASM 友好
|
||
public sealed class PacketWriter
|
||
{
|
||
private readonly List<byte> _buf;
|
||
|
||
public PacketWriter(int capacity = 64)
|
||
{
|
||
_buf = new List<byte>(capacity);
|
||
}
|
||
|
||
public void WriteByte(byte v) => _buf.Add(v);
|
||
|
||
public void WriteBool(bool v) => _buf.Add(v ? (byte)1 : (byte)0);
|
||
|
||
public void WriteUInt16(ushort v)
|
||
{
|
||
_buf.Add((byte)(v & 0xFF));
|
||
_buf.Add((byte)((v >> 8) & 0xFF));
|
||
}
|
||
|
||
public void WriteVarUInt(uint v)
|
||
{
|
||
while (v >= 0x80)
|
||
{
|
||
_buf.Add((byte)(v | 0x80));
|
||
v >>= 7;
|
||
}
|
||
_buf.Add((byte)v);
|
||
}
|
||
|
||
public void WriteVarInt(int v)
|
||
{
|
||
uint zig = (uint)((v << 1) ^ (v >> 31)); // zigzag
|
||
WriteVarUInt(zig);
|
||
}
|
||
|
||
public void WriteVarLong(long v)
|
||
{
|
||
ulong zig = (ulong)((v << 1) ^ (v >> 63));
|
||
while (zig >= 0x80)
|
||
{
|
||
_buf.Add((byte)(zig | 0x80));
|
||
zig >>= 7;
|
||
}
|
||
_buf.Add((byte)zig);
|
||
}
|
||
|
||
public void WriteSingle(float v)
|
||
{
|
||
byte[] b = BitConverter.GetBytes(v);
|
||
if (!BitConverter.IsLittleEndian) Array.Reverse(b);
|
||
_buf.Add(b[0]); _buf.Add(b[1]); _buf.Add(b[2]); _buf.Add(b[3]);
|
||
}
|
||
|
||
public void WriteBytes(byte[] data)
|
||
{
|
||
if (data == null || data.Length == 0)
|
||
{
|
||
WriteVarUInt(0);
|
||
return;
|
||
}
|
||
WriteVarUInt((uint)data.Length);
|
||
_buf.AddRange(data);
|
||
}
|
||
|
||
public void WriteString(string s)
|
||
{
|
||
if (string.IsNullOrEmpty(s))
|
||
{
|
||
WriteVarUInt(0);
|
||
return;
|
||
}
|
||
byte[] b = Encoding.UTF8.GetBytes(s);
|
||
WriteVarUInt((uint)b.Length);
|
||
_buf.AddRange(b);
|
||
}
|
||
|
||
public byte[] ToArray() => _buf.ToArray();
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 写 `PacketReader.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
using System.Text;
|
||
|
||
namespace XWorld.Framework.Protocol
|
||
{
|
||
// 与 PacketWriter 对偶；任何越界/畸形长度抛 FormatException（容错入口统一）
|
||
public sealed class PacketReader
|
||
{
|
||
private readonly byte[] _buf;
|
||
private int _pos;
|
||
|
||
public PacketReader(byte[] data)
|
||
{
|
||
_buf = data ?? Array.Empty<byte>();
|
||
_pos = 0;
|
||
}
|
||
|
||
public int Position => _pos;
|
||
public bool HasMore => _pos < _buf.Length;
|
||
|
||
public byte ReadByte()
|
||
{
|
||
if (_pos >= _buf.Length) throw new FormatException("PacketReader: read past end");
|
||
return _buf[_pos++];
|
||
}
|
||
|
||
public bool ReadBool() => ReadByte() != 0;
|
||
|
||
public ushort ReadUInt16()
|
||
{
|
||
byte lo = ReadByte();
|
||
byte hi = ReadByte();
|
||
return (ushort)(lo | (hi << 8));
|
||
}
|
||
|
||
public uint ReadVarUInt()
|
||
{
|
||
uint result = 0;
|
||
int shift = 0;
|
||
while (true)
|
||
{
|
||
if (shift > 28) throw new FormatException("PacketReader: varuint too long");
|
||
byte b = ReadByte();
|
||
// 第 5 字节(shift==28)只有低 4 位有效，超出即为越界 varuint
|
||
// 注意：C# 对 uint 的移位量按 0x1F 取模，必须在读第 6 字节前拦截
|
||
if (shift == 28 && (b & 0x70) != 0)
|
||
throw new FormatException("PacketReader: varuint overflow");
|
||
result |= (uint)(b & 0x7F) << shift;
|
||
if ((b & 0x80) == 0) break;
|
||
shift += 7;
|
||
}
|
||
return result;
|
||
}
|
||
|
||
public int ReadVarInt()
|
||
{
|
||
uint zig = ReadVarUInt();
|
||
return (int)(zig >> 1) ^ -(int)(zig & 1); // zigzag decode
|
||
}
|
||
|
||
public long ReadVarLong()
|
||
{
|
||
ulong result = 0;
|
||
int shift = 0;
|
||
while (true)
|
||
{
|
||
if (shift > 63) throw new FormatException("PacketReader: varlong too long");
|
||
byte b = ReadByte();
|
||
// 第 10 字节(shift==63)只有最低 1 位有效；ulong 移位量按 0x3F 取模
|
||
if (shift == 63 && (b & 0x7E) != 0)
|
||
throw new FormatException("PacketReader: varlong overflow");
|
||
result |= (ulong)(b & 0x7F) << shift;
|
||
if ((b & 0x80) == 0) break;
|
||
shift += 7;
|
||
}
|
||
return (long)(result >> 1) ^ -(long)(result & 1);
|
||
}
|
||
|
||
public float ReadSingle()
|
||
{
|
||
byte[] b = new byte[4];
|
||
b[0] = ReadByte(); b[1] = ReadByte(); b[2] = ReadByte(); b[3] = ReadByte();
|
||
if (!BitConverter.IsLittleEndian) Array.Reverse(b);
|
||
return BitConverter.ToSingle(b, 0);
|
||
}
|
||
|
||
public byte[] ReadBytes()
|
||
{
|
||
uint len = ReadVarUInt();
|
||
if (len == 0) return Array.Empty<byte>();
|
||
if (_pos + len > _buf.Length) throw new FormatException("PacketReader: bytes length exceeds buffer");
|
||
byte[] outv = new byte[len];
|
||
Array.Copy(_buf, _pos, outv, 0, (int)len);
|
||
_pos += (int)len;
|
||
return outv;
|
||
}
|
||
|
||
public string ReadString()
|
||
{
|
||
uint len = ReadVarUInt();
|
||
if (len == 0) return string.Empty;
|
||
if (_pos + len > _buf.Length) throw new FormatException("PacketReader: string length exceeds buffer");
|
||
string s = Encoding.UTF8.GetString(_buf, _pos, (int)len);
|
||
_pos += (int)len;
|
||
return s;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 运行测试，确认全绿**
|
||
|
||
Run: `dotnet test Server/Server.sln`
|
||
Expected: PASS，全部 `PacketCodecTests` 通过。
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/Protocol/PacketWriter.cs" "Client/Assets/Framework/Shared/Protocol/PacketReader.cs" Server/Framework.Shared.Tests/PacketCodecTests.cs
|
||
git commit -m "feat(protocol): hand-rolled binary PacketWriter/PacketReader with varint/zigzag"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: 帧信封 FrameCodec（TDD）
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/Protocol/FrameCodec.cs`
|
||
- Test: `Server/Framework.Shared.Tests/FrameCodecTests.cs`
|
||
|
||
帧线网格式：`[channel:u8][opcode:u16 小端][payloadLen:varuint][payload bytes]`，payload 自带长度前缀以便流式自定界（WebSocket 已有消息边界，但保留长度前缀让协议对传输无关）。
|
||
|
||
- [ ] **Step 1: 写失败测试 `FrameCodecTests.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
using Xunit;
|
||
using XWorld.Framework.Protocol;
|
||
|
||
namespace XWorld.Framework.Tests
|
||
{
|
||
public class FrameCodecTests
|
||
{
|
||
[Fact]
|
||
public void Frame_RoundTrips()
|
||
{
|
||
var original = new Frame(Channel.Game, 7, new byte[] { 10, 20, 30 });
|
||
byte[] wire = FrameCodec.Encode(original);
|
||
Frame decoded = FrameCodec.Decode(wire);
|
||
|
||
Assert.Equal(Channel.Game, decoded.Channel);
|
||
Assert.Equal((ushort)7, decoded.Opcode);
|
||
Assert.Equal(new byte[] { 10, 20, 30 }, decoded.Payload);
|
||
}
|
||
|
||
[Fact]
|
||
public void Frame_EmptyPayload_RoundTrips()
|
||
{
|
||
var original = new Frame(Channel.Framework, 1, null);
|
||
Frame decoded = FrameCodec.Decode(FrameCodec.Encode(original));
|
||
Assert.Equal(Channel.Framework, decoded.Channel);
|
||
Assert.Equal((ushort)1, decoded.Opcode);
|
||
Assert.Empty(decoded.Payload);
|
||
}
|
||
|
||
[Fact]
|
||
public void Encode_WireLayout_IsChannelOpcodeLenPayload()
|
||
{
|
||
var f = new Frame(Channel.Game, 0x0102, new byte[] { 0xAA });
|
||
byte[] wire = FrameCodec.Encode(f);
|
||
// channel=1, opcode 小端 = 02 01, len varuint = 1, payload = AA
|
||
Assert.Equal(new byte[] { 0x01, 0x02, 0x01, 0x01, 0xAA }, wire);
|
||
}
|
||
|
||
[Fact]
|
||
public void Decode_Truncated_Throws()
|
||
{
|
||
Assert.Throws<FormatException>(() => FrameCodec.Decode(new byte[] { 0x00 }));
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行，确认红**
|
||
|
||
Run: `dotnet test Server/Server.sln --filter FrameCodecTests`
|
||
Expected: 编译失败（`Frame`/`Channel`/`FrameCodec` 不存在）。
|
||
|
||
- [ ] **Step 3: 写 `FrameCodec.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
|
||
namespace XWorld.Framework.Protocol
|
||
{
|
||
public enum Channel : byte
|
||
{
|
||
Framework = 0, // 匹配/心跳/大厅等框架消息
|
||
Game = 1, // 转发给具体小游戏房间的业务消息
|
||
}
|
||
|
||
// 一帧线网消息
|
||
public readonly struct Frame
|
||
{
|
||
public readonly Channel Channel;
|
||
public readonly ushort Opcode;
|
||
public readonly byte[] Payload;
|
||
|
||
public Frame(Channel channel, ushort opcode, byte[] payload)
|
||
{
|
||
Channel = channel;
|
||
Opcode = opcode;
|
||
Payload = payload ?? Array.Empty<byte>();
|
||
}
|
||
}
|
||
|
||
public static class FrameCodec
|
||
{
|
||
// 线网: [channel:u8][opcode:u16 LE][payloadLen:varuint][payload]
|
||
public static byte[] Encode(Frame frame)
|
||
{
|
||
var w = new PacketWriter(frame.Payload.Length + 8);
|
||
w.WriteByte((byte)frame.Channel);
|
||
w.WriteUInt16(frame.Opcode);
|
||
w.WriteBytes(frame.Payload); // 自带 varuint 长度前缀
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static Frame Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
var channel = (Channel)r.ReadByte();
|
||
ushort opcode = r.ReadUInt16();
|
||
byte[] payload = r.ReadBytes();
|
||
return new Frame(channel, opcode, payload);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 运行，确认绿**
|
||
|
||
Run: `dotnet test Server/Server.sln --filter FrameCodecTests`
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/Protocol/FrameCodec.cs" Server/Framework.Shared.Tests/FrameCodecTests.cs
|
||
git commit -m "feat(protocol): Frame envelope + FrameCodec with framework/game channels"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: 确定性随机 DeterministicRandom（TDD）
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/DeterministicRandom.cs`
|
||
- Test: `Server/Framework.Shared.Tests/DeterministicRandomTests.cs`
|
||
|
||
对应设计 §4.4：权威随机由种子驱动，两端用同一算法复现。
|
||
|
||
- [ ] **Step 1: 写失败测试 `DeterministicRandomTests.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
using Xunit;
|
||
using XWorld.Framework;
|
||
|
||
namespace XWorld.Framework.Tests
|
||
{
|
||
public class DeterministicRandomTests
|
||
{
|
||
[Fact]
|
||
public void SameSeed_ProducesIdenticalSequence()
|
||
{
|
||
var a = new DeterministicRandom(12345UL);
|
||
var b = new DeterministicRandom(12345UL);
|
||
for (int i = 0; i < 1000; i++)
|
||
Assert.Equal(a.Next(100), b.Next(100));
|
||
}
|
||
|
||
[Fact]
|
||
public void DifferentSeed_DivergesQuickly()
|
||
{
|
||
var a = new DeterministicRandom(1UL);
|
||
var b = new DeterministicRandom(2UL);
|
||
bool anyDiff = false;
|
||
for (int i = 0; i < 20; i++)
|
||
if (a.Next(1_000_000) != b.Next(1_000_000)) { anyDiff = true; break; }
|
||
Assert.True(anyDiff);
|
||
}
|
||
|
||
[Fact]
|
||
public void Next_StaysInRange()
|
||
{
|
||
var rng = new DeterministicRandom(999UL);
|
||
for (int i = 0; i < 100_000; i++)
|
||
{
|
||
int v = rng.Next(7);
|
||
Assert.InRange(v, 0, 6);
|
||
}
|
||
}
|
||
|
||
[Fact]
|
||
public void Next_One_AlwaysZero()
|
||
{
|
||
var rng = new DeterministicRandom(42UL);
|
||
for (int i = 0; i < 100; i++)
|
||
Assert.Equal(0, rng.Next(1));
|
||
}
|
||
|
||
[Theory]
|
||
[InlineData(0)]
|
||
[InlineData(-3)]
|
||
public void Next_NonPositiveMax_Throws(int max)
|
||
{
|
||
var rng = new DeterministicRandom(42UL);
|
||
Assert.Throws<ArgumentOutOfRangeException>(() => rng.Next(max));
|
||
}
|
||
|
||
[Fact]
|
||
public void State_SnapshotAndResume_ContinuesIdentically()
|
||
{
|
||
var rng = new DeterministicRandom(7UL);
|
||
for (int i = 0; i < 10; i++) rng.Next(1000);
|
||
ulong snapshot = rng.State;
|
||
|
||
var resumed = new DeterministicRandom(snapshot);
|
||
// 注意：State 是当前内部状态，用它重建后序列从“下一步”继续
|
||
int[] fromOriginal = new int[5];
|
||
int[] fromResumed = new int[5];
|
||
for (int i = 0; i < 5; i++) fromOriginal[i] = rng.Next(1000);
|
||
for (int i = 0; i < 5; i++) fromResumed[i] = resumed.Next(1000);
|
||
Assert.Equal(fromOriginal, fromResumed);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行，确认红**
|
||
|
||
Run: `dotnet test Server/Server.sln --filter DeterministicRandomTests`
|
||
Expected: 编译失败（`DeterministicRandom` 不存在）。
|
||
|
||
- [ ] **Step 3: 写 `DeterministicRandom.cs`**
|
||
|
||
```csharp
|
||
using System;
|
||
|
||
namespace XWorld.Framework
|
||
{
|
||
// SplitMix64：跨平台确定性、无浮点、状态即种子（便于快照/复盘）
|
||
public sealed class DeterministicRandom : IRandom
|
||
{
|
||
private ulong _state;
|
||
|
||
public DeterministicRandom(ulong seed)
|
||
{
|
||
_state = seed;
|
||
}
|
||
|
||
// 当前内部状态；用它构造新实例可从“下一步”继续同一序列
|
||
public ulong State => _state;
|
||
|
||
private ulong NextU64()
|
||
{
|
||
_state += 0x9E3779B97F4A7C15UL;
|
||
ulong z = _state;
|
||
z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL;
|
||
z = (z ^ (z >> 27)) * 0x94D049BB133111EBUL;
|
||
return z ^ (z >> 31);
|
||
}
|
||
|
||
public int Next(int maxExclusive)
|
||
{
|
||
if (maxExclusive <= 0)
|
||
throw new ArgumentOutOfRangeException(nameof(maxExclusive), "maxExclusive 必须为正");
|
||
|
||
ulong bound = (ulong)maxExclusive;
|
||
// 拒绝采样，消除取模偏差
|
||
ulong threshold = (ulong.MaxValue - bound + 1) % bound;
|
||
while (true)
|
||
{
|
||
ulong r = NextU64();
|
||
if (r >= threshold) return (int)(r % bound);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 运行，确认绿**
|
||
|
||
Run: `dotnet test Server/Server.sln --filter DeterministicRandomTests`
|
||
Expected: PASS。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/DeterministicRandom.cs" Server/Framework.Shared.Tests/DeterministicRandomTests.cs
|
||
git commit -m "feat(framework): deterministic SplitMix64 IRandom with snapshottable state"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: 框架控制消息 DTO 与 opcode（TDD）
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/Protocol/FrameworkMessages.cs`
|
||
- Test: `Server/Framework.Shared.Tests/FrameworkMessagesTests.cs`
|
||
|
||
覆盖设计 §3.3 对局流程所需的框架级消息：心跳 / 匹配请求 / 匹配成功 / 玩家输入封装 / 状态快照 / 房间结束 / 错误。
|
||
|
||
- [ ] **Step 1: 写失败测试 `FrameworkMessagesTests.cs`**
|
||
|
||
```csharp
|
||
using System.Collections.Generic;
|
||
using Xunit;
|
||
using XWorld.Framework;
|
||
using XWorld.Framework.Protocol;
|
||
|
||
namespace XWorld.Framework.Tests
|
||
{
|
||
public class FrameworkMessagesTests
|
||
{
|
||
[Fact]
|
||
public void Heartbeat_RoundTrips()
|
||
{
|
||
var m = new HeartbeatMsg { ClientTimeMs = 1_725_000_000_123L };
|
||
var d = HeartbeatMsg.Decode(m.Encode());
|
||
Assert.Equal(m.ClientTimeMs, d.ClientTimeMs);
|
||
}
|
||
|
||
[Fact]
|
||
public void MatchRequest_RoundTrips()
|
||
{
|
||
var m = new MatchRequestMsg { GameId = "rock_paper_scissors", Version = 3 };
|
||
var d = MatchRequestMsg.Decode(m.Encode());
|
||
Assert.Equal(m.GameId, d.GameId);
|
||
Assert.Equal(m.Version, d.Version);
|
||
}
|
||
|
||
[Fact]
|
||
public void MatchFound_RoundTrips_WithPlayers()
|
||
{
|
||
var m = new MatchFoundMsg
|
||
{
|
||
RoomId = "room-42",
|
||
Version = 3,
|
||
SelfPlayerId = 1001,
|
||
Players =
|
||
{
|
||
new PlayerInfo { PlayerId = 1001, Name = "Alice", IsAI = false },
|
||
new PlayerInfo { PlayerId = -1, Name = "AI", IsAI = true },
|
||
},
|
||
};
|
||
var d = MatchFoundMsg.Decode(m.Encode());
|
||
Assert.Equal("room-42", d.RoomId);
|
||
Assert.Equal(3, d.Version);
|
||
Assert.Equal(1001, d.SelfPlayerId);
|
||
Assert.Equal(2, d.Players.Count);
|
||
Assert.Equal(1001, d.Players[0].PlayerId);
|
||
Assert.Equal("Alice", d.Players[0].Name);
|
||
Assert.False(d.Players[0].IsAI);
|
||
Assert.Equal(-1, d.Players[1].PlayerId);
|
||
Assert.True(d.Players[1].IsAI);
|
||
}
|
||
|
||
[Fact]
|
||
public void GameInput_RoundTrips()
|
||
{
|
||
var m = new GameInputMsg { GameOpcode = 12, Payload = new byte[] { 9, 8, 7 } };
|
||
var d = GameInputMsg.Decode(m.Encode());
|
||
Assert.Equal((ushort)12, d.GameOpcode);
|
||
Assert.Equal(new byte[] { 9, 8, 7 }, d.Payload);
|
||
}
|
||
|
||
[Fact]
|
||
public void Snapshot_RoundTrips()
|
||
{
|
||
var m = new SnapshotMsg { Tick = 250, StateBlob = new byte[] { 0xDE, 0xAD } };
|
||
var d = SnapshotMsg.Decode(m.Encode());
|
||
Assert.Equal(250, d.Tick);
|
||
Assert.Equal(new byte[] { 0xDE, 0xAD }, d.StateBlob);
|
||
}
|
||
|
||
[Fact]
|
||
public void RoomEnd_RoundTrips()
|
||
{
|
||
var m = new RoomEndMsg { WinnerPlayerId = 1001, ResultBlob = new byte[] { 1 } };
|
||
var d = RoomEndMsg.Decode(m.Encode());
|
||
Assert.Equal(1001, d.WinnerPlayerId);
|
||
Assert.Equal(new byte[] { 1 }, d.ResultBlob);
|
||
}
|
||
|
||
[Fact]
|
||
public void Error_RoundTrips()
|
||
{
|
||
var m = new ErrorMsg { Code = 404, Message = "version mismatch" };
|
||
var d = ErrorMsg.Decode(m.Encode());
|
||
Assert.Equal(404, d.Code);
|
||
Assert.Equal("version mismatch", d.Message);
|
||
}
|
||
|
||
[Fact]
|
||
public void Opcodes_AreStableValues()
|
||
{
|
||
// 线网兼容性：opcode 数值固定，改动等于破坏协议
|
||
Assert.Equal((ushort)1, (ushort)FrameworkOpcode.Heartbeat);
|
||
Assert.Equal((ushort)2, (ushort)FrameworkOpcode.MatchRequest);
|
||
Assert.Equal((ushort)3, (ushort)FrameworkOpcode.MatchFound);
|
||
Assert.Equal((ushort)4, (ushort)FrameworkOpcode.GameInput);
|
||
Assert.Equal((ushort)5, (ushort)FrameworkOpcode.Snapshot);
|
||
Assert.Equal((ushort)6, (ushort)FrameworkOpcode.RoomEnd);
|
||
Assert.Equal((ushort)7, (ushort)FrameworkOpcode.Error);
|
||
}
|
||
|
||
[Fact]
|
||
public void Message_TravelsInsideFrame()
|
||
{
|
||
// 端到端：DTO -> payload -> Frame -> wire -> Frame -> DTO
|
||
var req = new MatchRequestMsg { GameId = "rps", Version = 1 };
|
||
var frame = new Frame(Channel.Framework, (ushort)FrameworkOpcode.MatchRequest, req.Encode());
|
||
byte[] wire = FrameCodec.Encode(frame);
|
||
|
||
Frame back = FrameCodec.Decode(wire);
|
||
Assert.Equal(Channel.Framework, back.Channel);
|
||
Assert.Equal((ushort)FrameworkOpcode.MatchRequest, back.Opcode);
|
||
var d = MatchRequestMsg.Decode(back.Payload);
|
||
Assert.Equal("rps", d.GameId);
|
||
Assert.Equal(1, d.Version);
|
||
}
|
||
|
||
// —— null/空边界：记录并验证「null 与空线网等价」的有意行为 ——
|
||
|
||
[Fact]
|
||
public void GameInput_NullPayload_RoundTrips_AsEmpty()
|
||
{
|
||
var m = new GameInputMsg { GameOpcode = 5, Payload = null };
|
||
var d = GameInputMsg.Decode(m.Encode());
|
||
Assert.Equal((ushort)5, d.GameOpcode);
|
||
Assert.NotNull(d.Payload);
|
||
Assert.Empty(d.Payload);
|
||
}
|
||
|
||
[Fact]
|
||
public void Error_NullMessage_RoundTrips_AsEmpty()
|
||
{
|
||
var m = new ErrorMsg { Code = 7, Message = null };
|
||
var d = ErrorMsg.Decode(m.Encode());
|
||
Assert.Equal(7, d.Code);
|
||
Assert.Equal(string.Empty, d.Message);
|
||
}
|
||
|
||
[Fact]
|
||
public void MatchFound_EmptyPlayerList_RoundTrips()
|
||
{
|
||
var m = new MatchFoundMsg { RoomId = "r0", Version = 1, SelfPlayerId = 0 };
|
||
// Players 默认空列表，不添加任何玩家
|
||
var d = MatchFoundMsg.Decode(m.Encode());
|
||
Assert.Equal("r0", d.RoomId);
|
||
Assert.Equal(1, d.Version);
|
||
Assert.Equal(0, d.SelfPlayerId);
|
||
Assert.NotNull(d.Players);
|
||
Assert.Empty(d.Players);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> 注：DTO 中的不透明 `byte[]`（Payload/StateBlob/ResultBlob）与字符串（GameId/RoomId/Message）字段，null 在线网上等价于空值，Decode 恒返回非 null（空数组/空串）。`FrameworkMessages.cs` 对应字段已加单行注释说明。
|
||
|
||
- [ ] **Step 2: 运行，确认红**
|
||
|
||
Run: `dotnet test Server/Server.sln --filter FrameworkMessagesTests`
|
||
Expected: 编译失败（消息类型与 `FrameworkOpcode` 不存在）。
|
||
|
||
- [ ] **Step 3: 写 `FrameworkMessages.cs`**
|
||
|
||
```csharp
|
||
using System.Collections.Generic;
|
||
using XWorld.Framework;
|
||
|
||
namespace XWorld.Framework.Protocol
|
||
{
|
||
// 框架通道(Channel.Framework)的 opcode；数值是线网契约，禁止随意改动
|
||
public enum FrameworkOpcode : ushort
|
||
{
|
||
Heartbeat = 1,
|
||
MatchRequest = 2,
|
||
MatchFound = 3,
|
||
GameInput = 4,
|
||
Snapshot = 5,
|
||
RoomEnd = 6,
|
||
Error = 7,
|
||
}
|
||
|
||
public sealed class HeartbeatMsg
|
||
{
|
||
public long ClientTimeMs;
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarLong(ClientTimeMs);
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static HeartbeatMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
return new HeartbeatMsg { ClientTimeMs = r.ReadVarLong() };
|
||
}
|
||
}
|
||
|
||
public sealed class MatchRequestMsg
|
||
{
|
||
public string GameId;
|
||
public int Version;
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteString(GameId);
|
||
w.WriteVarInt(Version);
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static MatchRequestMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
return new MatchRequestMsg { GameId = r.ReadString(), Version = r.ReadVarInt() };
|
||
}
|
||
}
|
||
|
||
public sealed class MatchFoundMsg
|
||
{
|
||
public string RoomId;
|
||
public int Version;
|
||
public int SelfPlayerId;
|
||
public List<PlayerInfo> Players = new List<PlayerInfo>();
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteString(RoomId);
|
||
w.WriteVarInt(Version);
|
||
w.WriteVarInt(SelfPlayerId);
|
||
w.WriteVarUInt((uint)Players.Count);
|
||
foreach (var p in Players)
|
||
{
|
||
w.WriteVarInt(p.PlayerId);
|
||
w.WriteString(p.Name);
|
||
w.WriteBool(p.IsAI);
|
||
}
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static MatchFoundMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
var m = new MatchFoundMsg
|
||
{
|
||
RoomId = r.ReadString(),
|
||
Version = r.ReadVarInt(),
|
||
SelfPlayerId = r.ReadVarInt(),
|
||
};
|
||
uint n = r.ReadVarUInt();
|
||
for (uint i = 0; i < n; i++)
|
||
{
|
||
m.Players.Add(new PlayerInfo
|
||
{
|
||
PlayerId = r.ReadVarInt(),
|
||
Name = r.ReadString(),
|
||
IsAI = r.ReadBool(),
|
||
});
|
||
}
|
||
return m;
|
||
}
|
||
}
|
||
|
||
// 把一条小游戏业务输入封进框架通道（也可直接走 Channel.Game，二者择一，详见服务端子项目）
|
||
public sealed class GameInputMsg
|
||
{
|
||
public ushort GameOpcode;
|
||
public byte[] Payload;
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteUInt16(GameOpcode);
|
||
w.WriteBytes(Payload);
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static GameInputMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
return new GameInputMsg { GameOpcode = r.ReadUInt16(), Payload = r.ReadBytes() };
|
||
}
|
||
}
|
||
|
||
public sealed class SnapshotMsg
|
||
{
|
||
public int Tick;
|
||
public byte[] StateBlob; // 由小游戏 Core.Encode(state) 产出，框架不解释内容
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarInt(Tick);
|
||
w.WriteBytes(StateBlob);
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static SnapshotMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
return new SnapshotMsg { Tick = r.ReadVarInt(), StateBlob = r.ReadBytes() };
|
||
}
|
||
}
|
||
|
||
public sealed class RoomEndMsg
|
||
{
|
||
public int WinnerPlayerId; // 0 表示平局/无胜者
|
||
public byte[] ResultBlob; // 小游戏自定义结算数据
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarInt(WinnerPlayerId);
|
||
w.WriteBytes(ResultBlob);
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static RoomEndMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
return new RoomEndMsg { WinnerPlayerId = r.ReadVarInt(), ResultBlob = r.ReadBytes() };
|
||
}
|
||
}
|
||
|
||
public sealed class ErrorMsg
|
||
{
|
||
public int Code;
|
||
public string Message;
|
||
|
||
public byte[] Encode()
|
||
{
|
||
var w = new PacketWriter();
|
||
w.WriteVarInt(Code);
|
||
w.WriteString(Message);
|
||
return w.ToArray();
|
||
}
|
||
|
||
public static ErrorMsg Decode(byte[] data)
|
||
{
|
||
var r = new PacketReader(data);
|
||
return new ErrorMsg { Code = r.ReadVarInt(), Message = r.ReadString() };
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 运行全量测试，确认绿**
|
||
|
||
Run: `dotnet test Server/Server.sln`
|
||
Expected: 全部测试 PASS（四个测试类）。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/Protocol/FrameworkMessages.cs" Server/Framework.Shared.Tests/FrameworkMessagesTests.cs
|
||
git commit -m "feat(protocol): framework control messages (match/heartbeat/snapshot/roomend/error) with stable opcodes"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 8: Unity 程序集集成与跨端编译核对
|
||
|
||
**Files:**
|
||
- Create: `Client/Assets/Framework/Shared/Framework.Shared.asmdef`
|
||
- Verify: 共享层在 Unity 与 .NET **两端都能编**。
|
||
|
||
- [ ] **Step 1: 写 `Framework.Shared.asmdef`**
|
||
|
||
```json
|
||
{
|
||
"name": "XWorld.Framework.Shared",
|
||
"rootNamespace": "XWorld.Framework",
|
||
"references": [],
|
||
"includePlatforms": [],
|
||
"excludePlatforms": [],
|
||
"allowUnsafeCode": false,
|
||
"overrideReferences": false,
|
||
"precompiledReferences": [],
|
||
"autoReferenced": true,
|
||
"defineConstraints": [],
|
||
"versionDefines": [],
|
||
"noEngineReferences": true
|
||
}
|
||
```
|
||
|
||
> `noEngineReferences: true` 在 Unity 编译期强制本程序集不引用 `UnityEngine`/`UnityEditor`，正是设计 §2.1「Core 绝不引用 UnityEngine」的机器级护栏。**不要**把本程序集加入 `HybridCLRSettings.asset` 的 `hotUpdateAssemblies` —— 框架接口常驻、不热更（§4.2）。
|
||
|
||
- [ ] **Step 2: .NET 侧再跑一次全量测试（确保 asmdef 的加入没破坏链接 glob）**
|
||
|
||
Run: `dotnet test Server/Server.sln`
|
||
Expected: 全绿（asmdef 是 `.asmdef`，不在 `**\*.cs` glob 内，应无影响）。
|
||
|
||
- [ ] **Step 3: Unity 侧编译核对（人工检查点）**
|
||
|
||
打开 Unity 工程 `Client/`（菜单或命令行均可），等待编译：
|
||
- 在 Unity 终端可执行（路径按本机 Unity 安装调整）：
|
||
`"<UnityEditor路径>/Unity" -batchmode -quit -projectPath "D:/UD/AI/AIC#Project/Client" -logFile -`
|
||
- 期望：日志无编译错误；`Library/ScriptAssemblies/XWorld.Framework.Shared.dll` 生成。
|
||
- 若报 `UnityEngine` 相关错误，说明某文件误用了平台 API（应为 0，源码已全部纯 C#）。
|
||
|
||
> 此步无法在本机自动化（需 Unity Editor）。若当前环境无 Unity，则**标注为待人工核对**并继续；.NET 侧 netstandard2.1 编译通过已能高置信度保证 Unity 也能编（API 面同为 netstandard2.1，语言级别同为 C# 9）。
|
||
|
||
- [ ] **Step 4: 提交**
|
||
|
||
```bash
|
||
git add "Client/Assets/Framework/Shared/Framework.Shared.asmdef"
|
||
git commit -m "feat(framework): Unity asmdef for shared layer (noEngineReferences, resident/non-hotupdate)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 9: 更新过时规则文档（收尾）
|
||
|
||
**Files:**
|
||
- Modify: `Doc/Rule/UnityProject.md`（若存在「小游戏用 Lua」条目）
|
||
|
||
对应设计 §10 风险清单：现有「小游戏逻辑用 Lua、不用 C#」规则需更新为 C# 热更路线。
|
||
|
||
- [ ] **Step 1: 查找过时规则**
|
||
|
||
Run: `grep -n -i "lua" "D:/UD/AI/AIC#Project/Doc/Rule/UnityProject.md"`
|
||
Expected: 列出涉及「小游戏用 Lua」的行。若文件不存在或无相关条目，跳过本任务并在提交说明里注明。
|
||
|
||
- [ ] **Step 2: 在该规则处追加更正说明**
|
||
|
||
在相关条目下方插入（保留原文，追加批注，便于追溯）：
|
||
|
||
```markdown
|
||
> ⚠️ 更新（2026-06-18）：小游戏逻辑已切换为 **C# 热更**（客户端 HybridCLR + 服务端 ALC），
|
||
> 弃用 Lua 小游戏路线。详见架构设计
|
||
> `docs/superpowers/specs/2026-06-18-csharp-hotfix-minigame-architecture-design.md`
|
||
> 与共享层实现 `Client/Assets/Framework/Shared/`。
|
||
```
|
||
|
||
- [ ] **Step 3: 提交**
|
||
|
||
```bash
|
||
git add "Doc/Rule/UnityProject.md"
|
||
git commit -m "docs(rule): mark Lua-minigame rule superseded by C# hot-update path"
|
||
```
|
||
|
||
---
|
||
|
||
## 完成判据（Definition of Done）
|
||
|
||
- [ ] `dotnet test Server/Server.sln` 全绿（四个测试类：Packet/Frame/Random/FrameworkMessages 往返与边界全部通过）。
|
||
- [ ] `dotnet build Server/Server.sln` 0 error/0 warning。
|
||
- [ ] 规范源码仅一份（`Client/Assets/Framework/Shared/`），.NET 侧靠 `<Compile Include>` 链接，无任何拷贝（A1 满足）。
|
||
- [ ] 共享层零 `UnityEngine`/`System.IO`/socket 依赖（asmdef `noEngineReferences` + netstandard2.1 双重保证）。
|
||
- [ ] 本程序集未进入 HybridCLR `hotUpdateAssemblies`（常驻不热更）。
|
||
- [ ] §5 全部接口（IGameLogic / IRandom / ITimer / ILogger / IStorage / IGameClient / IGameClientCtx / IGameServerRoom / IRoomCtx）与基础类型（RoomConfig / PlayerInfo / NetMessage / StepResult）均已落地。
|
||
- [ ] 框架协议编解码（PacketWriter/Reader + Frame + 7 个控制消息 + 稳定 opcode）已落地且 DTO↔Frame↔wire 端到端往返通过。
|
||
- [ ] Unity 侧编译核对：通过，或在无 Unity 环境下明确标注为待人工核对。
|
||
|
||
## 不在本子项目范围（交给后续 §9 步骤）
|
||
|
||
- 服务端宿主（Kestrel WS 网关 / Session / 匹配 / RoomHost / ALC 加载器）—— §9 第 2 步。
|
||
- 客户端宿主（扩展 LoadDll 的小游戏 manifest 维度 / HybridCLR 加载小游戏 DLL / 生命周期接管）—— §9 第 3 步。
|
||
- 构建/发布工具链（双编译 + manifest + 签名 + 上传）—— §9 第 4 步。
|
||
- 用 C# 重写 RockPaperScissors —— §9 第 5 步（届时基于本层的 `IGameLogic` 写 RPS.Core）。
|
||
- 任何 `game.json` 解析、签名校验、CDN/版本库 —— 后续子项目。
|