Sprawl How to Make a Metroidvania (Map + Ability Gates)

People searching how to make a metroidvania in 2026 want two very specific answers most tutorials skip: how to design the interconnected map so it actually feels like a metroidvania and not a linear platformer with backtracking, and how to structure the code so a new ability retroactively opens up rooms the player has already seen. Everything else — sprite art, tilesets, boss encounters, save systems — is standard 2D platformer work. This guide covers both metroidvania-specific problems honestly, then walks the recipe end-to-end using the Sorceress asset stack for art and audio and WizardGenie for the code loop.

How to make a metroidvania in 2026: the ingredients most tutorials skip

Metroidvania is a 2D exploration-platformer subgenre where the world is one large interconnected map, the player character starts with limited abilities, and new abilities (double jump, bomb, dash, wall cling, dive) both open new areas and reveal that previously visible walls, ledges, and passages were secretly gates the whole time. The name is a portmanteau of Metroid (Nintendo, 1986) and Castlevania: Symphony of the Night (Konami, 1997), according to the Metroidvania entry on Wikipedia. The modern indie canon — Hollow Knight, Ori and the Blind Forest, Axiom Verge, Blasphemous, Guacamelee, Animal Well — all obey the same three rules: one continuous map, an ability-gated graph of rooms, and a save system that respects backtracking.

What separates a real metroidvania from a linear platformer is not the art style or the pixel-count. It is the map. In a linear platformer the player enters level 1, clears it, enters level 2, clears it, and never returns. In a metroidvania the player wanders a hub, tries to enter every corridor, hits three or four ability gates on the first pass, comes back to each one after earning the required ability, and the world visibly opens up. Every ability, once earned, must unlock at least two rooms the player has already seen and could not enter — that is the design rule that makes the genre feel alive. Skip it and you have a platformer with fast-travel.

The metroidvania game loop in one minute (explore gate backtrack unlock)

Every metroidvania runs the same core loop, and understanding it in one minute is the difference between a real project and a stalled prototype:

1. Explore phase. Player controls the hero through platforming rooms — run, jump, attack, take damage from enemies, kill enemies, pick up small pickups (health, currency). Rooms are single screens or scrolling areas; camera clamps to the current room edges.
2. Gate encounter. Player reaches a wall, ledge, ceiling, or door that requires an ability they do not yet have. The game does not block them harshly — it just does not let them progress. A bombable wall shows small cracks; an unreachable ledge is visible above; a locked door has a colored keyhole.
3. Ability acquisition. Player finds a boss or a chest deeper in the reachable area that grants a new ability (double jump, bomb, dash, wall cling, dive). A cutscene or a screen-flash confirms the pickup, and the ability icon appears on the HUD.
4. Backtrack + unlock. Player returns to a previously visible gate, uses the new ability, and enters the newly-reachable area. The world visibly expands. This is the beat that makes the genre feel like a metroidvania.
5. Save + escalate. Player finds a save point (bench, campfire, save-room). Enemy difficulty ramps up in the newly-unlocked area. Loop repeats until every ability is earned and the final boss becomes reachable.

Every per-frame update runs off the browser-standard animation loop. The requestAnimationFrame API documented on MDN fires roughly 60 times per second in sync with the display refresh; every tick, the hero controller reads input, updates position with the current ability flags, checks room-edge triggers to load the next room, and runs enemy AI within the current room only. Rooms outside the current one are frozen or unloaded to keep the browser build responsive.

Pick your engine in 2026: Godot 4, Phaser 4, or WizardGenie

The engine question decides how much boilerplate you write vs how much you skip. Three honest 2026 answers, ranked by "playable slice in two weekends":

• WizardGenie (recommended for a first project). AI-powered game engine that runs in the browser and, on desktop, ships as a Windows installer. You paste the room graph and ability list into a paragraph; WizardGenie writes, runs, and iterates on the code in real time using its dual-agent Planner+Executor loop. The Planner (a top-tier reasoner) breaks the metroidvania loop into tasks. The Executor (a cheap fast typer like DeepSeek V4 Pro) writes the actual JavaScript. Model lineup verified 2026-08-05 in src/app/_home-v2/_data/tools.ts: Claude Opus 4.7, Claude Sonnet 4.6, GPT-5.5, Gemini 3.1 Pro, DeepSeek V4 Pro, Kimi K2.5, Grok 4.2, MiniMax M2.7 — bring your own key or use the fallback trial key.
• Godot 4. Free open-source engine, currently at Godot 4 released 14 July 2026 per the official Godot Windows download page verified 2026-08-05. Godot’s scene tree naturally models a metroidvania room (each room is a scene, the game swaps scenes on transition), CharacterBody2D plus move_and_slide() handles platformer movement, and GDScript is friendly for solo devs. Best if you want to hand-write the game and understand every collision check.
• Phaser 4. Popular 2D HTML5 game framework, currently at Phaser v4.2.1 "Giedi" released 9 July 2026 per the official Phaser download page verified 2026-08-05. Tilemap support for the rooms, arcade physics for platformer movement, group management for enemies and pickups. Best if you want a pure JavaScript build that ships as a single HTML bundle.

