T2FGame.Protocol 1.0.1

T2FGame.Protocol

T2FGame 框架的协议层，提供命令路由定义和 Protobuf 消息协议。

功能特性

• 命令路由系统：类似 ioGame 的 CmdMerge 机制
• Protobuf 支持：高性能二进制序列化
• 命令工具类：路由合并、解析、格式化

安装

<PackageReference Include="T2FGame.Protocol" />

核心概念

命令路由 (CmdMerge)

T2FGame 使用两级命令路由系统：

• Cmd（主命令）：表示功能模块，如用户模块、战斗模块
• SubCmd（子命令）：表示具体操作，如登录、注册

CmdMerge = (Cmd << 16) | SubCmd

命令定义

/// <summary>
/// 命令模块定义
/// </summary>
public static class CmdModule
{
    public const int System = 0;      // 系统模块
    public const int User = 1;        // 用户模块
    public const int Battle = 2;      // 战斗模块
    public const int Room = 3;        // 房间模块
    public const int Chat = 4;        // 聊天模块
}

/// <summary>
/// 用户模块子命令
/// </summary>
public static class UserCmd
{
    public const int Login = 1;       // 登录
    public const int Logout = 2;      // 登出
    public const int GetInfo = 3;     // 获取信息
    public const int UpdateInfo = 4;  // 更新信息
}

核心组件

CmdKit 工具类

// 合并命令
int cmdMerge = CmdKit.Merge(CmdModule.User, UserCmd.Login);
// 结果: 65537 (1 << 16 | 1)

// 解析命令
(int cmd, int subCmd) = CmdKit.Parse(cmdMerge);
// cmd = 1, subCmd = 1

// 获取主命令
int cmd = CmdKit.GetCmd(cmdMerge);

// 获取子命令
int subCmd = CmdKit.GetSubCmd(cmdMerge);

// 格式化为字符串（用于日志）
string str = CmdKit.CmdToString(cmdMerge);
// 结果: "Cmd[1-1]" 或 "User.Login"（如果已注册描述）

命令描述注册

// 注册命令描述（启动时调用一次）
CmdKit.RegisterDescription(CmdModule.User, "User");
CmdKit.RegisterDescription(CmdKit.Merge(CmdModule.User, UserCmd.Login), "User.Login");

// 日志输出时会显示友好名称
_logger.LogInformation("处理命令: {Cmd}", CmdKit.CmdToString(cmdMerge));
// 输出: 处理命令: User.Login

Protobuf 消息

定义 Proto 文件

// user.proto
syntax = "proto3";
package t2fgame.protocol;

option csharp_namespace = "T2FGame.Protocol.Messages";

// 登录请求
message LoginRequest {
    string username = 1;
    string password = 2;
    string device_id = 3;
}

// 登录响应
message LoginResponse {
    int64 user_id = 1;
    string token = 2;
    int64 expire_time = 3;
}

// 用户信息
message UserInfo {
    int64 user_id = 1;
    string nickname = 2;
    int32 level = 3;
    int64 gold = 4;
}

使用生成的消息

// 创建请求
var request = new LoginRequest
{
    Username = "player1",
    Password = "password123",
    DeviceId = "device-001"
};

// 序列化
byte[] data = request.ToByteArray();

// 反序列化
var parsed = LoginRequest.Parser.ParseFrom(data);

项目配置

csproj 配置 Protobuf 编译

<ItemGroup>
  <PackageReference Include="Google.Protobuf" />
  <PackageReference Include="Grpc.Tools" PrivateAssets="All" />
</ItemGroup>

<ItemGroup>
  <Protobuf Include="Protos\**\*.proto" GrpcServices="None" />
</ItemGroup>

目录结构

T2FGame.Protocol/
├── Cmd/
│   ├── CmdKit.cs           # 命令工具类
│   ├── CmdModule.cs        # 命令模块定义
│   └── CmdDescription.cs   # 命令描述管理
├── Protos/
│   ├── common.proto        # 通用消息
│   ├── user.proto          # 用户消息
│   └── room.proto          # 房间消息
└── Messages/               # 生成的 C# 代码（自动生成）

最佳实践

1. 命令编号规划：预留足够的命令空间，避免后期冲突
2. 消息版本兼容：使用 Protobuf 的字段编号，确保向后兼容
3. 命令描述注册：在应用启动时注册所有命令描述，便于调试
4. Proto 文件组织：按模块分文件，保持清晰的结构