| name | godot-game-loop-collection |
| description | Use when implementing collection quests, scavenger hunts, or "find all X" objectives. |
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).
NEVER Do
- NEVER use free() to destroy an active state node or level — This can cause crashes if the node is still processing. Always use
queue_free() to safely dispose of it at the end of the frame.
- NEVER calculate physics-dependent game state in _process() — Movement and precise collisions must happen in
_physics_process() to stay synced with the engine's fixed timestep.
- NEVER execute heavy state transitions (like loading massive levels) synchronously — Calling
load() on a huge scene stalls the main thread. Use ResourceLoader.load_threaded_request().
- NEVER use exact floating-point equality (==) for time-based states — Floating-point errors will eventually cause missed triggers. Use
is_equal_approx() or relative comparisons.
- NEVER manipulate the active SceneTree from a background thread — The SceneTree is not thread-safe. Use
call_deferred() to push results back to the main thread.
- NEVER rely on a monolithic "GameManager" with hardcoded absolute paths — This creates tight coupling. Use groups, signals, and exported references for a modular architecture.
- NEVER assume child nodes are ready before their parent —
_ready() executes from bottom-to-top. If you need child references, use @onready or await ready.
- NEVER use string-based signals for critical state transitions — Avoid
connect("signal", _on_func). Use the Signal object syntax (signal.connect(_on_func)) for compile-time validation.
- NEVER poll for input state every frame for discrete menu events — Use the
_unhandled_input() callback to cleanly intercept events without wasting CPU cycles in _process().
- NEVER crash the engine intentionally via CRASH_NOW_MSG — Regular state handling should always recover gracefully. Crashing is for unrecoverable internal engine failures.
- NEVER hardcode spawn positions in code — Always use
Marker3D or CollisionShape3D nodes in the scene so designers can adjust layout without touching code.
- NEVER neglect "juice" before an item disappears — Immediate
queue_free() feels dry. Always spawn particles or play a sound before removal.
- NEVER use global variables for local collection progress — Keep counts encapsulated within the
CollectionManager and emit signals to update the UI.
- NEVER leave orphaned nodes in the tree during state swaps — Always ensure the previous level/state is properly queued for deletion before instantiating the new one.
- NEVER scale collision shapes non-uniformly for collectibles — This breaks collision detection math. Adjust the internal shape resource properties instead.
Available Scripts
MANDATORY: Read the appropriate script before implementing the corresponding pattern.
Collection of 10 expert patterns: Custom MainLoop extensions, deferred scene switching, threaded loading, and frame throttling.
The central brain of the hunt. Tracks progress and manages completion signals.
Spatial radar for pointing towards the nearest collectible using vector math.
Expert Collection Patterns
1. Persistent Collection (Save/Load)
To ensure progress survives restarts, use FileAccess to store data in user://.
func save_progress(data: Dictionary):
var file = FileAccess.open("user://save.dat", FileAccess.WRITE)
file.store_var(data) # Binary serialization for performance
func load_progress() -> Dictionary:
if not FileAccess.file_exists("user://save.dat"): return {}
var file = FileAccess.open("user://save.dat", FileAccess.READ)
return file.get_var()
2. Collection Archive UI (Silhouettes)
Display uncollected items as silhouettes without extra textures by using modulate.
- Technique: Use an
ItemList or TextureRect grid.
- Silhouette: Set
modulate = Color(0, 0, 0, 0.5) for locked items.
- Reveal: Set
modulate = Color(1, 1, 1, 1) once collected.
Reference
