godot-game-loop-harvest

脚本目录（按路径必读）

路径	必读内容
命中 / 采集	harvestable_node.gd、resource_data.gd、harvest_tool_data.gd
离线 / 自动保存	harvest_loop_patterns.gd、harvest_autosave_manager.gd、harvest_inventory_manager.gd
矿脉 / 重生 / 世界	harvest_respawn_manager.gd + 下方的 FastNoiseLite 矿脉说明

设置（简要）

1. 创建 HarvestResourceData / HarvestToolData .tres（工具 枚举 + 等级、产出范围、可选的掉落场景）。
2. 将 harvestable_node.gd 附加到 StaticBody3D；指定数据和 mesh_to_shake；交互保持在 Layer 1。
3. 需要持久化世界状态时，将 harvest_respawn_manager.gd 自动加载为 HarvestRespawnManager。

命中流程

射线检测 / 交互 → apply_hit(tool_data: HarvestToolData)：

if collider is HarvestableNode:
    collider.apply_hit(player_tool)

信号	载荷	连接到
harvested	(data, amount)	库存 / harvest_inventory_manager
took_damage	(curr, max)	HUD 血条 / 弹出提示池
interaction_failed	(reason: StringName)	"wrong_tool" / "low_tier" 反馈

绝对不要做

• 绝不要用浮点数累加采集数量 — 使用 int。
• 绝不要在 _process 中不使用 delta 计算采集速率 — 这会使经济系统受帧率影响。
• 绝不要依赖 OS.get_ticks_msec() 计算离线进度 — 使用 Time.get_unix_time_from_system()。
• 绝不要通过自由格式字符串检查工具类型 — 使用 HarvestToolData.ToolType / StringName 枚举（见脚本）。
• 绝不要修改共享的 Resource 模板 — 在运行时修改耐久度 / 生命值前，先执行 duplicate(true)。
• 绝不要在 VFX / SFX 播放完毕前调用 queue_free() — 隐藏网格、切换碰撞层，并在特效播放完毕后释放。
• 绝不要在退出时跳过 UNIX 时间戳保存 — 离线收益依赖该时间戳。
• 绝不要将采集逻辑与 UI 计数器耦合 — 只使用信号。
• 绝不要对碰撞形状进行非均匀缩放 — 修改形状资源的尺寸。

矿脉程序化生成（噪声）

使用 FastNoiseLite 阈值生成自然分布的矿簇；在 noise.get_noise_2dv(pos) > threshold 的位置生成 HarvestableNode 实例。通过重生管理器持久化已耗尽矿脉的 ID — 加载时不要在没有种子的情况下重新生成矿脉。

工具耐久度

将耐久度保存在 HarvestToolData（Resource）中，而不是玩家节点中。成功命中后，从工具 Resource 发出耐久度 / 损坏信号。

离线 UNIX 运算、工作线程批处理、弹出提示池和矿脉程序化生成深入内容为必读：harvest-elite-patterns.md。当命中流程 + 重生管理器已足够时，不要加载。

参考

渐进式披露： 只浏览你正在实现的 API 的官方文档（Resources、StaticBody3D 命中、信号、计时器、保存 / 离线时间）。连接库存、自动加载、射线检测或经济平衡时，再打开相关 Skills — 不要预先加载整个知识网络。

官方文档

• 资源 — 将 HarvestResourceData / HarvestToolData 编写为可共享的 .tres 资源，让设计师无需编辑采集脚本即可调整生命值、产出范围和工具门槛。
• Resource — 修改运行时的采集/工具状态前调用 duplicate(true)，避免某个节点的资源耗尽或耐久度变化改写共享的 Resource 模板。
• GDScript 导出变量 — @export / @export_group 支持在采集数据 Resource 上通过 Inspector 配置工具等级、产出范围、重生时间和掉落场景。
• 使用信号 — 发出 harvested、took_damage 和 interaction_failed 信号，让物品栏、HUD 进度条和反馈 UI 无需耦合 HarvestableNode 的内部实现即可订阅。
• StaticBody3D — 世界中的可采集对象是玩家会查询/击打的静态碰撞体；将它们放在交互层上，并在资源耗尽时移至非活动层。
• 碰撞形状（3D） — 直接调整形状资源的尺寸；碰撞形状的非均匀缩放会导致镐/斧对树木和矿石节点的命中检测出错。
• 空闲处理与物理处理 — 连续采集速率乘以 delta（经济系统的固定步长计时优先使用 _physics_process），确保采集速度不受帧率影响。
• Time — 离线收益应持久化 Time.get_unix_time_from_system()；不要使用 OS.get_ticks_msec() / 运行时长计算现实中的离开时间。
• 保存游戏 — 将物品数量、资源耗尽节点 ID，以及绝对重生/离线时间戳与其余进度数据一并持久化。
• FileAccess — 定时自动保存通过 FileAccess.open 将 JSON（或二进制）写入 user://，确保采集进度在手动保存之间发生崩溃时也能保留。
• Tween — 受击反馈抖动使用网格子节点的短时属性补间，无需为每次打击创建临时动画播放器。
• 单例（Autoload） — 将 HarvestRespawnManager 注册为 Autoload，让分散在各处的可采集对象通过 /root/HarvestRespawnManager 处理全世界范围的资源耗尽状态持久化。

相关技能

前置条件

• godot-resource-data-patterns — 采集产出、工具属性和掉落场景以 Resource 为先；在将经济数值写入节点前，先确定组合/复制规则。
• godot-signal-architecture — 明确 harvested / inventory_updated 的归属并安全连接信号，让采集节点与 HUD 和物品栏中心解耦。
• godot-physics-3d — StaticBody3D 的层/掩码和可交互世界道具的形状设置，是可靠命中验证的前提。
• godot-gdscript-mastery — 类型化 Resource、对 create_timer 使用 await，以及 Mutex / WorkerThreadPool 模式都以扎实的 GDScript 基础为前提。

补充技能

• godot-inventory-system — 将 harvested 接入实际的物品栏／堆叠流程，而不是只把数量留在采集专用字典中。
• godot-save-load-systems — 将仓库总量、工具耐久度和资源节点耗尽计时器纳入项目存档架构，实现完整的往返读写，而不只是定期导出 JSON。
• godot-autoload-architecture — 重生和物品栏管理器应纳入规范的 Autoload 图，明确初始化顺序和信号总线边界。
• godot-raycasting-queries — 玩家采集输入通常会先进行射线或形状投射，命中可采集碰撞体后再调用 apply_hit(tool_data)。
• godot-tweening — 将受击抖动扩展为润色动画（挤压、闪光、镜头冲击），避免过早调用 queue_free() 截断视觉特效。
• godot-economy-system — 将采集产出接入消耗点、制作成本和商贩循环，让采集融入连贯的经济系统。

下游／使用方

• godot-monte-carlo-balancer — 将产出、重生时间和工具等级设为可调的 Resources 后，可通过蒙特卡洛模拟验证采集节奏和消耗压力，再确定最终曲线。
• godot-genre-survival — 生存循环会在此采集核心的基础上，将采集与饥饿、制作和世界威胁系统结合起来。
• godot-game-loop-collection — 收集／拾荒目标通常会使用相同的采集／物品栏信号来完成“收集 N 个 X”任务。
• godot-procedural-generation — 交互循环稳定后，可基于采集节点数据构建噪声驱动的资源矿脉和世界布局。

主技能

• godot-master — 技能库路由器和镜像模块入口；用于发现同级技能，或在编辑 Domain Skill 后同步共享脚本镜像。