Unity Aseprite Importer

Overview

The 2D Aseprite Importer (com.unity.2d.aseprite) is a Unity package that imports Aseprite’s .ase and .aseprite files directly, with no PNG export step. It supports all Aseprite colour modes (RGBA, Grayscale and Indexed), layers, layer and cel opacity, linked cels, individual frame durations, and frame tags (Unity Technologies, Aseprite Importer manual: Aseprite Features). When you save the file in Aseprite, Unity reimports it, so the .aseprite file stays the single source of truth for the art and its animations.

Unity lists the Aseprite Importer in the 2D feature set, alongside 2D Animation, 2D Pixel Perfect, 2D PSD Importer, 2D Sprite, 2D SpriteShape, 2D Tilemap Editor and 2D Tilemap Extras (Unity Technologies, Unity Manual: 2D feature set). The package major version follows the editor: 1.1.x/1.0.x for Unity 6.0 (and 2022.3/2021.3), 1.2.x for 6.1, 2.x for 6.2 and 3.x for 6.3 (Unity Technologies, Aseprite Importer manual, version 3.0).

This page is the Aseprite-specific part of the unity-pixel-art-pipeline. The import rules there (Point filtering, no compression, one project-wide Pixels Per Unit) apply equally to Aseprite files.

Setup

1. Check Window → Package Manager → In Project for 2D Aseprite Importer. Projects created from the Universal 2D template normally have it as part of the 2D feature set; if it is missing, install it from the Unity Registry.
2. Save your art in Aseprite as .aseprite (or .ase) inside the project’s Assets folder.
3. Select the file in the Project window and set the importer options below, then click Apply.

Settings to check on every file

Setting	Default	What to set	Why
Import Mode	Animated Sprite	Animated Sprite for characters; Sprite Sheet for static props or tilesets you slice yourself; Tile Set for Aseprite tilemap layers	Decides what assets Unity generates
Pixels Per Unit	100	Your project-wide PPU (e.g. 16)	The default will make the sprite the wrong size next to your tiles
Filter Mode	Point	Leave on Point	Already correct for pixel art
Compression	None	Leave on None	Already correct for pixel art
Generate Mip Maps	Off	Leave off	Mip maps blur pixel art
Pivot Alignment / Pivot Space	Bottom / Canvas	Bottom suits characters standing on the ground	Canvas space keeps each frame’s position as drawn on the Aseprite canvas
Layer Import Mode	Merge Frame	Merge Frame unless you need separate layers	Merges all layers of a frame into one sprite; Individual Layers makes one sprite per layer per frame
Generate Physics Shape	—	On if you will use a Polygon Collider 2D or tile Collider Type: Sprite	Creates a default physics shape from the sprite outline when none is set in the Sprite Editor

The default values in this table come from the package’s importer documentation (Unity Technologies, Aseprite Importer manual: Importer Features). The key point for crisp pixel art is that filtering and compression are already right, but Pixels Per Unit is not: always change it from 100 to the PPU the rest of the project uses, and match it on the unity-pixel-perfect-camera’s Assets Pixels Per Unit.

Usage

Frame tags become Animation Clips

In Animated Sprite mode with Animation Clip enabled, “every tag in Aseprite generates one Animation Clip”; with no tags, one clip covers all frames. Frame timing comes from the frame durations in Aseprite (Unity Technologies, Aseprite Importer manual: Importer Features). A practical workflow is therefore:

1. In Aseprite, tag frame ranges Idle, Run, Jump, Attack and so on.
2. Save. Unity generates a model prefab (set up to look like the first frame), a clip per tag, and an Animator Controller when the file has more than one frame.
3. Drag the generated prefab into the scene, or use the clips on your own character.

Details worth knowing:

• Looping. Tags loop by default (Repeat = ∞). To make a one-shot clip such as Attack or Die, open the tag’s properties in Aseprite and set Repeat to 1, then save; Unity reimports the clip without looping (Unity Technologies, Aseprite Importer manual: Importer FAQ).
• Direction. Only the Forward tag direction is supported (Unity Technologies, Aseprite Importer manual: Aseprite Features); ping-pong or reverse tags need to be laid out as forward frames.
• The generated Animator Controller is read-only. To add transitions and parameters, use Export Animation Assets in the importer, tick Animator Controller, and export it to a folder. If you leave the clips unticked during export, the states stay linked to the Aseprite file so art changes still flow through. New tags added later must be wired into the exported controller by hand (Unity Technologies, Aseprite Importer manual: Importer FAQ). Drive the controller from code as described in unity-animator-scripting.
• Animation events. Put event:FootstepLeft in a cel’s User Data in Aseprite and Unity adds an animation event on that frame; add a method with the same name to a script on the Animator’s GameObject. Arguments can follow a comma, for example event:Hit, 2 (Unity Technologies, Aseprite Importer manual: Importer FAQ).

Aseprite tilemaps

With Import Mode: Tile Set, the importer finds tilemap layers in the file and generates Tile assets and a Tile Palette for unity-tilemap. All tile sets in the file must share one tile size; if they do not, the first tile set used decides the Unity tile size (Unity Technologies, Aseprite Importer manual: Aseprite Features). You still add collision yourself on the Unity side (see Colliders and physics).

Alternative route: export a 1× PNG sprite sheet

If you cannot use the package (for example an older Unity version or a team that hands over PNGs), export a sprite sheet from Aseprite instead:

1. In Aseprite, choose File → Export Sprite Sheet (Aseprite, Aseprite Docs: Sprite Sheet).
2. Use a regular grid layout (by rows or columns) so every frame occupies a cell of the same size, and keep the output at 100% scale. Do not upscale in Aseprite: Unity scales the art on screen through the camera, and an upscaled PNG simply wastes texture memory and breaks the one-texel-per-art-pixel rule.
3. Import the PNG into Unity and apply the settings in unity-pixel-art-pipeline (Sprite Mode Multiple, Point, no compression, project-wide PPU).
4. Slice it in the Sprite Editor with Slice → Type: Grid By Cell Size, entering the frame size.
5. Build animation clips from the sliced frames by hand.

The same export can be scripted with Aseprite’s command line, for example aseprite -b player.aseprite --sheet player.png --sheet-type rows --data player.json (Aseprite, Aseprite Docs: Command Line Interface). Unity does not read the JSON file by itself, so with this route frame tags and durations have to be recreated manually; this is the main reason to prefer the importer.

Gotchas

• Sprites are tiny or huge next to tiles: Pixels Per Unit was left at 100. Set it to the project PPU.
• Edits in the Sprite Editor disappear: changing pivot settings, sprite padding, resizing a cel, or renaming or removing a layer can overwrite Sprite Editor data on reimport. Aseprite 1.3.14 and later can store layer IDs (“Create UUID for layers” in Sprite Properties) so that renaming a layer keeps the data (Unity Technologies, Aseprite Importer manual: Importer FAQ).
• Blend modes look wrong: blend modes are only supported with Layer Import Mode Merge Frame.
• Hidden layers appear or disappear unexpectedly: hidden layers, and layers inside hidden groups, are skipped unless Include Hidden Layers is ticked.
• Slices defined in Aseprite are not imported.
• Blurry result despite correct import: the problem is then on the camera side; see unity-pixel-perfect-camera.

Related

unity-pixel-art-pipeline · unity-pixel-perfect-camera · unity-tilemap · unity-animator-scripting · pixel-art-animation · pixel-art-fundamentals