godot-genre-card-game

绝不这样做（专家级反模式）

逻辑与架构

• 绝不要将卡牌逻辑硬编码在 UI 脚本中；必须将游戏效果封装在 Callable 对象或推入 LIFO 栈的命令资源中。
• 绝不要在 _process() 中执行棋盘状态计算（力量／韧性）；必须使用信号驱动的触发器或集中式 EffectStack 解析器。
• 绝不要忘记 LIFO 栈解析；必须使用 Array.push_back() 和 Array.pop_back()，从栈顶到底部依次解析反应。

UX 与动画

• 绝不要在拖放过程中忽略 Z 索引管理；必须在点击时将卡牌置于最前方，防止其滑到其他卡牌下方。
• 绝不要让卡牌在牌堆之间瞬间“传送”；牌堆移动必须使用 create_tween()／tween_property 链（0.2 秒以上）。
• 绝不要对手牌使用 global_position；必须使用 Curve2D 布局，并通过 sample_baked() 实现平滑弧线。

牌组与状态管理

• 绝不要忘记处理牌组为空的情况；必须实现弃牌堆自动洗回牌库，避免软锁。
• 绝不要使用浮点数表示离散的卡牌属性；费用、攻击力和生命值必须使用 int，避免精度漂移。
• 绝不要使用标准 Control 节点来渲染大量 token／战场单位；渲染 100 张以上的卡牌或地图图标时，必须使用 _draw() 自定义绘制，以绕过 SceneTree 开销。
• 绝不要依赖 SceneTree 顺序处理手牌逻辑；必须在 Array 中管理逻辑顺序，并通过 queue_redraw() 更新视觉效果。
• 绝不要在标准 for 循环中删除数组元素；必须反向迭代或使用 filter()，避免索引错误。
• 绝不要忘记在 _init() 中提供无参构造函数；否则 Resource 将无法在 Inspector 中加载。

---

🛠 专家组件（scripts/）

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

1. card_effect_resolution.gd — LIFO 效果栈（push_back／pop_back）
2. card_tween_manager.gd — 可中断的牌堆／手牌 Tween（不使用传送）
3. card_data_resource.gd — Inspector 安全的 Resource 卡牌定义

原创专家模式

• card_effect_resolution.gd - 用于嵌套触发和反制的 LIFO 栈解析器。

模块化组件

• card_data_resource.gd - 数据驱动的卡牌定义，支持基于 Inspector 的设计。
• card_data.gd - 用于验证器／测试的轻量级 CardData Resource 存根。
• deck_shuffle_bag.gd - 用于实现卡牌均匀分布的安全随机化模式。
• turn_state_machine.gd - 通过状态匹配管理固定阶段（抽牌、出牌、战斗）。
• card_drag_drop.gd - 为 Control 节点实现原生 _get_drag_data()。
• board_query_filter.gd - 用于查询棋盘元数据的函数式 filter() 模式。
• card_tween_manager.gd - 管理可中断的卡牌动效与棋盘过渡。
• reactive_card_ui.gd - 由 Resource 信号驱动的 UI，可自动更新视觉状态。
• board_state_dictionary.gd - 与 Node 顺序解耦的基于网格的追踪（Vector2i）。
• match_state_resetter.gd - 清理对局中临时 Resource 修改的模式。
• deck_builder_validator.gd - 用于牌组构建限制和法力曲线的后端逻辑。

---

核心循环

1. 抽牌 → 2. 评估 → 3. 出牌 → 4. 结算（LIFO 栈） → 5. 弃牌／结束

决策树

效果栈

需求	操作
嵌套反应 / 计数器	MANDATORY card_effect_resolution.gd — 仅限 LIFO（pop_back）
仅需 FIFO 顺序动画	少见；单独使用一个队列——不要复用反应栈

手牌与棋盘

需求	操作
弧形手牌布局	Curve2D.sample_baked + card_tween_manager.gd
拖拽目标选择	card_drag_drop.gd
密集棋盘（100+ 个图标）	_draw() / board_state_dictionary.gd — 不要为每个棋子都创建一个 Control

数据

需求	操作
卡牌定义	MANDATORY card_data_resource.gd（无参数的 _init）
牌组 RNG	deck_shuffle_bag.gd
回合阶段	turn_state_machine.gd

技能链

