Godot Genre Metroidvania

NEVER Do (Expert Anti-Patterns)

World Design & Exploration

• NEVER allow "Soft-Locks" where a player is trapped; if they enter via a one-way path ("valve"), they MUST be able to leave using current abilities. Always design fail-safe escape routes.
• NEVER create empty dead ends; if a player backtracks to a remote area, they MUST be rewarded with a collectible, lore, or currency. Empty rooms are design failures.
• NEVER make backtracking purely repetitive; as the player gains movement (Dash/Teleport), traversal through old areas MUST become faster. Open shortcuts to bypass long, early routes.
• NEVER hide the critical path without "crumbs"; use distinct Landmarks, unique lighting, or environmental storytelling to build the player's mental map.
• NEVER design abilities that serve only one purpose; strictly implement dual-use traversal and combat functionality (e.g., a "Dash" that crosses gaps and dodges attacks).

Persistence & Mapping

• NEVER forget to save persistent room state; if a player opens a chest or defeats a boss, that state MUST remain saved when they leave and return.
• NEVER load interconnected rooms synchronously via load(); strictly use ResourceLoader.load_threaded_request() for seamless transitions.
• NEVER track global progression within localized room scripts; strictly use Autoload Singletons for global ability flags and world state.
• NEVER use floating-point types for grid coordinates (minimaps/fog); strictly use Vector2i to prevent precision jitter.
• NEVER manipulate the SceneTree directly from a background loading thread; strictly use call_deferred().

Physics & Controls

• NEVER calculate jump arcs or dashes inside _process(); strictly use _physics_process() to prevent stutter.
• NEVER multiply CharacterBody2D velocity by delta before move_and_slide(); the engine handles this internally.
• NEVER poll is_action_just_pressed() inside _physics_process() for buffering; strictly capture events in _unhandled_input().
• NEVER use standard strings for high-frequency ability checks; strictly use StringName (&"dashing") for pointer-speed comparisons.
• NEVER iterate through every node to broadcast updates; strictly use SceneTree.call_group() for efficient mass communication.
• NEVER delete active room/player nodes via free(); strictly use queue_free() to avoid segmentation faults.

🛠 Expert Components (scripts/)

Golden-path order (MANDATORY reads)

1. Persistence / flags — metroid_game_state.gd + persistent_progression_system.gd
2. Ability definitions / gates — ability_unlock_resource.gd + progression_gate_manager.gd
3. Room stream / switch — background_room_streamer.gd + safe_scene_switcher.gd
4. Map fog — minimap_fog_manager.gd (orchestrator) with minimap_fog.gd / minimap_fog_revealer.gd

Original Expert Patterns

• minimap_fog.gd - Grid-based fog of war that tracks visited rooms and persists via global save data.
• progression_gate_manager.gd - Central manager for ability-gated progression (Locks/Keys) and world persistence.
• metroid_game_state.gd - MANDATORY Autoload-shaped world/ability/collectible state (do not paste a local game_state tutorial).
• ability_unlock_resource.gd - MANDATORY Resource definitions for unlockable abilities queried by gates.
• minimap_fog_manager.gd - MANDATORY Vector2i fog orchestration synced to progression/save.

Modular Components

• platformer_jump_buffer.gd - Modular coyote time and jump buffering for high-fidelity movement.
• background_room_streamer.gd - Thread-safe background room preloading using ResourceLoader.
• safe_scene_switcher.gd - Deferred scene transition pattern for stable cross-room world-state switching.
• minimap_fog_revealer.gd - Vector2i-based fog-of-war clearing logic synced to player position.
• persistent_progression_system.gd - Autoload pattern for tracking global ability/collectible flags.
• ability_state_machine.gd - Optimized StringName pattern matching for traversal/combat states.
• fast_wall_detector.gd - Direct PhysicsServer queries for performance-optimized wall detection.
• save_station_broadcast.gd - Group-based entity resetting and healing logic on save interaction.
• decoupled_hazard_logic.gd - Interface-style pattern for generic damage interaction.
• smooth_room_camera_transition.gd - Tween-based camera limit interpolation for seamless room movement.

Core Loop

1. Exploration → blocked by a lock
2. Discovery → key ability / boss
3. Acquisition → new traversal/combat tool
4. Backtracking → shortcuts + dual-use abilities
5. Progression → new biome opens

Skill Chain

Architecture (script-first — no inline recipes)

1. Game State & Persistence

MANDATORY: metroid_game_state.gd + persistent_progression_system.gd. Rooms never own global ability flags. Room metadata uses resource_local_to_scene so instanced rooms do not share collectible state.

2. Room Transitions & Fast Travel

MANDATORY: background_room_streamer.gd + safe_scene_switcher.gd.

Fast travel must match NEVER (threaded load + deferred swap) — never ResourceLoader.load() / sync change_scene:

class_name FastTravelSystem extends Node

var _pending_path: String = ""
var _spawn_id: StringName = &""

func travel_to_room(scene_path: String, spawn_id: StringName) -> void:
    _pending_path = scene_path
    _spawn_id = spawn_id
    var err := ResourceLoader.load_threaded_request(scene_path)
    if err != OK:
        push_error("Fast travel request failed: %s" % scene_path)
        return
    set_process(true)

func _process(_delta: float) -> void:
    var status := ResourceLoader.load_threaded_get_status(_pending_path)
    if status == ResourceLoader.THREAD_LOAD_IN_PROGRESS:
        return
    set_process(false)
    if status != ResourceLoader.THREAD_LOAD_LOADED:
        push_error("Fast travel load failed: %s" % _pending_path)
        return
    var packed := ResourceLoader.load_threaded_get(_pending_path) as PackedScene
    # SceneTree work must be deferred — never from a worker thread
    call_deferred("_swap_room", packed, _spawn_id)

func _swap_room(packed: PackedScene, spawn_id: StringName) -> void:
    GlobalState.target_spawn_id = spawn_id
    get_tree().change_scene_to_packed(packed)

3. Ability Gating

MANDATORY: ability_unlock_resource.gd + progression_gate_manager.gd + ability_state_machine.gd. Gates query StringName abilities from the Autoload — do not hardcode ability strings in room scripts.

4. Map / Fog

MANDATORY: minimap_fog_manager.gd. Use Vector2i cells only.

Design Principles (from Dreamnoid)

• Ability Versatility — traversal + combat dual use
• Practice Rooms — teach before punish
• Landmarks — mental map without explicit markers
• Item micro-stories — lore without cutscene walls

Common Pitfalls

1. Softlocks on one-way valves — always design an escape with current abilities
2. Backtracking tedium — shortcuts + faster movement after unlocks
3. Empty dead ends — every remote path needs a reward
4. Sync room loads — violates NEVER; use threaded request + deferred swap