The rest of this guide assumes WizardGenie for the code side. Every step still applies unchanged if you swap in Godot 4 or Phaser 4 by hand — the "AI writes the loop" step becomes "you write the loop against the design doc." GameMaker 2024 is also a legitimate metroidvania engine (Nuclear Throne and Undertale used the older GameMaker Studio) but it is a paid commercial product and outside the browser-first scope of this recipe.

Step 1 — design the room graph and ability list on paper first

Skip this step and you will rewrite the metroidvania four times. This is the one genre where the design doc must be finished before the code starts, because every new ability retroactively changes the reachability graph. Do the design in 45 minutes on paper (or in a text file) and the AI code generation halves. The design doc needs four sections:

1. Room graph. A directed graph of every room as a node and every corridor as an edge, as described in the directed graph entry on Wikipedia. For a first metroidvania, 12 rooms is enough: one entrance, one central hub, three biomes with three rooms each (say caves / library / waterway), two save rooms, and one boss room. Each room has a name, a list of connected rooms, and a list of enemies. Draw it on paper. This is not optional.
2. Ability list. 3–5 abilities for a first pass. Typical set: double jump (reach higher ledges), bomb (break cracked walls), dash (cross wide gaps), wall cling (climb vertical shafts), dive (enter underwater passages). Each ability has a room where it is earned and a list of at least two gates it unlocks. If any ability unlocks only one gate, either delete the ability or add another gate — a single-unlock ability wastes the design beat.
3. Gate placement. On the room graph, mark every corridor edge that requires an ability. Colored padlocks work: red for bomb, blue for dive, green for double jump. Confirm the first-pass reachable subgraph (starting from the entrance with zero abilities) touches the room where the first ability lives. Confirm each subsequent ability, once picked up, expands the reachable subgraph by at least two rooms.
4. Save + loot table. Two save points for a 12-room map (one near the hub, one deeper in). Every room lists the enemies that spawn (2–4 per room) and any pickups (small health, small currency, or the ability itself for one room per ability).

That is the whole design doc. Put it in a markdown file with the room graph as an indented list and the ability list as a table. WizardGenie parses this structure well and will use it to seed the room manager, the ability flags, and the gate checks. A great reference for the same "design doc first, code second" pattern applied to a different genre is Fortify How to Make a Tower Defense Game, which uses the same approach for wave and tower tables.

Step 2 — generate the asset pack (hero, enemies, tilesets, music)

The asset stack for a first metroidvania slice is small compared to the design doc. Roughly one hero sprite sheet, four enemy sprites, three tilesets, one looping track, and a handful of sound effects. Broken down:

