Godot 同伴指令轮盘：暂停、选择和反馈要在一秒内完成

同伴指令轮盘常见于动作 RPG：按住肩键，时间放慢，选择同伴技能或战术，松手派发指令。体验好时，玩家能在一秒内完成决策；体验差时，轮盘抢输入、目标选错、时间缩放影响 UI、松手后指令没发出去。

Godot 实现轮盘并不难，Control 画一个圆形菜单即可。难的是它跨越输入、时间系统、AI、目标选择和战斗反馈。指令轮盘不能只是 UI，它需要 CommandWheelController 协调当前上下文：谁可以被命令，哪些指令可用，当前目标是谁，松手时如何确认。

项目里的真实问题

一个同伴战斗系统中，玩家按住手柄肩键打开轮盘，游戏进入慢动作。第一版实现直接设置 Engine.time_scale = 0.2，结果 UI 动画也变慢，长按判定变慢，网络心跳也受影响。另一个问题是玩家选择“集火”时，目标射线仍使用打开轮盘前的准星位置，指令经常发给错误敌人。

这些问题说明指令轮盘需要明确的时间域和目标域。慢动作只应该影响游戏世界，不应该影响 UI 输入和网络。目标选择要在轮盘期间持续更新或锁定，并在确认时再次校验。

设计目标

• 快速唤起：按住输入后立即显示轮盘，默认选项和当前目标清晰。
• 时间隔离：慢动作影响战斗世界，不拖慢 UI、输入和网络。
• 目标可靠：指令确认时目标仍合法，失效时给出 fallback。
• 反馈明确：指令派发成功、失败、冷却、不可用都有即时反馈。

这些目标不是为了把系统做重，而是为了让 Godot 客户端在真实设备、真实网络和真实内容量下仍然可控。很多功能原型只需要一个脚本，但进入发布流程后，必须回答状态从哪里来、失败怎么恢复、UI 如何同步、日志能否说明问题。下面的设计会围绕这些问题展开。

推荐架构

flowchart TD
    A["输入事件/业务意图"] --> B["CommandWheelController"]
    B --> C["输入唤起"]
    B --> D["时间缩放"]
    B --> E["目标选择"]
    B --> F["指令派发"]
    C --> H["状态快照"]
    D --> H
    E --> H
    F --> H
    H --> I["UI反馈和日志"]

图里的每个模块都可以按项目规模合并或拆分。小团队可以用一个 Autoload 承担管理器职责，大项目可以拆成服务、Resource 配置和 UI ViewModel。关键是调用方向要稳定：业务层提交意图，管理器判断状态，执行层接触 Godot 节点、资源或网络，最后统一反馈给 UI 和日志。

关键实现细节

轮盘输入分为按下、保持、方向选择、松手确认、取消。按下后进入 command_mode，暂停普通技能输入，显示轮盘。保持期间根据摇杆方向或鼠标位置更新当前选项。松手时确认，按取消键或方向回中可以取消。
时间缩放不要直接全局修改所有系统。可以用项目已有暂停/时间服务，将战斗物理、动画和 AI 进入慢动作，而 UI、输入、网络和日志使用真实时间。Godot 的 Timer 和 AnimationPlayer 要明确使用 process mode 或自定义 delta。
目标选择可以有两种策略：打开轮盘时锁定当前目标，或轮盘期间持续根据准星更新。哪种更好取决于玩法，但确认时必须校验目标仍存在、可见、可被该指令作用。目标失效时可以转为无目标指令、选择最近合法目标或取消并提示。
指令可用性要提前显示。冷却中、能量不足、同伴倒地、距离过远，都应该让轮盘项变灰并显示原因。不要等玩家松手后才弹失败。

失败处理和恢复路径

轮盘打开时同伴死亡，指令列表要刷新或关闭。继续显示可用技能会误导玩家。
松手确认时如果 UI 焦点被弹窗抢走，应取消指令并恢复输入，不要把旧选择派发出去。
多人或联网项目中，指令派发可能需要服务器确认。客户端可以先播放本地反馈，但最终失败要能回滚或提示。

GDScript 接口草图

class_name CommandWheelController
extends Node

signal state_changed(snapshot: Dictionary)
signal operation_failed(code: String, detail: Dictionary)

var _version := 0
var _snapshot := {}

func submit(intent: Dictionary) -> void:
    _version += 1
    var token := _version
    _snapshot = {"phase": "pending", "intent": intent}
    emit_signal("state_changed", _snapshot)
    _execute(intent, func(result: Dictionary):
        if token != _version:
            return
        if result.get("ok", false):
            _snapshot = result
            emit_signal("state_changed", _snapshot)
        else:
            emit_signal("operation_failed", result.get("code", "unknown"), result)
    )

func current_snapshot() -> Dictionary:
    return _snapshot.duplicate(true)

这段代码只表达接口边界。真实项目里，intent 可以替换成 typed Resource 或明确的 Dictionary schema，_execute 里也要接入超时、取消和错误码。保留 _version 的原因，是客户端经常出现旧异步结果晚于新操作返回的情况。没有版本保护，UI 快速切换、网络重试和资源加载都会把状态改回旧值。

数据契约和协作接口

CommandRequest 包含 companion_id、command_id、target_id、target_position、issued_at、client_context。AI 系统消费请求，轮盘不直接改同伴状态。
时间服务提供 enter_command_slowmo(source_id) 和 exit_command_slowmo(source_id)，支持引用计数，避免多个系统互相恢复时间。
UI 项配置包含 icon、cooldown、cost、requires_target、range、disabled_reason。

