Plantilla metroidvania
ExperimentoPlantilla Unity 6 para metroidvanias 2D: combate direccional, doble salto, salas y habitaciones oscuras.
Más información Abrir en GitHub →
Starting point for 2D pixel-art metroidvanias in Unity 6 (6000.6.5f1), URP 2D Renderer and the Input System. It ships a tuned player controller, directional combat, movement abilities, room transitions and debug tools, so a new game starts from gameplay instead of setup.
Everything that can be generated is generated by editor scripts (placeholder art, player prefab, rooms), so the project stays easy to rebuild and diff.
Features
- Player controller on a dynamic
Rigidbody2Dwith manual gravity: acceleration/deceleration, air control, exact jump height, coyote time, jump buffer and jump cut. All values in the inspector, in Unity units (1 u = 16 px). - Combat: forward, up and down attacks (down only in the air), each with its own hitbox and timing window, plus
UnityEvents and states to hook animations. - Abilities (toggle with F3): double jump, forward slash (ground and air) and wall cling with wall jump that lets you climb walls.
- Rooms: one scene per room, exits (
RoomTransition) and arrival points (RoomEntrance), fade to black between rooms, camera cut to the player on arrival. - Camera: Cinemachine follow with a confiner to the room bounds, Pixel Perfect Camera at 320x180 with integer upscale.
- Dark rooms (toggle with F4): only a halo around the player lights the scene.
- Debug: on-screen readout (F1), in-game collider outlines for everything in the scene (F2), respawn (R), editor gizmos.
- Sample rooms:
TestRoom(controller tuning course) andBossRoom(flat arena with aBossSpawnmarker), linked by a door.
Technical setup
| Item | Value |
|---|---|
| Unity | 6000.6.5f1, Universal 2D template (URP 2D Renderer) |
| Reference resolution | 320x180, Pixel Perfect Camera, integer upscale |
| Pixels per unit | 16 (1 unit = 16 px) |
| Tiles | 16x16 |
| Character canvas | 48x48, pivot bottom-center (0.5, 0), body 12x32 px collider |
| Input | Input System, keyboard + gamepad at the same time |
| Physics layers | 6 Ground, 7 Player |
Packages: 2D Aseprite Importer, 2D Pixel Perfect, 2D Tilemap, Cinemachine, Input System. No Asset Store or third-party packages.
Starting a new game
- Create a repository from this template (GitHub Use this template) and clone it.
- Recommended for a game: store art and audio in Git LFS. Run
git lfs installand swap the binary block in.gitattributesfor the commented LFS lines below it. The template itself stays LFS-free, because GitHub template repositories cannot contain LFS content. - In Unity Hub: Add > Add project from disk, pick the folder and open it with 6000.6.5f1.
- Open
Assets/_Project/Scenes/TestRoom.unityand press Play. - Make it yours:
- Edit > Project Settings > Player: set Company Name, Product Name and the bundle identifier.
- Optionally rename the
Metroidvaniaroot namespace: find and replace it inAssets/_Project, including the assembly definitionsMetroidvania.RuntimeandMetroidvania.Editor. - Replace the placeholder art (see Art pipeline) and build your own rooms (see Rooms).
If the generated scenes or prefab are ever missing or outdated, rebuild them from the Metroidvania menu: Build Player Prefab, Build Test Room, Build Boss Room, and Placeholders for the dummy sprite and ground tile.
Controls
| Action | Keyboard | Gamepad |
|---|---|---|
| Move | WASD / arrows | Left stick / D-pad |
| Jump (hold for full height; again in the air to double jump) | Space / J | A / South |
| Attack | K | X / West |
| Up attack (ground or air) | Up + K | Up + X |
| Down attack (air only) | Down + K | Down + X |
| Forward slash (ground or air) | L | RT |
| Wall cling / wall jump | Push into a wall in the air / jump | Same |
| Pause (reserved) | Esc | Menu / Start |
Debug keys: F1 readout, F2 collider outlines, F3 abilities on/off, F4 dark room, R (or gamepad View) respawn.
Rooms
Each room is a scene with its own player and camera, so any room can be played directly. Rooms are built from code with RoomBuilder (Assets/_Project/Editor/RoomBuilder.cs):
var room = RoomBuilder.Begin("Assets/_Project/Scenes/MyRoom.unity");
room.Shell(width: 40, height: 18, floorTop: 3); // floor, walls, ceiling
room.Clear(0, 3, 0, 5); // a 3-tile door in the left wall
room.PlacePlayer(new Vector2(1.5f, 3f));
room.AddEntrance("FromTestRoom", new Vector2(1.5f, 3f), facing: 1);
room.AddTransition("To TestRoom", new Rect(0f, 3f, 0.75f, 3f), "TestRoom", "FromBossRoom", exitDirection: -1);
room.Finish(); // collision, camera, save, add to build
A transition names the target scene and an entrance id in it; the player walks out while the screen fades to black and appears standing at the entrance, facing into the room. Keep the body (12 px wide) clear of the door trigger at the entrance. TestRoomBuilder and BossRoomBuilder are complete examples.
Level design notes for the default tuning: the full jump reaches 3.5 tiles (3 tiles needs a near-full jump), the double jump adds 3, and the body is 2 tiles tall, so never leave exactly 2 tiles of headroom under a solid platform.
Art pipeline
- Draw on a 48x48 canvas for characters (any editor that exports
.aseprite). - Drop the file into
Assets/Characters/<Name>/. - The 2D Aseprite Importer turns it into sprites and animation clips. Importer settings: PPU 16, pivot bottom-center, Point filter, no compression.
- Hook animations to
PlayerControllerevents (On State Changed,On Attack Started,On Slash Started, ...).
Project layout
Assets/
_Project/
Scenes/ TestRoom, BossRoom
Scripts/ runtime code (Metroidvania.* namespaces)
Player/ PlayerController
Controls/ generated Input System wrapper (PlayerInputActions)
Rooms/ RoomTransition, RoomEntrance, RoomTransitionManager
Lighting/ DarkRoom
Debugging/ overlay, collider visualizer, respawn
Editor/ placeholder art, prefab and room builders
Input/ Player.inputactions
Art/ placeholder sprites and tiles
Prefabs/ Player
Resources/ debug line material
Characters/ imported characters (.aseprite)