A Godot metroidvania template is a platformer with a map screen

By Eduardo Orellana · Updated

The systems in a metroidvania can be handed to you. The interconnected map cannot, and the map is the game, which is why this genre gets less out of a starter project than almost any other. Flockbay is free, AI included: free hosted AI every day, or your own Claude, ChatGPT, agent or API key. It runs on Windows, macOS and Linux, on the official Godot engine.

AppImage, x86_64. Ubuntu 22.04, Debian 12, Fedora 39 or newer.

Intel or AMD Chromebook, with Linux turned on.

Download for macOSDownload for Windows

What exists

Godot has no official metroidvania demo. Its own demo projects run to a 2D role-playing demo, a truck-driving demo, a multiplayer bomber, and nothing shaped like this. So the projects people share are community ones, and the one that circulates most is the Darkcom Metroidvania repository on GitHub: a 2D side-view starter with a character controller, enemies, connected level scenes, map data, and the menu and options flow around them.

That list is the standard shape. A metroidvania starter is a platformer starter with three things bolted on: a dash or similar ability, a health bar, and a minimap. It is a real project and it will save you real time, but it is a smaller head start than the genre label suggests.

The honest comparison is a plain 2D platformer starter, of which Godot has more and better maintained ones. What you would be missing is ability gating, save persistence and map data, and two of those three you will write yourself anyway.

More on this: Godot 3D game templates and the work they do not remove

The map is the design, and it is not in the box

A metroidvania is a graph of locks and keys wearing the costume of a place. You see a ledge you cannot reach in the first ten minutes, you find the double jump in the fortieth, and the game is good in proportion to how well it remembered that ledge and how satisfying the walk back is. That structure is the creative act of the genre.

Nothing about it is code. It is a decision about what order abilities arrive in, which regions each one opens, how many routes exist through the middle of the game, and where the shortcuts unlock so that backtracking feels like mastery rather than a chore. A starter project cannot contain a line of it, because it is not the kind of thing that lives in a file.

The practical consequence is a working order. Sketch the region graph on paper first. Decide which ability opens which door, then check that every region has an exit reachable with the abilities the player must already hold to be standing there. Most abandoned metroidvanias have an excellent dash and a map that is still three rooms in a row.

More on this: Building a metroidvania when the map is the design

The controller you inherit is the one you will fight

Movement feel decides whether people keep playing, and it is almost entirely a tuning problem. Jump height and the arc it makes. How much you can steer in the air. Coyote time, so a jump pressed just after leaving the ledge still counts. Jump buffering, so a jump pressed just before landing still counts. Whether the dash cancels into a jump.

A starter arrives with somebody else's answers to all of those, and they will feel wrong to you, because feel is personal and theirs was tuned against their game. So the first thing you do with an inherited controller is change it, which means the first code you have to read properly is the code the author cared most about and structured most tightly.

This is why a metroidvania starter is a weaker deal than a racing or tower defense one. There you can leave the inherited systems alone for months. Here the one thing you must change on day one sits at the centre of the project.

More on this: Godot puzzle templates: three of the four are card games

Persistence is what breaks late

A metroidvania has to remember things across a save file, and the list is longer than it looks. Which doors are open. Which bosses stay dead. Which items are gone from the world. Which abilities you hold. Which rooms have been seen, so the map can draw them. Where the last save point was.

Starters usually stop short of that, because a demo with three rooms does not need it. Retrofitting persistence into a project that assumed rooms were disposable is one of the genuinely expensive jobs in this genre. Every scene that spawns something has to ask whether that something is already gone.

The map screen is the same problem in different clothes. A map is a data structure that has to stay in step with the level layout, and maintained separately the two will drift the first week you start moving rooms. Deriving the map from the layout costs more up front and is the version that survives.

The volume problem

Metroidvanias are large. Not in systems, in rooms. The genre's well-known games run to hundreds of screens, and the feeling of a connected world is a direct product of that count. There is no version of this genre that is small and still feels like the genre.

A starter gives you two or three rooms. The gap between that and a shippable game is a content pipeline: a way to build a room quickly, connect it to its neighbours, place enemies and pickups, and test it from the nearest save point rather than the title screen. Building that early is what makes the rest possible, and no starter contains it because it is specific to how you work.

If that sounds like more than you want to take on, a single-screen action game or a linear platformer is not a lesser goal. It is a different one, and it finishes. The game templates list a starting point for every genre, metroidvania included.

Where Flockbay fits

Flockbay approaches this from the other side, and it is not a template library. There is no picker in the app, though a Godot project you have downloaded opens in it with Open Godot project. What changes is who writes the code: you say the dash should cancel into a jump, Flockbay writes the GDScript in your project, plays it itself, and then you play it and say whether it is right. That loop answers the controller problem better than inheriting somebody's and editing it.

The volume problem gets a more direct answer than you might expect. Creating a project settles 2D or 3D first, read from your description and confirmed by you, and Flockbay writes a brief before it builds anything: which rooms come first, what comes after, what is not in this version. Once you approve it, rooms are painted rather than assembled. Flockbay lays tile ground cell by cell, and the tiles, the edges and the collision all follow from which cells are ground, so a block stops the walker the moment it is there. The matcher is a pure function of that coverage, which is exactly what you want in a genre where rooms get moved: painting the same cells in a different order draws the same edges every time. When a jump is one cell too far, Paint is a button around Godot's own 2D view, so you can drag that cell yourself, and Godot's undo takes it back.

Where it stops is the part this page has spent five sections on. Laying rooms fast does not decide which ability opens which door. Bring the region graph you sketched on paper to the brief, and Flockbay writes the gating, the map screen and the save format against it. The graph is still yours to design, the walk back is still yours to judge, and persistence is still the expensive job, which is why it belongs in the brief before the rooms multiply. Flockbay is a desktop app for Windows, macOS and Linux, the engine underneath is Godot, and your game runs locally on the bundled copy. Building needs an internet connection; playing what you built does not.

More on this: Make a platformer with AI: getting the jump right is the whole job

A starting project for this is the platformer game templates. The design note that goes with it is how level design tells a story.

Questions

Is there an official Godot metroidvania template?
No. Godot ships demo projects but none of them is a metroidvania. What people share are community repositories on GitHub, the Darkcom Metroidvania project among them.
Can I pick a metroidvania template inside Flockbay?
No. Flockbay has no template picker and no starter projects in it at all. Anything on this page is a public repository you clone yourself, then open in Godot or, for a Godot 4 project, in Flockbay with Open Godot project.
Could I just use a 2D platformer template instead?
Usually yes, and often it is the better base, because platformer projects are more numerous and better maintained. What you would add is ability gating, save persistence and the map screen, and you were likely writing those yourself either way.
How big does a metroidvania need to be?
Bigger than most first projects. The sense of a connected world comes from having many rooms and several routes through them, so the genre does not scale down gracefully. Plan the content pipeline before the tenth room, not after the fiftieth.
What is the most expensive thing to add late?
Persistence. Deciding halfway through that the world must remember opened doors, dead bosses and taken items means revisiting every scene that spawns anything. Design the save format before the rooms multiply.