Expert blueprint for Metroidvanias including ability-gated exploration (locks/keys), interconnected world design (backtracking with shortcuts), persistent state tracking (collectibles, boss defeats), room transitions (seamless loading), map systems (grid-based revelation), and ability versatility (combat + traversal). Use for exploration platformers or action-adventure games. Trigger keywords: metroidvania, ability_gating, interconnected_world, backtracking, map_system, persistent_state, room_transition, soft_locks.
13k tokens
context cost
the whole folder, loaded on every use
20
files
ships runnable scripts
0
copies elsewhere
how many repositories repackaged it
451
stars on the repo
on the repository, not the skill itself
Install
one command, takes just this skill from the repository
NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.
Genre: Metroidvania
Expert blueprint for Metroidvanias balancing exploration, progression, and backtracking rewards.
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.
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.
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
Softlocks on one-way valves — always design an escape with current abilities
Backtracking tedium — shortcuts + faster movement after unlocks
Empty dead ends — every remote path needs a reward
> 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
Using CharacterBody2D — move_and_slide, floor detection, and velocity rules for coyote/buffer jumps and dash traversal.
Idle and Physics Processing — keep jump arcs, dashes, and wall slides in _physics_process; capture buffers in input callbacks.
InputEvent — _unhandled_input jump/ability buffering so presses are not lost between physics ticks.
Background loading — ResourceLoader.load_threaded_request for adjacent-room preload without hitch spikes.
Change scenes manually — deferred room swaps, spawn door IDs, and safe queue_free of the outgoing room.
Saving games — persist abilities, opened gates, collectibles, and visited map cells across sessions.
Singletons (Autoload) — global progression/game-state ownership so rooms never keep conflicting ability flags.
Resources — ability unlock definitions and room metadata as .tres data with safe duplication.
Using Tilemaps — TileMapLayer + Vector2i cells for minimap fog revelation and grid room tracking.
Camera2D — room limit_* bounds and tweened limit handoffs for seamless camera room transitions.
Using Area2D — doors, save stations, and hazard triggers via body_entered without hard scene coupling.
Groups — call_group for save-station heal/respawn broadcasts instead of walking the whole tree.
Related Skills
Prerequisites
godot-project-foundations — autoloads, scene layout, and project settings before stacking room streaming and global progression.
godot-characterbody-2d — tight platformer locomotion is the substrate under ability-gated traversal (dash, wall slide, double jump).
godot-tilemap-mastery — layered TileMap/TileMapLayer authorship for gameplay collision, landmarks, and minimap fog grids.
godot-autoload-architecture — singleton ownership patterns for ability flags and world persistence that rooms must not duplicate.
Complements
godot-scene-management — threaded load queues and deferred room switches that keep interconnected maps hitch-free.
godot-save-load-systems — durable schemas for collectibles, boss flags, and visited cells across long exploration sessions.