godot-genre-fighting

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

帧数据与逻辑

• 绝不要使用可变帧率；必须将逻辑严格锁定在确定性固定循环中（使用带帧计数器的 _physics_process），并在传送时调用 reset_physics_interpolation()。
• 绝不要使用标准物理系统进行命中检测；必须使用 PhysicsDirectSpaceState.intersect_shape() 即时查询碰撞箱，避免 Area2D 信号延迟。
• 绝不要跳过伤害缩放；必须在连击中每次命中后降低 10% 伤害，以防止出现无限连击。
• 绝不要让所有招式在防御后都没有破绽；必须确保高收益招式有恢复窗口，让攻击者可以被反击。
• 绝不要依赖 Area2D.get_overlapping_areas()；必须使用 intersect_shape() 实现即时、精确到帧的判定。
• 绝不要忽略碰撞箱接近判定（接近防御）；即使碰撞箱尚未命中，只要进入附近区域，也必须触发防御状态。

角色与动画

• 绝不要通过简单地设置父节点（scale.x = -1）来翻转角色；必须调整专用的Visuals 节点，并以编程方式管理碰撞箱偏移。
• 绝不要使用基于字符串的动画触发；必须使用 AnimationMixer 和 ADVANCE_MANUAL 实现帧同步播放。
• 绝不要在帧关键逻辑中使用 yield 或 await；必须在状态机中使用整数帧计数，精确管理恢复和起手窗口。
• 绝不要将帧数据存储在原始脚本中；必须使用 Resource 文件（.tres），并委托逻辑处理伤害缩放、取消和连击状态追踪。
• 绝不要为角色部件使用深层节点层级；必须保持骨骼结构扁平，以减少变换开销。

输入与网络

• 绝不要跳过输入缓冲；必须实现 5-10 帧的缓冲，确保玩家操作宽容、响应灵敏。
• 绝不要让 Input.use_accumulated_input 保持启用；必须将其禁用，以保留子帧时序，实现精确的连击衔接。
• 绝不要在网络对战中使用客户端命中检测；必须使用回滚网络代码或服务端验证，防止不同步。
• 绝不要在多人游戏中使用标准 TCP；必须使用 UDP/ENet，避免延迟突增时发生队头阻塞。
• 绝不要依赖 SceneTree 处理网络对战中的格斗角色变换；必须在可序列化数据缓冲区中管理位置。

---

🛠 专家组件（scripts/）

实现对应系统前必须阅读：

1. fighting_input_buffer.gd — 缓冲 + 动作输入（QCF/DP）
2. direct_hitbox_query.gd — 唯一命中判定路径（intersect_shape）
3. rollback_state_serializer.gd — 用于网络对战的快照/恢复

原创专家模式

• fighting_input_buffer.gd - 帧锁定输入引擎（60fps），支持动作指令模糊匹配（QCF/DP）。
• hitbox_component.gd - 碰撞箱/受击箱体积辅助工具（High/Low/Throw 层）— 使用 direct_hitbox_query 判定命中，而非 Area 信号。

模块化组件

• deterministic_physics_loop.gd - 用于逐帧精确推进游戏状态的自定义循环模式。
• direct_hitbox_query.gd - 使用 PhysicsServer 进行形状投射，即时解决碰撞。
• hit_stop_controller.gd - 动态调整时间缩放，营造“打击感”。
• manual_animation_advancer.gd - 通过手动处理 delta 实现与帧同步的动画控制。
• rollback_state_serializer.gd - 用于管理离散游戏状态快照的序列化逻辑。
• bitwise_state_flags.gd - 用于跟踪格斗角色状态的高性能位标志。
• input_accumulation_control.gd - 用于禁用 Godot 输入累积、实现子帧计时的开关。
• raw_byte_network_sync.gd - 基于 UDP 的状态同步，提升网络对战效率。
• string_name_optimization.gd - 在 AI 状态中使用指针级 StringName 比较的模式。
• round_timer_logic.gd - 用于帧同步对局计时器和超时触发的逻辑。

从基线恢复（按需加载）

• attack_resource.gd - .tres 帧数据 Resource（前摇/有效帧/后摇、帧数优势）。
• combo_tracker.gd - 伤害缩放（每击约 10%）和连击状态。
• fighter_state_machine.gd - IDLE/ATTACKING/HITSTUN 状态，使用整数 state_frame。
• fight_game_state.gd - 可序列化的回滚快照框架（与 rollback_state_serializer.gd 配合使用）。
• move_set_loader.gd - 用于设计师迭代的 JSON 招式列表加载器。
• frame_advancer.gd - 用于调整碰撞箱位置的 @tool 编辑器帧擦洗工具。
• fighter_balance_profile.gd - 按角色阵容分别设置伤害/移动/防御缩放的 Resource。

---

核心循环

Neutral → Confirm Hit → Combo → Advantage → Repeat

决策树（无 Area2D / 内联系统转储）

帧与固定循环

需求	操作
攻击时序 Resource	使用包含前摇/有效帧/后摇/帧数优势的 .tres，而非脚本常量
60fps 模拟步进	deterministic_physics_loop.gd
动画与帧同步	manual_animation_advancer.gd（ADVANCE_MANUAL）

输入

需求	操作
5–10f 输入缓冲 + QCF/DP	必须使用 fighting_input_buffer.gd
子帧连段	input_accumulation_control.gd — 禁用输入累积

碰撞箱