• Hero sprite sheet (one character, walk + idle + jump + attack). Open Sorceress Auto-Sprite v2. The three-step workflow — generate a character with AI, animate that character with AI video, then convert the video into a clean game-ready sprite sheet — is exactly what a metroidvania hero needs (multiple actions from one character reference). Iterate on the base character until you have something on-model, then run the animation pass for walk, idle, jump, and attack. Auto-Sprite v2 outputs a stitched sprite sheet ready for the animator in your engine.
• Enemy sprites (4 enemies). Open Sorceress Quick Sprites. Prompt each enemy: "top-down skeleton with rusted sword, 48x48 pixel art, dark grey palette, four-direction walking cycle" for a basic mob. Quick Sprites bills 9 credits per generation (verified 2026-08-05 in src/app/quick-sprites/page.tsx line 21 as CREDITS_PER_GEN = 9). Four enemies at 9 credits = 36 credits = $0.36. Metroidvanias reuse enemies across biomes with recolor variations; four base enemies plus three palette swaps gives you 12 visually distinct threats.
• Biome tilesets (3 tilesets). Open Sorceress Tileset Forge. Prompt each biome: "top-down cave tileset, 32x32 tile grid, wet-stone floor, cracked-brick walls, seamless edges, dark palette with faint blue moss" for the caves. Repeat with different palettes and themes for library (bookshelf walls, marble floor, warm palette) and waterway (dripping stone, blue water tiles, murky palette). Tileset Forge outputs a tileable image ready to slice inside your engine. Roughly 20–40 credits per biome to iterate to a clean result. For a first metroidvania three biomes reads as three distinct visual regions on the map, which is the minimum for the genre to breathe.
• Background music (2 loops). Open Sorceress Music Gen. One prompt: "90-second looping ambient track, dark cave atmosphere, minor-key strings and low drone, occasional distant drips, no percussion, ends cleanly for loop" for the exploration theme. Second prompt: same but energetic percussion and fast strings for the boss theme. Music Gen bills 10 credits per generation (verified 2026-08-05 in src/app/music-gen/page.tsx line 28 as MUSIC_CREDIT_COST = 10). Two loops at 10 credits = 20 credits = $0.20. Export to WAV for cleaner in-engine playback, or stick with the default MP3.
• SFX one-shots (8 sounds). Open Sorceress SFX Gen. Eight essentials: hero attack swing, hero hurt, enemy hit, enemy death, jump, land, door unlock, save chime. SFX Gen bills 1 credit per second of audio, minimum 1 credit (verified 2026-08-05 in src/app/sfx-gen/page.tsx line 23). Combat one-shots are 0.3–1.5s each, so figure roughly 10–16 credits for the whole pack.

Save each file with a descriptive lowercase name (hero_walk.png, cave_tiles.png, cave_ambient.wav, door_unlock.wav) into a single assets/ folder in your project. Consistent lowercase-with-underscores names let the loader glob-import the whole folder at build time. Rooms in the design doc reference asset files by name, so the loader can map a room’s tileset field to cave_tiles.png directly. Wikipedia’s entry on tile-based video games is a good background reference for how the tileset feeds the room map data.

Step 3 — code the loop in WizardGenie (rooms, gates, saves, backtracking)

With the design doc in one tab and the asset folder in another, open WizardGenie and paste the doc into the prompt. Ask it to scaffold a metroidvania with these components:

1. Game state singleton that holds hero position, hero HP, current room id, ability flags (double jump, bomb, dash, wall cling, dive), save slot data, and the set of unlocked gates. Every frame this is what the render step reads. Ability flags start as false; the pickup step flips one to true.
2. Room graph. A hardcoded object mapping room id to a list of connected room ids and a list of gate edges. Each gate edge lists the required ability. Loading a room = look up its tileset, spawn its enemies, position the hero at the entry point, and clamp the camera to the room bounds. Enemies in other rooms are unloaded.
3. Hero controller. Standard 2D platformer: horizontal move with acceleration, jump with coyote-time (~6 frames of jump-allowed after leaving a ledge), attack with a short cooldown, damage with a brief invulnerability window. Each ability flag conditionally enables its behavior: double jump lets the second jump fire mid-air, bomb spawns a bomb entity on button press, dash grants a short high-speed movement burst, wall cling latches to wall tiles when jumping into them, dive lets the hero swim in water tiles.
4. Ability gate check. When the hero tries to enter a corridor with a gate, the code reads the required ability from the room graph and checks the flag. If the ability is present, the gate visually opens (door slides, wall crumbles) and adds the corridor to the unlocked-gates set. If not, the hero bounces off with a small feedback animation and the HUD hints at the required ability icon.
5. Save point. Enter a save-room and the game writes the game-state singleton to localStorage as JSON. On next load, if a save exists, the hero spawns at the saved position with all saved ability flags and unlocked gates restored. Two save points is plenty for a 12-room map.
6. Camera + UI. Camera follows the hero but clamps to current-room bounds so the player never sees outside a room. HUD shows HP, ability icons (grayed until earned, lit after pickup), and a mini-map of rooms visited (fog-of-war style: dark until entered).
7. Sound hooks. Play hero_attack.wav on attack, hurt.wav when the hero takes damage, door_unlock.wav when a gate opens, save_chime.wav at save points, and switch the background music track when entering the boss room.

WizardGenie will produce a working prototype in one shot for the small design doc above. If it lands close but not perfect, iterate — "the double jump does not consume on the second press, fix", "the bomb wall does not visually crack, add the sprite swap", "the save room does not restore ability flags on load, check the JSON schema." Each iteration is a small chat turn, not a rewrite. The How to Make a Video Game With AI post covers the WizardGenie iteration rhythm in more depth.

