GM 指令框架 · 使用说明

〇它是干什么的（一句话）

一行代码注册一条 GM 指令；在编辑器面板里边打边联想、回车执行，成功/失败与耗时直接回显。

// 一行一条：名字里的 / 会自动长成分组树
RevGM.Register("经济/加金币", "给当前玩家加金币", args => AddGold(args.Int(0, 1000)),
               RevGMArg.Int("数量", 1000));

面板长这样（示意）

┌────────────────────────────────────────────────────────────────────────────┐
│ ● Play 中（可执行）  命令 42 条                        [命令来源][刷新][帮助] │
│ 命令 [加金____________________________] [清空] [执行 (Enter)]               │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ 经济/加金币          <数量>  给当前玩家加金币   ← 命中字高亮、↑↓ 选择 │ │
│ │ 经济/清空金币                    把金币清零                            │ │
│ │ 战斗/清空全场敌人  ⚠             高危：执行前二次确认                    │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ ┌── 分组树 ──────────┐ ┌── 详情 ─────────────────────────────────────────┐ │
│ │ ▼ 经济 (2)         │ │ 经济/加金币                                     │ │
│ │   加金币           │ │ 给当前玩家加金币                                │ │
│ │   清空金币         │ │ 参数：· 数量|整数(默认 1000)                    │ │
│ │ ▼ 战斗 (1)         │ │ [填入输入框] [复制命令名] [执行]                 │ │
│ └────────────────────┘ └─────────────────────────────────────────────────┘ │
│ ✔ 执行成功（1.20 ms）  经济/加金币 500 → 金币 = 1500                         │
│ 历史（点一条重新填入） 12:31:07 ✔ 经济/加金币 500                            │
└────────────────────────────────────────────────────────────────────────────┘

一3 分钟跑起来（可粘贴）

三步：写注册入口 → 启动时调一次 → 面板里执行。

using Revolution;

public static class MyGameCommands
{
    private static int _gold;

    [RevGMEntry("战斗 / 经济 相关")]     // ← 想让面板在"不进 Play"时也能列出命令，就加它
    public static void Register()
    {
        // ★ 一行注册：名字 / 说明 / 干什么 / 参数说明
        RevGM.Register("经济/加金币", "给当前玩家加金币",
                       args => { _gold += args.Int(0, 1000); return $"金币 = {_gold}"; },
                       RevGMArg.Int("数量", 1000));
    }
}

// 你的启动流程里（游戏入口 / 场景 Boot / 或一个 [RuntimeInitializeOnLoadMethod]）：
MyGameCommands.Register();

也可以不用面板（游戏内控制台 / 自动化 / 单测）

RevGMResult r = RevGM.Execute("经济/加金币 500");
if (!r.Success) Debug.LogError(r.Message);      // Message 是人话，直接能看

二面板怎么用（4 步 + 键位表）

整个过程可以只用键盘完成。

两种模式（很重要）

三一行注册的六种形态（挑一种用）

都是"一行"，区别只在写不写参数说明、要不要回显、要不要标记。

// ① 最简单：无参数、无返回值（框架自动替你回 done）
RevGM.Register("经济/清空金币", "把金币清零", args => _gold = 0);

// ② 要回显一句话：返回 string 就是面板上那行结果
RevGM.Register("工具/概览", "打印当前状态", args => $"金币={_gold}");

// ③ 带参数说明（推荐）：面板显示帮助 + 执行前自动校验
RevGM.Register("战斗/缩放主角", "把主控英雄缩放成指定倍数",
               args => { _scale = args.Float(0); return $"缩放 = {_scale}"; },
               RevGMArg.Float("倍率", 1f));

// ④ 高危：面板执行前二次确认（Ctrl+Enter 跳过）
RevGM.Register("战斗/清空全场敌人", "把所有敌人血量清零", args => ClearEnemy(),
               RevGMFlags.HighRisk);

// ⑤ 隐藏：不进联想列表，但直接写完整名仍可执行（临时/废弃命令）
RevGM.Register("工具/内部复位", "把演示状态复位", args => Reset(), RevGMFlags.Hidden);

// ⑥ 逻辑复杂就别写大 lambda：把方法直接传进来（方法组）
RevGM.Register("聊天/发消息", "往指定频道发消息", SendChatMessage,
               RevGMArg.Enum("频道", "lobby", "guild", "customteam"), RevGMArg.Str("内容", ""));

private static string SendChatMessage(RevGMArgs args)
    => $"已发送到 {args.Str(0)}：{args.Str(1, "（空）")}";

lambda 支持情况（已逐条实测）

四参数怎么写（新手最容易含糊的地方）

两步：声明参数说明（给人看 + 给框架校验）+ 用 args 取参数（不自己解析字符串）。

4.1 声明参数说明：RevGMArg

4.2 取参数：args（永远不要自己解析字符串）

args.Count          // 参数个数
args.Has(1)         // 第 2 个参数有没有传
args.Raw(0)         // 原始字符串
args.Text           // 参数整体（原样拼回一行）
args.Str(0, "默认")   // 文本
args.Int(0, 1000)   // 整数（解析失败 → 抛一句人话）
args.Float(0, 1f)   // 小数
args.Bool(0, true)  // 开关
args.Enum<ChatChannel>(0, ChatChannel.Lobby)   // 枚举

