godot-turn-system

绝对不要做（专家级反模式）

顺序与确定性

• 绝对不要在每个操作后重新计算回合顺序；严格地每轮只排序一次，或仅在与速度相关的属性发生变化时排序，以防止出现 O(n log n) 延迟。

• 绝对不要使用随机方式打破先攻平局；严格使用次级静态属性（敏捷、ID 或持久的“运气”）来实现可确定性重放。

• 绝对不要在遍历回合顺序队列时修改该队列；严格遍历 duplicate() 的副本，或在循环结束后修改队列。

• 绝对不要使用立即执行的 call_group() 广播全局回合状态变化；严格使用 call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...)，以避免通知数百个单位时造成帧卡顿。

• 绝对不要将 Node 层级作为事实来源；严格使用 Dictionary 棋盘状态记录逻辑网格坐标。

逻辑与行动经济

• 绝对不要在验证之前扣除行动点（AP）；严格先调用 can_perform_action(cost)，再执行 current_ap -= cost，以防止漏洞。
• 绝对不要硬编码阶段转换（if phase == 0）；严格使用 enum + match 或专用状态机来管理抽牌、主要和结束阶段。
• 绝对不要在内部清理之前发出“回合结束”信号；严格在通知下一回合之前重置 AP 并处理状态效果。
• 绝对不要使用精确浮点相等判断（==）检查 AP；严格使用 >= 或 is_equal_approx() 进行可靠比较。

战术网格与 UI

• 绝对不要将通用 AStar2D 用于瓦片网格；严格使用 AStarGrid2D，以实现快 10 倍的寻路并原生处理对角线。
• 更改障碍物状态后，绝对不要忘记对 AStarGrid2D 调用 update()；如果切换了 set_point_solid()，则必须先刷新网格，才能进行下一次查询。
• 绝对不要用 while 循环锁住主线程来处理输入；严格使用 await 关键字或信号，让执行让出控制权并返回 Tree。
• 绝对不要使用 is_action_pressed() 处理回合决策；严格使用 is_action_just_pressed() 处理离散且逐帧锁定的菜单输入。
• 绝对不要在联网游戏中跳过回合超时处理；严格实现服务端计时器，并设置默认的“跳过”操作，以防止恶意拖延。请参阅下方的联网回合超时黄金路径。

---

决策树 — 选择回合模型

需求	选择	必需脚本
离散回合（国际象棋 / 战术游戏 / 卡牌阶段）	回合 + 先攻队列 + AP 阶段	turn_system_patterns.gd
连续量表（FF 风格 ATB）	在 _process 中填充每个行动者的量表	active_time_battle.gd
时间线 / CTB，带有打断与预测	事件时间线 + 预测 UI	timeline_turn_manager.gd

不要在代码中另创第四种模型。编码前请先阅读对应脚本。

专家级组件（scripts/）

• turn_system_patterns.gd — 基于 match 的阶段状态机、UndoRedo、AStarGrid2D 棋盘辅助工具。
• active_time_battle.gd — ATB 量表、就绪时暂停、异步操作交接。
• timeline_turn_manager.gd — 带有打断和预演的时间线 / CTB。
• turn_predictor.gd — 模拟 ATB 量表，用于时间线 UI 预览。
• combat_stats_resource.gd — 用于悬停 UI 的确定性伤害预览 Resource。

TurnManager Autoload — 仅包含接口契约

保持 Autoload 精简。不要在此粘贴完整的队列计算逻辑 — 请在上方选定的脚本中实现。

# turn_manager.gd (AutoLoad) — contract only
extends Node
signal turn_started(combatant: Node)
signal turn_ended(combatant: Node)
signal round_ended
signal turn_timed_out(combatant: Node)  # multiplayer: server default-pass

func start_combat(participants: Array[Node]) -> void: pass
func end_turn() -> void: pass
func request_pass(combatant: Node) -> void: pass  # default action on timeout

联网回合超时（标准路径）

引用自 NEVER：时钟由服务端掌控；客户端永远不能决定“跳过”。

1. 收到 turn_started 时，服务端启动一个一次性 Timer / SceneTreeTimer（权威）。
2. 超时后：服务端调用 request_pass(current)（或自动结束回合），然后发出 turn_timed_out。
3. 客户端只负责渲染倒计时；绝不在本地修改回合队列。
4. 与 godot-multiplayer-networking 搭配使用，以支持主机权威 RPC。

行动点（契约）

func can_perform_action(cost: int) -> bool:
    return current_action_points >= cost

func perform_action(cost: int) -> bool:
    if not can_perform_action(cost):
        return false
    current_action_points -= cost
    return true

阶段：优先使用 enum Phase { DRAW, MAIN, END } + match，或转到 godot-state-machine-advanced。完整的 ATB / 时间线运算位于 MANDATORY 脚本中——不要在此处重复 Elite 代码片段。

深度配方（按需查阅）

LLM 忽略规则：如果通用 Agent 在阅读前不会知道某项内容，就将其放在此处或 scripts/ 中——绝不要删除，只能移动。

主题	参考
ATB / 预测 / 预览	elite-turn-patterns.md

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接； 将工作路由给相关领域时加载相关技能——不要预加载整个技能网络。

官方文档

• 空闲和物理处理 — 何时应将回合计时放在 _process、_physics_process 或纯事件步骤中。
• 使用信号 — 无需轮询量表即可处理回合开始 / 回合结束 / 单位行动事件。
• 资源 — 将先攻 / 速度属性作为 Resource，用于模拟和 UI 预测。
• 单例（Autoload） — TurnManager 的所有权边界。
• GDScript 基础知识 — 使用 await 编排多阶段回合。
• Object — 回合总线侦听器的信号连接标志。
• SceneTree — 在菜单处理回合选择时暂停游戏。
• Timer — 无需忙等循环的可选实时回合计时器。
• Tween — 为 ATB 量表和回合交接效果制作动画。
• AnimationPlayer — 必须在下一回合开始前完成的行动动画。
• MultiplayerAPI — 联网对局中的权威回合顺序。
• JSON — 用于平衡测试的确定性回合回放 / 种子日志。

相关技能

前置条件

• godot-project-foundations — TurnManager 的场景和 Autoload 放置位置。
• godot-signal-architecture — 回合总线契约（信号向上，命令向下）。
• godot-resource-data-patterns — 与战斗 / UI 共享的速度 / 先攻 Resource。
• godot-autoload-architecture — 全局回合协调器的生命周期。

补充

• godot-state-machine-advanced — 嵌套在回合阶段下的单位状态。
• godot-combat-system — 在获准的回合内结算行动。
• godot-rpg-stats — 速度/敏捷属性影响 ATB 计量条。
• godot-ability-system — 冷却时间按回合计算，而非仅按实际时间计算。
• godot-tweening — 计量条填充与回合交接的表现效果。
• godot-multiplayer-networking — 由主机负责验证的回合顺序与锁步。

下游 / 使用方

• godot-genre-action-rpg — ARPG/JRPG 类战斗中的 ATB/回合混合机制。
• godot-genre-card-game — 卡牌回合与优先级窗口。
• godot-genre-rts — 策略循环中的离散指令。
• godot-monte-carlo-balancer — 模拟回合矩阵，平衡速度与行动的公平性。

主索引

• godot-master — 用于回合系统的库路由器与镜像模块入口。