Collection Game Loops

Overview

Core Components

1. Collection Manager (

collection_manager.gd

)

• Role: Tracks progress (

  current / target

  ).
• Behavior: Listens for

  item_collected(id)

  -> Updates items -> Signals

  collection_completed

  on valid count.
• Tip: Use

  collection_id

  strings to run multiple hunts simultaneously (e.g., "red_eggs" vs "blue_eggs").

2. Collectible Item (

collectible_item.gd

)

• Role: Handles interaction and self-destruction.
• Behavior: On Interact -> Play VFX -> Emit Signal -> Queue Free.

3. Hidden Item Spawner (

hidden_item_spawner.gd

)

• Role: Populates the level.
• Behavior: Instantiates the item scene at:
  • Hand-placed

    Marker3D

    nodes (Deterministic).
  • Random points within a

    CollisionShape

    volume (Procedural).

Usage Example

# In a Level Script or Game Mode
@onready var manager = $CollectionManager

func _ready():
    manager.start_collection("easter_egg_2024", 10)
    manager.collection_completed.connect(_on_all_eggs_found)

func _on_all_eggs_found():
    print("You found all the eggs! Here is a bunny hat.")
    # Unlock reward

Best Practices

• Persistence: Combine with

  godot-mechanic-secrets

  to save which specific IDs have been found if the player needs to quit and resume.
• NEVER hardcode spawn positions in code: Always use

  Marker3D

  or

  CollisionShape3D

  nodes in the scene so designers can adjust layout without touching code.
• Avoid "God Objects": The

  CollectionManager

  shouldn't handle input, UI, AND audio. Let it emit signals and let other systems react.
• Juice: Always spawn particles or play a sound before the item disappears. Immediate

  queue_free()

  feels dry.