godot-game-loop-collection

$npx mdskill add thedivergentai/GD-Agentic-Skills/godot-game-loop-collection

Implement collectible IDs, scavenger hunts, and completion archives in Godot 4.7.

  • Solves stable collectible ID management and persistent find-all-X progress tracking.
  • Depends on Godot 4.7+ and uses StringName/int IDs, not NodePaths.
  • Gates collection with one-shot disable to avoid double-counting on body_entered.
  • Delivers a collection manager, compass UI, and save-compatible completion archive.

SKILL.md

.github/skills/godot-game-loop-collectionView on GitHub ↗
---
name: godot-game-loop-collection
description: "Expert collection-loop systems for collectible IDs, scavenger hunts, completion archives, nearest-item compass UI, hidden spawners, and persistent find-all-X progress. Use when implementing collectibles, scavenger hunts, completion% archives, or compass-guided item hunts. Keywords: collectible_id, scavenger_hunt, collection_manager, collection_compass, completion_archive, hidden_item_spawner, find_all, collectible_item."
---

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Collection Game Loops

Stable collectible IDs → manager → compass → save. Not generic game-loop boilerplate.

## NEVER Do (collection landmines)

- **NEVER reuse or omit stable collectible IDs** — Duplicate IDs double-count or overwrite; missing IDs break completion % and saves.
- **NEVER count the same Area overlap twice** — `body_entered` can re-fire on re-entry; gate with "already collected" / one-shot disable of monitoring.
- **NEVER persist NodePaths as the identity of collectibles** — Paths break on scene moves; save **IDs** (StringName / int), not `get_path()`.
- **NEVER soft-lock the last item** — If compass / spawn logic depends on "remaining > 1", the final pickup becomes unfindable.
- **NEVER store hunt progress only in scene-local nodes** — Level reload wipes progress; keep collected set in [collection_manager.gd](scripts/collection_manager.gd) + save.
- **NEVER `queue_free()` collectibles with zero juice and no ID commit** — Commit ID first (signal), then VFX, then free.
- **NEVER scale collectible collision shapes non-uniformly** — Breaks overlap math; edit shape resources.
- **NEVER hardcode spawn positions in code** — Use Marker3D / designer points with [hidden_item_spawner.gd](scripts/hidden_item_spawner.gd).
- **NEVER drive collection truth from UI silhouettes** — Archive UI mirrors manager state; manager is authoritative.
- **NEVER load massive levels synchronously on hunt complete** — use threaded `ResourceLoader` (see references).
- **NEVER manipulate SceneTree from worker threads** — `call_deferred` only.

---

## Golden Path (MANDATORY)

1. [collectible_item.gd](scripts/collectible_item.gd) — `item_id` (unique) + `collection_id` (hunt), one-shot Area pickup
2. [collection_manager.gd](scripts/collection_manager.gd) — authoritative collected-ID set via `register_item()` + `get_remaining_ids()`
3. [collection_compass.gd](scripts/collection_compass.gd) — nearest node whose `item_id` is still in manager remainders
4. Persist collected IDs via [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md)

Optional: [hidden_item_spawner.gd](scripts/hidden_item_spawner.gd) for randomized hunts; [collection_loop_patterns.gd](scripts/collection_loop_patterns.gd) for advanced loop/MainLoop helpers.

## Available Scripts (full set)

- [collectible_item.gd](scripts/collectible_item.gd) — **MANDATORY** pickup actor; export stable `item_id` per instance and hunt `collection_id`
- [collection_manager.gd](scripts/collection_manager.gd) — **MANDATORY** progress brain; `start_collection(id, item_ids)` then `register_item(id, item_id)`
- [collection_compass.gd](scripts/collection_compass.gd) — **MANDATORY** when guiding players; wire `collection_manager` and query `get_remaining_ids()`
- [hidden_item_spawner.gd](scripts/hidden_item_spawner.gd) — designer markers / chance spawns (Do NOT Load for fixed placed-only hunts)
- [collection_loop_patterns.gd](scripts/collection_loop_patterns.gd) — advanced loop patterns (Do NOT Load for simple ID hunts)

## Expert Collection Patterns

### 1. Persistent Collection (Save/Load)
Serialize the manager’s collected `item_id` set per `collection_id` (`PackedStringArray` via `get_collected_ids()` / `restore_collected_ids()`), not node paths. Reload: manager restores set → collectibles self-disable if `item_id` already owned.

