Plazoleta / Labs

Plantilla metroidvania

Experimento

Plantilla Unity 6 para metroidvanias 2D: combate direccional, doble salto, salas y habitaciones oscuras.

C#Unity 6

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 Rigidbody2D with 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) and BossRoom (flat arena with a BossSpawn marker), 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

  1. Create a repository from this template (GitHub Use this template) and clone it.
  2. Recommended for a game: store art and audio in Git LFS. Run git lfs install and swap the binary block in .gitattributes for the commented LFS lines below it. The template itself stays LFS-free, because GitHub template repositories cannot contain LFS content.
  3. In Unity Hub: Add > Add project from disk, pick the folder and open it with 6000.6.5f1.
  4. Open Assets/_Project/Scenes/TestRoom.unity and press Play.
  5. Make it yours:
    • Edit > Project Settings > Player: set Company Name, Product Name and the bundle identifier.
    • Optionally rename the Metroidvania root namespace: find and replace it in Assets/_Project, including the assembly definitions Metroidvania.Runtime and Metroidvania.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

  1. Draw on a 48x48 canvas for characters (any editor that exports .aseprite).
  2. Drop the file into Assets/Characters/<Name>/.
  3. The 2D Aseprite Importer turns it into sprites and animation clips. Importer settings: PPU 16, pivot bottom-center, Point filter, no compression.
  4. Hook animations to PlayerController events (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)