阶段	技能	目的
1. 数据	resources、custom-resources	卡牌属性（费用、类型、效果）
2. UI	control-nodes、layout-containers	手牌布局、工具提示
3. 输入	drag-and-drop、state-machines	目标选择、悬停
4. 逻辑	command-pattern、signals	LIFO 栈、回合阶段
5. 润色	godot-tweening、shaders	抽牌手感、烫金效果

常见陷阱

陷阱	解决方案
在反应栈上使用 FIFO pop_front	在 card_effect_resolution.gd 中使用 LIFO pop_back
牌堆瞬间跳变	通过 card_tween_manager.gd 使用补间动画
ATK/HP 使用浮点数	在 Resources 上使用 int 属性

精英技巧（可选润色）

• 全息烫金效果：在卡牌 Control 上使用 UV 滚动着色器——这不是保证栈正确性的必要条件。
• 卡牌历史：使用信号总线记录器支持重放 / 调试；不要放在热解析路径上。

专家知识（按需查阅）

大模型无知规则： 如果通用 Agent 在阅读之前并不知道某项内容，就加载参考资料——绝不要删除专家补充内容。

• expert-card-patterns.md — 恢复基础教学内容（架构、原因、实现深度）
• card_history_logger.gd
• hand_manager.gd

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；需要切换到相邻领域时再加载相关技能——不要预加载整个技能网络。

官方文档

• 资源 — 将 CardData 作为 .tres 资源，让设计师无需修改 UI 脚本即可编辑费用和属性。
• GDScript 导出变量 — 使用 @export / @export_group 模式，通过检查器编辑卡牌定义。
• Control — 使用 _get_drag_data / _can_drop_data / _drop_data 和 set_drag_preview 实现原生卡牌拖放。
• 自定义 GUI 控件 — 使用 _gui_input、mouse_filter 和 _draw 构建交互式卡牌正面，以适应密集的棋盘布局。
• 尺寸和锚点 — 锚定手牌区和棋盘区，让布局在分辨率变化时保持稳定。
• 使用容器 — 了解何时使用 HBox/Grid 构建卡组构筑网格，何时手动排列弧形手牌。
• Tween — 使用可中断的 create_tween() / tween_property 为抽牌、出牌和弃牌动作增添动感。
• 贝塞尔曲线、曲线和路径 — 了解弧形手牌布局背后的数学原理，而非依赖粗略的圆形近似。
• Curve2D — 使用 sample_baked() 生成平滑的非圆形扇形位置和旋转角度。
• 随机数生成 — 为抽牌堆实现带种子的 RNG 和洗牌袋公平机制。
• 使用信号 — 使用资源的 changed 信号和效果堆栈信号，让 UI 保持响应式，无需通过 _process 轮询。
• 你的第一个 2D 着色器 — 在卡牌正面使用 canvas_item 箔面／稀有度着色器。

相关技能

前置要求

• godot-project-foundations — 在连接 DeckManager 和卡牌场景前，先了解场景树、Autoload 和导入基础知识。
• godot-resource-data-patterns — 了解 .tres 的所有权、复制和 emit_changed，避免对局增益效果泄漏到编写好的卡牌文件中。
• godot-gdscript-mastery — 掌握效果堆栈和回合状态机所用的类型化 Array、Callable／Command 和 match 阶段。
• godot-ui-containers — 掌握手牌区和棋盘命中测试所需的 Control 布局、锚点和 mouse_filter 使用习惯。

补充

• godot-tweening — 终止/并行 Tween 模式，避免快速播放时发生瞬移或堆积失效的 Tween。
• godot-signal-architecture — 用于抽牌、出牌、结算和弃牌的总线/信号图，避免 UI 掌管游戏规则。
• godot-input-handling — 当卡牌与键盘快捷键及无障碍拖动共用视口时，区分指针输入与动作映射。
• godot-turn-system — 该技能的回合状态机所接入的抽牌/主要阶段/战斗/结束阶段归属。
• godot-shaders-basics — 超越该技能入门全息效果代码片段的 canvas_item 稀有度箔片与高亮材质。

下游 / 使用者

• godot-monte-carlo-balancer — 模拟换牌、法力曲线以及胜率与费用/力量的关系，确保卡牌属性在随机数机制下保持平衡。
• godot-genre-roguelike — 使用 CardData、商店和每幕选牌池的逐局牌组构筑游戏。
• godot-inventory-system — 收藏/牌组构筑 UI，将已拥有的卡牌与对局中的牌堆分开保存。
• godot-ability-system — 将关键字/状态效果（中毒、嘲讽、护盾）作为可复用的能力资源，在堆叠中进行结算。

主技能

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。