需求	操作
逐帧精确命中	必须且只能使用 direct_hitbox_query.gd
碰撞体积编辑辅助工具	使用 hitbox_component.gd 设置形状/层级 — 绝不可使用 area_entered / get_overlapping_areas 进行判定
近身防御	在有效帧生效前查询扩展后的形状

连击 / 取消

需求	操作
伤害缩放，每击约 10%	在连击状态中跟踪；将取消层级存储在 Attack Resource 上
状态	IDLE/ATTACKING/HITSTUN/BLOCKSTUN…，使用整数 state_frame — 参阅 godot-state-machine-advanced

网络同步

需求	操作
状态快照	MANDATORY rollback_state_serializer.gd
传输	通过 raw_byte_network_sync.gd 使用 UDP/ENet；对等领域 godot-multiplayer-networking

---

平衡指南

元素	指南
生命值	约 20 秒的回合中设为 10,000-15,000
连招伤害	每次命中造成的伤害最多为生命值的 30-40%
最快招式	起手 3-5 帧（轻拳）
最慢招式	20-40 帧（超必杀技、头顶攻击）
投技距离	较短，但可靠
能量槽增长	受到约 2 次连招即可充满

进行角色阵容 / 对战模拟时，请使用 godot-monte-carlo-balancer。

常见问题

问题	解决方案
无限连招	命中硬直衰减 + 重力缩放
Area2D 信号命中	替换为 direct_hitbox_query.gd
延迟导致输入丢失	缓冲 8 帧以上
不同步	确定性循环 + 回滚序列化器

专家知识（按需加载）

LLM 知识盲区规则： 如果通用 Agent 在阅读前不会了解某项知识，就加载参考资料——绝不要删除专家补充内容。

• expert-fighting-patterns.md — 恢复的基线教学内容（架构、原因、实现深度）
• attack_resource.gd
• combo_tracker.gd
• fighter_state_machine.gd
• fight_game_state.gd
• move_set_loader.gd
• frame_advancer.gd
• fighter_balance_profile.gd

参考资料

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

官方文档

• 空闲处理和物理处理 — 战斗逻辑必须在固定物理帧（或自定义帧计数器）上运行，而不能使用可变的 _process 时间增量。
• 输入 — 禁用 use_accumulated_input，并逐帧采样动作，确保输入缓冲和动作窗口保持确定性。
• 输入示例 — 输入动作映射和事件处理模式，为 5–10 帧缓冲和动作识别提供支持。
• 控制器、游戏手柄和操纵杆 — 摇杆死区和数字方向阈值，确保 QCF/DP 方向历史记录准确。
• 使用 Area2D — 攻击框／受击框体积、monitoring 与 monitorable，以及为何信号延迟通常会导致无法及时处理逐帧判定的同时命中。
• 物理简介 — 使用碰撞层／遮罩过滤上段／下段／投掷，而不是在高频路径中使用字符串组。
• PhysicsDirectSpaceState2D — 通过即时 intersect_shape 处理命中，无需等待 Area2D 重叠信号。
• PhysicsShapeQueryParameters2D — 形状查询设置（遮罩、排除对象、collide_with_areas），用于直接检查攻击框。
• AnimationMixer — 使用 ADVANCE_MANUAL／回调模式，使攻击动画片段与整数帧数据同步推进。
• 资源 — 将起手帧／有效帧／恢复帧、连招取消和平衡配置存储为 .tres 数据，而不是硬编码为脚本常量。
• 高级多人游戏 — 在确定性格斗模拟中添加网络对战时使用的权限、RPC 和对等端角色。
• ENetMultiplayerPeer — 使用 UDP/ENet 传输交换输入，便于回滚，且不会受到 TCP 队头阻塞的影响。

相关技能

前置条件

• godot-project-foundations — 必须先锁定物理帧率、输入映射和项目默认设置，帧数据系统才能保持确定性。
• godot-input-handling — 在动作指令和连招取消中处理动作采样、设备映射和适配输入缓冲的输入管线。
• godot-2d-physics — 碰撞层／遮罩和直接空间查询构成了攻击框／受击框判定的基础，可避免 Area 信号延迟。
• godot-characterbody-2d — 即使不涉及纯命中检测，格斗角色仍需要接地移动、朝向，以及传送／reset_physics_interpolation 约定。

补充

• godot-combat-system — 通用的 DamageData / 命中确认模式，格斗帧数据可在此基础上细化为前摇、判定和恢复窗口。
• godot-animation-player — 通过动画驱动的碰撞箱启用轨道、取消帧和恢复锁定，而非使用自由运行的计时器。
• godot-state-machine-advanced — 使用整数 state_frame 计数器实现 IDLE/ATTACKING/HITSTUN/BLOCKSTUN 有限状态机，而非基于 await 的恢复机制。
• godot-resource-data-patterns — 招式列表、取消表和 FighterBalanceProfile 资源，并支持为每个格斗角色实例安全地创建副本。
• godot-signal-architecture — 通过命中确认、回合结束和 HUD 事件，避免模拟循环与表现层节点耦合。
• godot-multiplayer-networking — 回滚或延迟输入网络代码中的对等端同步、RPC 规范和权威验证。
• godot-adapt-single-to-multiplayer — 将本地格斗角色改造为支持网络对战时的预测、协调和大厅／迟到加入模式。

下游／使用方

• godot-monte-carlo-balancer — 在整个角色阵容中模拟对战矩阵、伤害缩放和惩罚窗口，而不是根据 AFK→职业 PvE 档位进行猜测。

主入口

• godot-master — 用于发现格斗相关技能并同步共享脚本镜像的库路由器和镜像模块入口。