Common issues (and how to fix each in under a minute)

Every first metroidvania project trips on the same handful of bugs. Fix them by adjusting numbers in the design doc, not the code:

• Player gets stuck early with no visible gates. Room graph missing a first-pass corridor. Confirm the reachable subgraph starting from the entrance (zero abilities) touches at least three rooms including the room where the first ability is earned. If not, add a corridor from the hub to that room.
• New ability unlocks only one room. Design rule broken. Add another gate for that ability somewhere the player has already been. Every ability must unlock at least two previously visible gates.
• Player forgets which gate needed which ability. Gates are not visually distinct. Give each ability type its own gate art (red cracked wall for bomb, blue watery arch for dive, high ledge with dust for double jump) so the player subconsciously maps ability to gate.
• Backtracking feels like a chore. Rooms are too big or corridors are too long. Cut room widths in half or add a fast-travel option between save rooms after the second ability is earned. Hollow Knight solved this with the Stagway network; a first project can just teleport between save rooms.
• Save-room load restores position but not ability flags. JSON schema misses the flags. Confirm the save writes the full ability object and the load call restores all flags before the render step runs.
• Enemies respawn every time the player re-enters a room. Correct behavior for a metroidvania (unlike a platformer). Do not "fix" this unless you also design a specific unkillable-enemy or one-shot-boss loop; respawning enemies is what keeps backtracking dangerous.

What a metroidvania costs to build on Sorceress in 2026

Concrete asset budget for the 12-room, 5-ability slice described above, all numbers verified 2026-08-05 against the local Sorceress source:

• Hero sprite sheet: ~50 credits ($0.50) for a full walk + idle + jump + attack sheet iterated on Auto-Sprite v2. Add a hurt animation and a special-ability animation and this rises to ~80 credits ($0.80).
• Enemy sprites: 4 enemies x 9 credits = 36 credits ($0.36) on Quick Sprites. Three palette recolors add 0 credits (recolor in a browser image editor after export) but visually double the enemy count.
• Biome tilesets: 3 biomes x ~30 credits each = ~90 credits ($0.90) for iterated clean tileable results on Tileset Forge. A fourth biome (boss room ambience) doubles the roster to ~120 credits.
• Music: 2 loops x 10 credits + 4 credits WAV exports = 24 credits ($0.24). One exploration loop, one boss loop is the minimum; add a save-room theme for another 12 credits.
• SFX pack: 8 one-shots at 1–2 credits each = ~14 credits ($0.14).

Total AI asset cost: roughly 210–280 credits, or $2.10–$2.80 at Sorceress’s 100 credits per dollar standard rate (verified 2026-08-05 in src/lib/models.ts line 69 as CREDITS_PER_DOLLAR = 100). New accounts start with 100 free credits (verified 2026-08-05 in src/app/api/admin/credits/route.ts line 12 as SIGNUP_GRANT = 100), so a first-time user pays roughly $1.10–$1.80 out of pocket for the full asset pack. The Sorceress Lifetime tier at $49 one-time (verified in src/app/plans/page.tsx line 51 as LIFETIME_PRICE = 49) covers unlimited Auto-Sprite v2, Quick Sprites, Tileset Forge, Music Gen, and SFX Gen for the life of the account, which pays back after roughly the fourth full metroidvania asset pack — useful if you plan to iterate on multiple biomes and enemy variants across a longer development cycle.

Compare to the alternative: commissioning a pixel artist for a hero sheet plus four enemies (roughly $400–$900 total), a composer for two loops ($200–$600), three tilesets from a stock library or a commission ($100–$400), and an SFX pack from a stock library ($20–$40). Traditional cost: $720–$1,940 for the same asset scope. That is not an argument that AI assets replace a human artist for a shipping commercial metroidvania — Hollow Knight or Blasphemous quality still requires human artists — it is an argument that a genuine metroidvania prototype exists at all for a solo dev with a couple of weekends and a couple of dollars.

For related workflows: the How to Make a Tower Defense Game (Wave Loop 2026) post covers the same Sorceress asset stack for a wave-based strategy game. The Sorceress Tools Guide is the wide index across every tool referenced above, and the front page at Sorceress is where WizardGenie, Auto-Sprite v2, Quick Sprites, Tileset Forge, Music Gen, and SFX Gen all live.