godot-game-loop-collection

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 [collectionmanager.gd](scripts/collectionmanager.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 [hiddenitemspawner.gd](scripts/hiddenitemspawner.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. [collectibleitem.gd](scripts/collectibleitem.gd) — itemid (unique) + collectionid (hunt), one-shot Area pickup
2. [collectionmanager.gd](scripts/collectionmanager.gd) — authoritative collected-ID set via registeritem() + getremaining_ids()
3. [collectioncompass.gd](scripts/collectioncompass.gd) — nearest node whose item_id is still in manager remainders
4. Persist collected IDs via godot-save-load-systems

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

Available Scripts (full set)

• [collectibleitem.gd](scripts/collectibleitem.gd) — MANDATORY pickup actor; export stable itemid per instance and hunt collectionid
• [collectionmanager.gd](scripts/collectionmanager.gd) — MANDATORY progress brain; startcollection(id, itemids) then registeritem(id, itemid)
• [collectioncompass.gd](scripts/collectioncompass.gd) — MANDATORY when guiding players; wire collectionmanager and query getremaining_ids()
• [hiddenitemspawner.gd](scripts/hiddenitemspawner.gd) — designer markers / chance spawns (Do NOT Load for fixed placed-only hunts)
• [collectionlooppatterns.gd](scripts/collectionlooppatterns.gd) — advanced loop patterns (Do NOT Load for simple ID hunts)

Expert Collection Patterns

1. Persistent Collection (Save/Load)

Serialize the manager’s collected itemid set per collectionid (PackedStringArray via getcollectedids() / restorecollectedids()), 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 — bodyentered pickup volumes for 3D collectibles and layer/mask setup so only the player triggers collection.
• Using Area2D — 2D overlap patterns when adapting the same collectible loop to Area2D/Sprite2D radar UIs.
• Groups — register collectibles and broadcast resets via getnodesingroup / callgroup without hard-coded node paths.
• Idle and physics processing — keep collision-driven progress in physicsprocess / physics frames; throttle compass/UI work in process.
• SceneTree — pause flags, groups, physicsframe, and current_scene ownership used by collection state transitions.
• Change scenes manually — deferred free + instantiate handoff when finishing a hunt and loading the next level.
• Background loading — ResourceLoader.loadthreaded_request / status polling so large collectible levels do not hitch the main thread.
• Saving games — persist collected IDs and progress dictionaries with FileAccess under user://.
• Vector math — directionto / getangleto for nearest-collectible compass pointing.
• Marker3D — designer-placed spawn anchors for hidden-item hunts instead of hard-coded coordinates.
• Using signals — typed itemcollected / collection_updated wiring from pickups into the manager and UI.
• MainLoop — custom loop extension surface referenced by advanced collectionloop_patterns (rarely needed over SceneTree).

Related Skills

Prerequisites

• godot-project-foundations — scene tree, @onready, and resource basics before wiring managers, markers, and collectible scenes.
• godot-gdscript-mastery — typed signals, match, await, and deferred calls used throughout collection managers and loop patterns.
• godot-physics-3d — Area3D/CollisionShape3D layers and non-uniform scale pitfalls that break pickup detection.

Complements

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

Downstream / consumers

• godot-quest-system — wraps collection progress as quest objectives with rewards and branching.
• godot-inventory-system — turns collected pickups into inventory grants when items are kept rather than consumed.
• godot-theme-easter — seasonal egg-hunt presentation layered on the same collection loop.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.