4.3 框架会执行前先校验一遍（只要有参数说明）

所以下面这些错误在业务代码跑之前就被拦下并回显，不用等到业务里爆异常：

4.4 带空格的参数要用引号

工具/回显 "你好 世界" 第二段    // 第 1 个参数是「你好 世界」，第 2 个是「第二段」

五命令体怎么写得"有话说"（最容易踩的坑）

三条规则：成功回一句话；业务不行抛 RevGMUsageException；真 bug 交给框架。

5.1 成功：返回一句话（或什么都不返回）

RevGM.Register("经济/加金币", "给当前玩家加金币", args =>
{
    AddGold(args.Int(0, 1000));
    return "已发放";           // ← 面板上显示这句话；返回 null 也没问题（显示 done）
});

5.2 "业务上说不行" → 抛 RevGMUsageException

RevGM.Register("工具/领取每日奖励", "领取今天的奖励", args =>
{
    if (AlreadyClaimedToday) throw new RevGMUsageException("今天已经领过了");   // 原样显示在面板
    Claim();
    return "领取成功";
});

5.3 真 bug（自己写错了）→ 什么都别做，让框架兜

RevGM.Register("工具/会崩的命令", "演示异常", args => throw new InvalidOperationException("故意崩一下"));
// 面板显示：执行「工具/会崩的命令」时抛异常：InvalidOperationException: 故意崩一下
//            at 你的堆栈首行...

六"我要做 X" 对照表（背下就会用）

左边是你脑子里的需求，右边是可以直接抄的代码。

七八个最容易白干的坑

每一条都有对应报错，看到就知道怎么改。

八完整实战：把 GM 指令接上服务定位器

真实项目里，GM 命令不该自己 new 业务系统，而是从服务定位器里取 —— 两者是天然搭配。

public static class GameBoot
{
    // 服务定位器那份文档里说过：真要"全局入口"，就自己在启动代码里放一个 static readonly 字段
    public static readonly RevServiceLocator Services = RevServiceLocator.Create()
        .AddSingleton<IPlayerService, PlayerService>()
        .AddSingleton<IBattleService, BattleService>()
        .Build();

    [RuntimeInitializeOnLoadMethod]          // 或者你的游戏入口
    public static void Boot()
    {
        GameCommands.Register();             // 注册 GM 指令（正式包不调这一行 = 不存在）
    }
}

public static class GameCommands
{
    [RevGMEntry("局内：经济 / 战斗")]
    public static void Register()
    {
        RevGM.Register("经济/加金币", "给当前玩家加金币（不填默认 1000）",
            args =>
            {
                var player = GameBoot.Services.GetRequired<IPlayerService>();   // ← 运行时取服务
                int amount = args.Int(0, 1000);
                player.AddGold(amount);
                return $"金币 = {player.Gold}";
            },
            RevGMArg.Int("数量", 1000));

        RevGM.Register("战斗/秒杀当前目标", "把当前选中目标血量清零",
            args =>
            {
                var battle = GameBoot.Services.Get<IBattleService>();     // 可选能力：没进战斗就是 null
                if (battle == null) throw new RevGMUsageException("当前不在战斗中");
                if (!battle.HasTarget) throw new RevGMUsageException("没有选中目标");
                battle.KillTarget();
                return "已秒杀";
            },
            RevGMFlags.HighRisk);        // ← 高危：面板会二次确认
    }
}

九正式包策略（怎么保证它不上线）

本框架没有用编译宏裁剪，而是用更硬的一条：没人在启动期注册 = 不存在。

// 真码里是这种矩阵，还要靠人工纪律
//#define ENABLE_CHEAT_COMMANDS
#if ENABLE_CHEAT_COMMANDS && ENABLE_AITEST ...
// 结果：89% 的命令处于注释死代码状态

// 正式包不调这一行，就什么都不存在
MyGameCommands.Register();
// 需要临时关：RevGM.Enabled = false

十一页速查卡（可打印）

贴在显示器旁边，写指令时不用回来翻文档。

十一与参考实现的对照 + 已知边界

完整 12 条精华 + 16 条糟粕（每条带出处）在代码目录的 README 第四节。

已知边界（诚实清单）

• 联想是"字符级"匹配：中文命令请打中文子串（加金 → 经济/加金币）；拼音首字母缩写（如 jjb）不支持（需要一张拼音表，不在轻量范围内）。英文名命令支持缩写（agi → Battle/AddGoldInstant）。
• 编辑模式不执行命令：避免"命令体碰了运行时对象、在编辑器里直接崩"。
• 不做客户端权限伪造：HighRisk = 提醒 + 二次确认，真权限留给服务端。
• 命令名不能有空格（空格是命令与参数的分隔符），分组用 /；也不能只有分隔符（/、/// 会在注册时直接报错 —— 名字归一化后为空，放进去会变成一条联想不到、也删不掉的空名命令）。
• 面板不记录跨会话历史（只在当前编辑器会话内保留最近 50 条）。

十二文件都在哪（你只需要读两个）

运行时：Assets\Revolution\Runtime\RevGMCommand\　编辑器：Assets\Revolution\Editor\RevGMCommand\