星火 2.0 开发文档

主题

GameSystemUI 命令结果面板 ​

GameSystemUI.CmdResultSystemUI 提供一个轻量的客户端提示面板，用于把 CmdResult 的本地化文本显示在屏幕上。它适合显示“不能移动”“目标无效”“资源不足”等命令执行失败原因。

它不是通用 Toast 系统，也不负责创建业务错误。业务逻辑仍应返回或同步 CmdResult，面板只负责把结果展示给玩家。

常用命名空间：

csharp
#if CLIENT
using GameCore.BaseType;
using GameSystemUI.CmdResultSystemUI;
#endif

推荐入口 ​

类型作用推荐用法
CmdResultManager.ShowCmdResult(CmdResult)显示一条命令结果项目代码显示失败原因时调用
CmdResultManager.CmdResultPanel全局面板实例只在确实需要直接访问面板时使用
CmdResultPanel.Time自动隐藏延迟，单位毫秒当前不建议作为运行期配置入口依赖
CmdResultPanel.CmdResult当前显示结果通常不用直接赋值，走 Manager

CmdResultPanel 会在客户端 EventGameStart 时创建并加入可视树。不要在 GameStart 之前访问 CmdResultManager.CmdResultPanel。

显示命令失败 ​

CmdError 可以隐式转成 CmdResult。如果只是显示内置失败原因，可以直接传入：

csharp
#if CLIENT
CmdResultManager.ShowCmdResult(CmdError.CannotMove);
CmdResultManager.ShowCmdResult(CmdError.NotEnoughResource);
#endif

项目自己的命令或交互函数如果返回 CmdResult，推荐只在失败时显示：

csharp
#if CLIENT
private static void TryUseLocalAction()
{
    CmdResult result = ValidateLocalAction();
    if (!result)
    {
        CmdResultManager.ShowCmdResult(result);
        return;
    }

    SendActionRequestToServer();
}
#endif

CmdResultPanel 显示的是 CmdResult.LocalizedString。如果某个自定义错误没有本地化文本，优先补 CmdError / CmdResult 的本地化配置，而不是把普通字符串硬塞进面板。

和服务端结果配合 ​

服务端不能直接操作客户端 UI。服务端校验失败时，应把 CmdResult 或等价错误码通过项目已有通信方式发给客户端，再由客户端调用 ShowCmdResult。

csharp
// 服务端示意：执行前做权威校验。
CmdResult result = ValidateUseCard(player, cardId, target);
if (!result)
{
    SendUseCardFailedMessage(player, result);
    return;
}
csharp
#if CLIENT
// 客户端收到失败消息后显示。
private static void OnUseCardFailed(CmdResult result)
{
    CmdResultManager.ShowCmdResult(result);
}
#endif

通信方式可根据项目复杂度选择 双端事件系统、类型化消息系统 或更底层的 消息传递系统。

显示时间与样式 ​

内置面板默认约 3000 毫秒后自动隐藏。虽然 CmdResultPanel 暴露了 Time 属性，但当前实现更适合使用默认值；不要把它当成成熟的运行期 Toast 配置系统。

如果不同类型提示需要不同样式、不同持续时间、排队、图标或按钮，建议自建项目自己的 Toast/通知 UI。CmdResultPanel 保持用于短文本命令失败原因即可。

适合与不适合 ​

适合：

  • 显示框架命令失败原因。
  • 显示服务端校验失败后同步回客户端的 CmdResult。
  • 在开发期快速确认某个交互为什么失败。

不适合：

  • 长文本公告、奖励弹窗、任务提示。
  • 带按钮、图标、队列、分类的复杂通知。
  • 每帧或高频刷新的状态展示。

常见问题 ​

现象常见原因处理
调用时报空引用在 GameStart 之前访问了 CmdResultPanel延后到客户端 GameStart / HUD 初始化之后
面板没有显示传入的是成功结果，或结果本地化为空只显示失败结果，检查 LocalizedString
提示文字太快消失内置面板是轻量固定提示需要不同持续时间时，自建 Toast/通知 UI
服务端失败客户端没提示失败结果没有同步到客户端通过双端事件或类型化消息把结果发回客户端
同一提示刷屏在循环或 Think 中反复调用加冷却或只在状态变化时显示