godot-game-loop-collection

Original：🇺🇸 English
Translated

Use when implementing collection quests, scavenger hunts, or "find all X" objectives.

7installs
Sourcethedivergentai/gd-agentic-skills
Added on

NPX Install

npx skill4agent add thedivergentai/gd-agentic-skills godot-game-loop-collection

Tags

Translated version includes tags in frontmatter
game-collection-loopsgodot-enginegdscriptcollectible-systemgame-mechanics

SKILL.md Content

View Translation Comparison →

Collection Game Loops

Overview

This skill provides a standardized framework for "Collection Loops" – gameplay objectives where the player must find and gather a specific set of items (e.g., hidden eggs, data logs, coins).

Core Components

1. Collection Manager (
collection_manager.gd
)

The central brain of the hunt.
  • 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
)

The physical object in the world.
  • Role: Handles interaction and self-destruction.
  • Behavior: On Interact -> Play VFX -> Emit Signal -> Queue Free.

3. Hidden Item Spawner (
hidden_item_spawner.gd
)

Automates the placement of items.
  • Role: Populates the level.
  • Behavior: Instantiates the item scene at:
    • Hand-placed 
      Marker3D
      nodes (Deterministic).
    • Random points within a 
      CollisionShape
      volume (Procedural).

Usage Example

gdscript
# 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.