godot-game-loop-collection

永远不要做的事（收集系统的常见陷阱）

• 绝不要重复使用或省略稳定的可收集物品 ID——重复的 ID 会导致计数翻倍或覆盖；缺少 ID 会破坏完成度百分比和存档。
• 绝不要对同一个区域重叠重复计数——重新进入时，body_entered 可能会再次触发；应通过“已收集”标记或一次性禁用监测来设防。
• 绝不要将 NodePath 作为可收集物品的身份标识持久化——场景移动后路径会失效；应保存 ID（StringName / int），而不是 get_path()。
• 绝不要让最后一件物品变得无法收集——如果罗盘 / 生成逻辑依赖“剩余数量 > 1”，最后一个拾取物就会变得无法找到。
• 绝不要只在场景局部节点中存储搜寻进度——关卡重新加载会清除进度；应将已收集集合保存在 collection_manager.gd 中并进行存档。
• 绝不要在没有实际效果且未提交 ID 时对可收集物品调用 queue_free()——先提交 ID（发送信号），再播放 VFX，最后释放。
• 绝不要对可收集物品的碰撞形状进行非等比缩放——这会破坏重叠计算；应编辑形状资源。
• 绝不要在代码中硬编码生成位置——应将 Marker3D / 设计师放置点与 hidden_item_spawner.gd 配合使用。
• 绝不要通过 UI 剪影来判定收集状态——档案 UI 应镜像管理器状态；管理器才是权威来源。
• 绝不要在搜寻完成时同步加载大型关卡——使用线程化 ResourceLoader（见参考资料）。
• 绝不要从工作线程操作 SceneTree——只能使用 call_deferred。

---

标准流程（必须遵循）

1. collectible_item.gd — item_id（唯一）+ collection_id（搜寻任务），使用一次性 Area 拾取
2. collection_manager.gd — 通过 register_item() + get_remaining_ids() 管理权威的已收集 ID 集合
3. collection_compass.gd — 寻找 item_id 仍在管理器剩余列表中的最近节点
4. 通过 godot-save-load-systems 持久化已收集 ID

可选：hidden_item_spawner.gd 用于随机搜寻；collection_loop_patterns.gd 用于高级循环 / MainLoop 辅助功能。

可用脚本（完整列表）

• collectible_item.gd — 必须使用的拾取角色；为每个实例导出稳定的 item_id 和搜寻任务的 collection_id
• collection_manager.gd — 必须使用的进度管理器；先调用 start_collection(id, item_ids)，再调用 register_item(id, item_id)
• collection_compass.gd — 在引导玩家时必须使用；连接 collection_manager 并查询 get_remaining_ids()
• hidden_item_spawner.gd — 设计师放置点 / 概率生成（仅放置固定物品的搜寻任务中请勿加载）
• collection_loop_patterns.gd — 高级循环模式（简单的 ID 搜寻任务中请勿加载）

专家级收集模式

1. 持久化收集（存档 / 读档）

按 collection_id 序列化管理器已收集的 item_id 集合（通过 get_collected_ids() / restore_collected_ids() 使用 PackedStringArray），而不是节点路径。重新加载时：管理器恢复集合 → 如果 item_id 已拥有，可收集物品会自行禁用。

2. 收集档案 UI（剪影）

使用图标网格：未收集图标显示 modulate 剪影；管理器发出对应 ID 的信号后再显示图标。UI 绝不自行生成已收集状态。

线程化加载、MainLoop 辅助功能以及档案 / 存档进阶用法均必须使用：collection-loop-advanced.md。简单的固定 ID 寻宝任务中请勿加载。

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；将任务路由到相关领域时再加载相关技能，不要预先加载整个技能集合。

官方文档

• Area3D — 用于 3D 可收集物的 body_entered 拾取区域，以及图层/遮罩设置，确保只有玩家能触发收集。
• 使用 Area2D — 在将同一套可收集物循环适配到 Area2D/Sprite2D 雷达 UI 时的 2D 重叠模式。
• 组 — 注册可收集物并通过 get_nodes_in_group / call_group 广播重置，而无需硬编码节点路径。
• 空闲与物理处理 — 将碰撞驱动的进度放在 _physics_process / 物理帧中；在 _process 中限制罗盘/UI 的工作量。
• SceneTree — 暂停标志、组、physics_frame，以及收集状态转换所使用的 current_scene 所有权。
• 手动切换场景 — 完成狩猎并加载下一关时的延迟释放 + 实例化交接。
• 后台加载 — ResourceLoader.load_threaded_request / 状态轮询，使大型可收集物关卡不会卡住主线程。
• 保存游戏 — 使用 FileAccess 在 user:// 下持久化已收集 ID 和进度字典。
• 向量数学 — 用 direction_to / get_angle_to 实现指向最近可收集物的罗盘指引。
• Marker3D — 用于隐藏物品狩猎的设计师放置生成锚点，而非硬编码坐标。
• 使用信号 — 从拾取物到管理器和 UI 的类型化 item_collected / collection_updated 连接。
• MainLoop — 高级 collection_loop_patterns 所引用的自定义循环扩展接口（相比 SceneTree 很少需要）。

相关技能

前置条件

• godot-project-foundations — 在连接管理器、标记和可收集物场景之前的场景树、@onready 和资源基础。
• godot-gdscript-mastery — 在整个收集管理器和循环模式中使用的类型化信号、match、await 和延迟调用。
• godot-physics-3d — Area3D/CollisionShape3D 图层以及会破坏拾取检测的非均匀缩放陷阱。

配套技能

• godot-signal-architecture — 当许多可收集物都要通知同一个管理器时，使用安全的动态连接和事件总线模式。
• godot-scene-management — 为狩猎结束后的关卡切换提供线程化场景切换和所有权规则。
• godot-save-load-systems — 提供持久化存档结构，记录哪些物品在不同会话间仍保持已收集状态。
• godot-ui-containers — 使用 collection_updated 驱动剪影档案网格和进度 HUD 布局。
• godot-particles — 在 queue_free 前生成增强反馈的 VFX，让拾取操作响应更灵敏。
• godot-audio-systems — 设置与收集事件关联的一次性拾取 SFX 和总线路由。
• godot-monte-carlo-balancer — 根据完成时间分布调整 spawn_chance、目标数量和狩猎时长。

下游 / 使用方

• godot-quest-system — 将收集进度封装为带奖励和分支的任务目标。
• godot-inventory-system — 当拾取物品会保留而非消耗时，将其转为库存奖励。
• godot-theme-easter — 在相同的收集循环上叠加节日彩蛋狩猎主题呈现。

主技能

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