### 2. Collection Archive UI (Silhouettes)
Grid of icons: uncollected `modulate` silhouette; reveal when manager signals that ID. UI never invents collected state.

> **MANDATORY** for threaded loads, MainLoop helpers, and archive/save depth: [collection-loop-advanced.md](references/collection-loop-advanced.md). **Do NOT Load** for simple fixed-ID scavenger hunts.

## Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

### Official Documentation
- [Area3D](https://docs.godotengine.org/en/stable/classes/class_area3d.html) — `body_entered` pickup volumes for 3D collectibles and layer/mask setup so only the player triggers collection.
- [Using Area2D](https://docs.godotengine.org/en/stable/tutorials/physics/using_area_2d.html) — 2D overlap patterns when adapting the same collectible loop to Area2D/Sprite2D radar UIs.
- [Groups](https://docs.godotengine.org/en/stable/tutorials/scripting/groups.html) — register collectibles and broadcast resets via `get_nodes_in_group` / `call_group` without hard-coded node paths.
- [Idle and physics processing](https://docs.godotengine.org/en/stable/tutorials/scripting/idle_and_physics_processing.html) — keep collision-driven progress in `_physics_process` / physics frames; throttle compass/UI work in `_process`.
- [SceneTree](https://docs.godotengine.org/en/stable/classes/class_scenetree.html) — pause flags, groups, `physics_frame`, and `current_scene` ownership used by collection state transitions.
- [Change scenes manually](https://docs.godotengine.org/en/stable/tutorials/scripting/change_scenes_manually.html) — deferred free + instantiate handoff when finishing a hunt and loading the next level.
- [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html) — `ResourceLoader.load_threaded_request` / status polling so large collectible levels do not hitch the main thread.
- [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html) — persist collected IDs and progress dictionaries with `FileAccess` under `user://`.
- [Vector math](https://docs.godotengine.org/en/stable/tutorials/math/vector_math.html) — `direction_to` / `get_angle_to` for nearest-collectible compass pointing.
- [Marker3D](https://docs.godotengine.org/en/stable/classes/class_marker3d.html) — designer-placed spawn anchors for hidden-item hunts instead of hard-coded coordinates.
- [Using signals](https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html) — typed `item_collected` / `collection_updated` wiring from pickups into the manager and UI.
- [MainLoop](https://docs.godotengine.org/en/stable/classes/class_mainloop.html) — custom loop extension surface referenced by advanced collection_loop_patterns (rarely needed over SceneTree).

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — scene tree, `@onready`, and resource basics before wiring managers, markers, and collectible scenes.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — typed signals, `match`, `await`, and deferred calls used throughout collection managers and loop patterns.
- [godot-physics-3d](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-physics-3d/SKILL.md) — Area3D/CollisionShape3D layers and non-uniform scale pitfalls that break pickup detection.

#### Complements
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — safe dynamic connections and event-bus patterns when many collectibles notify one manager.
- [godot-scene-management](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-scene-management/SKILL.md) — threaded scene swaps and ownership rules for end-of-hunt level transitions.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — durable save schemas for which items remain collected across sessions.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — silhouette archive grids and progress HUD layouts driven by `collection_updated`.
- [godot-particles](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-particles/SKILL.md) — spawn juice VFX before `queue_free` so pickups feel responsive.
- [godot-audio-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-audio-systems/SKILL.md) — one-shot pickup SFX and bus routing tied to collect events.
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — tune spawn_chance, target counts, and hunt length against completion-time distributions.

#### Downstream / consumers
- [godot-quest-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-quest-system/SKILL.md) — wraps collection progress as quest objectives with rewards and branching.
- [godot-inventory-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-inventory-system/SKILL.md) — turns collected pickups into inventory grants when items are kept rather than consumed.
- [godot-theme-easter](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-theme-easter/SKILL.md) — seasonal egg-hunt presentation layered on the same collection loop.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — library router and mirrored module entry for cross-skill discovery.

More from thedivergentai/GD-Agentic-Skills

SkillDescription
godot-2d-animationExpert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0).
godot-2d-physicsExpert patterns for Godot 2D physics including collision layers/masks, Area2D triggers, raycasting, and PhysicsDirectSpaceState2D queries. Use when implementing collision detection, trigger zones, line-of-sight systems, or manual physics queries. Trigger keywords: CollisionShape2D, CollisionPolygon2D, collision_layer, collision_mask, set_collision_layer_value, set_collision_mask_value, Area2D, body_entered, body_exited, RayCast2D, force_raycast_update, PhysicsPointQueryParameters2D, PhysicsShapeQueryParameters2D, direct_space_state, move_and_collide, move_and_slide.
godot-3d-lightingExpert patterns for Godot 3D lighting including DirectionalLight3D shadow cascades, OmniLight3D attenuation, SpotLight3D projectors, VoxelGI vs SDFGI, and LightmapGI baking. Use when implementing realistic 3D lighting, shadow optimization, global illumination, or light probes. Trigger keywords: DirectionalLight3D, OmniLight3D, SpotLight3D, shadow_enabled, directional_shadow_mode, directional_shadow_split, omni_range, omni_attenuation, spot_range, spot_angle, VoxelGI, SDFGI, LightmapGI, ReflectionProbe, Environment, WorldEnvironment.
godot-3d-materialsExpert patterns for Godot 3D PBR materials using StandardMaterial3D including albedo, metallic/roughness workflows, normal maps, ORM texture packing, transparency modes, and shader conversion. Use when creating realistic 3D surfaces, PBR workflows, or material optimization. Trigger keywords: StandardMaterial3D, BaseMaterial3D, albedo_texture, metallic, metallic_texture, roughness, roughness_texture, normal_texture, normal_enabled, orm_texture, transparency, alpha_scissor, alpha_hash, cull_mode, ShaderMaterial, shader parameters.
godot-3d-world-buildingExpert patterns for 3D level design using GridMap with MeshLibrary, CSG constructive solid geometry, occlusion, and runtime GridMap builders. Use when building 3D levels, modular tilesets, or BSP-style geometry. For sky/fog/Environment recipes, route to godot-3d-lighting. Trigger keywords: GridMap, MeshLibrary, set_cell_item, get_cell_item, map_to_local, local_to_map, CSGCombiner3D, CSGBox3D, CSGSphere3D, CSGPolygon3D, OccluderInstance3D, bake CSG.
godot-ability-systemExpert patterns for RPG/action ability systems including cooldown strategies, combo systems, ability chaining, skill trees with prerequisites, upgrade paths, and resource management. Use when implementing unlockable abilities, character progression, or complex skill systems. Trigger keywords: PlayerAbility, AbilityManager, cooldown, SkillTree, SkillNode, prerequisites, can_use, execute, ComboSystem, ability_chain, global_cooldown, charge_system, upgrade_path.
godot-adapt-2d-to-3dExpert patterns for migrating 2D games to 3D including node type conversions, camera systems (third-person, first-person, orbit), physics layer migration, sprite-to-model art pipeline, and control scheme adaptations. Use when porting 2D projects to 3D or adding 3D elements. Trigger keywords: CharacterBody2D to CharacterBody3D, Area2D to Area3D, Camera2D to Camera3D, Vector2 to Vector3, collision_layer migration, sprite to MeshInstance3D, 2D to 3D conversion.
godot-adapt-3d-to-2dExpert patterns for simplifying 3D games to 2D including dimension reduction strategies, 2.5D fake-depth, isometric ports, camera flattening, physics conversion, 3D-to-sprite art pipeline, and control simplification. Use when porting 3D to 2D, building 2.5D / isometric / fake-depth gameplay, creating 2D versions for mobile, or prototyping. Trigger keywords: CharacterBody3D to CharacterBody2D, Camera3D to Camera2D, Vector3 to Vector2, flatten Z-axis, 2.5D, isometric, fake depth, Y-sort, simulated Z, orthogonal projection, 3D to sprite conversion, performance optimization.
godot-adapt-desktop-to-mobileExpert patterns for porting desktop games to mobile including touch control schemes (virtual joystick, gesture detection), UI scaling for small screens, performance optimization for mobile GPUs, battery life management, and platform-specific features. Use when creating mobile ports or cross-platform mobile builds. Trigger keywords: TouchScreenButton, virtual_joystick, gesture_detector, InputEventScreenTouch, InputEventScreenDrag, mobile_optimization, battery_saving, adaptive_performance, MOBILE_ENABLED.
godot-adapt-mobile-to-desktopExpert patterns for scaling mobile games to desktop including mouse/keyboard controls, increased resolution and graphical fidelity, expanded UI layouts, settings menus, window management, and platform-specific features. Use when creating desktop ports or cross-platform releases. Trigger keywords: mouse_controls, keyboard_shortcuts, resolution_scaling, graphics_settings, fullscreen_toggle, window_modes, Steam_integration, desktop_optimization.