godot-game-loop-collection

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.

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 + 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.
• 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 (see references).