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_t…
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.
Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.
Claude CodeNot declared
CursorNot declared
CodexNot declared
GitHub CopilotNot declared
WindsurfNot declared
Gemini CLINot declared
ClineNot declared
OpenCodeNot declared
Repository health
Stars678
LicenseLICENSE
Default branchmain
Open issues0
Status
Active
Package contents
Files included with this skill beyond the listing page.
skill mdSKILL.md16,107 B
docsSUMMARY.md553 B
History
First seen on skills.sh
First recorded snapshot · 212 installs
SKILL.md
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.loadthreadedrequest() 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 moveandslide(); the engine handles this internally.
NEVER poll isactionjustpressed() inside physicsprocess() 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.
Map fog — [minimapfogmanager.gd](scripts/minimapfogmanager.gd) (orchestrator) with [minimapfog.gd](scripts/minimapfog.gd) / [minimapfogrevealer.gd](scripts/minimapfogrevealer.gd)
Original Expert Patterns
[minimapfog.gd](scripts/minimapfog.gd) - Grid-based fog of war that tracks visited rooms and persists via global save data.
[progressiongatemanager.gd](scripts/progressiongatemanager.gd) - Central manager for ability-gated progression (Locks/Keys) and world persistence.
[metroidgamestate.gd](scripts/metroidgamestate.gd) - MANDATORY Autoload-shaped world/ability/collectible state (do not paste a local game_state tutorial).
[abilityunlockresource.gd](scripts/abilityunlockresource.gd) - MANDATORY Resource definitions for unlockable abilities queried by gates.
[minimapfogmanager.gd](scripts/minimapfogmanager.gd) - MANDATORY Vector2i fog orchestration synced to progression/save.
Modular Components
[platformerjumpbuffer.gd](scripts/platformerjumpbuffer.gd) - Modular coyote time and jump buffering for high-fidelity movement.
[backgroundroomstreamer.gd](scripts/backgroundroomstreamer.gd) - Thread-safe background room preloading using ResourceLoader.
[safesceneswitcher.gd](scripts/safesceneswitcher.gd) - Deferred scene transition pattern for stable cross-room world-state switching.
[minimapfogrevealer.gd](scripts/minimapfogrevealer.gd) - Vector2i-based fog-of-war clearing logic synced to player position.
[persistentprogressionsystem.gd](scripts/persistentprogressionsystem.gd) - Autoload pattern for tracking global ability/collectible flags.
[abilitystatemachine.gd](scripts/abilitystatemachine.gd) - Optimized StringName pattern matching for traversal/combat states.
[fastwalldetector.gd](scripts/fastwalldetector.gd) - Direct PhysicsServer queries for performance-optimized wall detection.
[savestationbroadcast.gd](scripts/savestationbroadcast.gd) - Group-based entity resetting and healing logic on save interaction.
[decoupledhazardlogic.gd](scripts/decoupledhazardlogic.gd) - Interface-style pattern for generic damage interaction.
[smoothroomcameratransition.gd](scripts/smoothroomcameratransition.gd) - Tween-based camera limit interpolation for seamless room movement.
MANDATORY: [metroidgamestate.gd](scripts/metroidgamestate.gd) + [persistentprogressionsystem.gd](scripts/persistentprogressionsystem.gd). Rooms never own global ability flags. Room metadata uses resourcelocalto_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: [abilityunlockresource.gd](scripts/abilityunlockresource.gd) + [progressiongatemanager.gd](scripts/progressiongatemanager.gd) + [abilitystatemachine.gd](scripts/abilitystatemachine.gd). Gates query StringName abilities from the Autoload — do not hardcode ability strings in room scripts.
4. Map / Fog
MANDATORY: [minimapfogmanager.gd](scripts/minimapfogmanager.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 — moveand_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 — unhandledinput jump/ability buffering so presses are not lost between physics ticks.
Background loading — ResourceLoader.loadthreaded_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.