分阶段落地

第一阶段实现单同伴、固定指令和本地慢动作。
第二阶段加入目标选择、不可用原因和时间域隔离。
第三阶段接入多同伴、联网确认和可访问性选项。

自动化验证和人工验收

按住轮盘时 UI 动画和输入仍使用真实时间。
目标在轮盘期间死亡或离开范围，确认时有合理 fallback。
冷却中指令显示不可用原因，松手不会派发。
快速打开关闭轮盘不会卡住慢动作。

观测指标

• 轮盘打开时长、取消率和指令确认率。
• 指令失败原因分布。
• 慢动作进入退出不平衡次数。
• 目标确认失败次数。

指标不必一开始就全部上报。开发包可以展示完整调试面板，内测包采样关键字段，正式包只保留错误码和聚合计数。重要的是每个异常都能留下足够证据，团队能判断它是内容问题、网络问题、平台问题还是客户端状态机问题。

上线前检查清单

• 轮盘输入状态和普通战斗输入互斥。
• 慢动作不影响 UI、输入和网络。
• 指令确认时重新校验目标。
• 不可用指令提前显示原因。
• 时间缩放有引用计数和异常恢复。

清单最好能逐步脚本化。不能自动检查的内容，也要明确由谁在什么阶段确认。Godot 项目里的客户端系统经常横跨程序、策划、美术、运营和 QA，如果验收口径只停留在口头，下一次类似问题还会以不同名字回来。

现场演练

现场演练可以让玩家在训练场中打开轮盘，选择集火、跟随、防守、使用技能。测试中途让目标死亡、同伴进入冷却、弹出系统提示。轮盘应能取消或刷新，不应该派发过期指令，也不应该让游戏永久停在慢动作。

案例复盘

指令轮盘的复盘重点通常是时间缩放。直接改 Engine.time_scale 后，UI 动画、输入监听和长按取消都变慢，玩家感觉轮盘迟钝。把慢动作交给 TimeDomainService 后，战斗世界慢下来，UI 仍用真实时间，摇杆选择变得跟手。这个案例说明“暂停世界”和“暂停界面”不是同一件事。

上线后的维护策略

指令轮盘上线后，维护重点是新同伴技能接入。每个技能都要声明是否需要目标、距离、冷却、资源消耗和失败原因。轮盘只负责展示和派发，不应该硬编码某个同伴的特殊规则。

灰度阶段要有回退开关。回退不是把功能粗暴关闭，而是退回更简单但完整的玩家路径：离线队列可以暂停新入队但继续处理已有队列，改键系统可以回到默认档案，地图标记可以关闭聚合但保留任务目标，邮件可以禁用批量领取但保留单封领取。每个系统上线前都应该写清楚“降级后玩家还能做什么”。

责任边界也要明确。谁维护配置，谁看指标，谁处理内容接入，谁判断是否回滚，都要写在系统说明里。Godot 客户端功能经常横跨多个岗位，如果只有实现者知道细节，后续每次活动、版本或平台接入都会重新踩坑。文档不需要很长，但必须包含接入示例、常见错误和验收步骤。

灰度验收脚本

灰度验收应覆盖手柄和键鼠两套输入。按住打开、方向选择、松手确认、取消、目标死亡、同伴倒地、技能冷却、弹窗打断，都要跑一遍。特别要检查慢动作引用计数，任何异常退出都不能让游戏永久慢速或永久锁输入。

验收脚本要同时面向人和机器。机器负责断言状态、错误码、数量和耗时；人负责判断文案是否能理解、视觉反馈是否打扰、操作路径是否顺手。很多客户端系统的失败不是“没有执行”，而是“执行了但玩家不知道发生了什么”。因此每个验收步骤都应该包含预期 UI、预期日志和预期状态快照三部分。

灰度结束后要做一次小复盘。指标是否符合预期，玩家是否使用了降级路径，QA 是否发现难以描述的问题，配置是否需要收紧。复盘结论要回写到检查清单里。这样下一批内容或下一次平台接入时，团队不需要重新摸索同一类边界。

边界补充

指令轮盘还要考虑可访问性。部分玩家不适合长按保持，可以提供点击切换模式：按一次打开轮盘，再按确认执行，按取消关闭。慢动作强度、轮盘停留时间和默认选项也应可配置。这样系统不会只服务反应快的玩家。

交付补充

交付时还要验证“无有效目标”的路径。玩家打开轮盘时如果没有敌人、同伴距离过远或当前目标不可达，轮盘应该提前显示禁用原因。不要让玩家松手后才发现指令失败，这会让指令系统显得不可靠。

最后补充

另外，指令轮盘的默认选项要可配置。不同同伴、不同战斗阶段，默认停在“跟随”“集火”还是“治疗”会影响操作速度。默认值不应写死在 UI 里。

小团队接入版本

小团队可以先不做圆形复杂 UI，用四方向菜单验证输入和指令链路。只要 command_mode、慢动作隔离和目标校验先稳定，后续换成更漂亮的轮盘只是表现层工作。

交付边界

交付标准是玩家能在一秒内唤起、选择、确认或取消指令，并且每个失败都有明确反馈。同伴指令系统的核心不是菜单形状，而是决策过程是否短、准、稳。

结语

同伴指令轮盘是输入、时间和 AI 的交叉点。Godot 项目把轮盘从单纯 UI 提升为控制器后，慢动作、目标选择和指令反馈才能稳定协作。玩家需要的是快速下令，不是和菜单搏斗。