Troubleshooting Aseprite For Beginners

This guide addresses problems commonly posed by beginners in forums.

Introduction

Hello,

Thank you for checking out my guide on troubleshooting for beginners. This guide collects together some issues with Aseprite that I've seen reoccur on social media.

Not every issue has a convenient resolution, so before we dive in, let me explain what issues I try to avoid in this guide (but which crop up despite my best efforts):

• Issues purchasing on various platforms (e.g., Steam vs. Humble Bundle), downloading or updating Aseprite, or switching between version branches.
  
• Issues compiling Aseprite from source code.
  
• Hardware issues, such as with a drawing tablet, mouse, HDR display monitor, or multi-monitor setups.
  
• Issues related to the operating system (Windows, MacOS, Linux), such as copying and pasting between Aseprite and other applications, the Aseprite file browser vs. the native file browser, file thumbnails.
  
• Issues related to themes[aseprite.org], especially ones with custom fonts.
  
• Best practices for scripting and debugging in Lua[aseprite.org]. That could be another guide all by itself.
  
• Bugs that have been fixed as of version 1.3.11, which is the current version of Aseprite at time of revising this guide.
  
• Acknowledged bugs or feature requests that have not yet been addressed.

It can be frustrating when the answer to a problem is 'use a Lua script' or 'resort to other software', but in some cases I did not see an alternative.


If you don't know what version of Aseprite you're currently using. Go to View > Help in the menu bar.


In some operating systems, such as Windows, the version will also be shown in the application title bar.

Official Information

The Aseprite customer support page is here[www.aseprite.org].

The official Aseprite documentation on troubleshooting[www.aseprite.org] includes sections on data recovery[www.aseprite.org] and resetting preferences[www.aseprite.org]. There is also a tutorial[aseprite.org] page that addresses common tasks and questions.

The Aseprite Github repository has an issue[github.com] section, which provides the clearest public indication that I've seen of how bugs are being prioritized and addressed.

Social Media

Aseprite also has a presence on social media, such as a community forum[community.aseprite.org], a subreddit, and of course this Steam community. It's always better to follow basic Internet etiquette when posting questions.

• Search to see if your question has been answered, not just with a general Google search, but with the forum's built-in search tools.
  
• If you post the same question across multiple forums, indicate that you've done so, linking to the cross posts, so people don't waste their time retreading the same details.
  
• If you resolve the issue yourself, update the question to say so, including the solution.
  
• Include relevant info like the Aseprite version, the operating system and version and the sprite color mode.
  
• If your question relates to the scripting API, post an MCVE[meta.stackoverflow.com].
  
• If your question involves a workflow across different software, such as a game engine, don't assume that Aseprite is the source of the problem. Name the software that you're using, and include explanations of relevant features, including links to documentation. Don't assume your audience should be familiar with it already.

That said, I hope this can help you get out of a rough spot and back to pixelling!

Keyboard Shortcuts

It's more important to reassign -- and in some cases unassign -- keyboard shortcuts that fit your habits than it is to memorize them. This is especially true if your habits were formed by another graphics editor.

There is a downloadable cheat sheet[www.aseprite.org] available on Aseprite's website. Since the release of version 1.3, it is out-of-date. In particular, shortcuts for working tile sets and tile maps will be missing from the sheet.

Many -- but not all -- Aseprite commands have a keyboard shortcut that can be reassigned.

To open the keyboard shortcuts dialog, go to Edit > Keyboard Shortcuts.


A dialog will open.


In the top-left corner of the dialog, a text input field will let you search for a command by name. Beware that not all commands have consistent names in the GUI versus internally. For example, creating a palette from a sprite is called color quantization.


Change to your preference, then confirm.

I recommend prioritizing the shortcuts for the keyboard shortcuts dialog itself, for the preferences menu, for closing a sprite and for closing Aseprite. I also recommend disabling the shortcut to advanced mode; see below.

A popular command that doesn't have a shortcut is selecting[aseprite.org] an active cel's silhouette -- i.e., its non-transparent pixels. This is currently done by holding down the Ctrl button and left clicking on a layer's name in the timeline[www.aseprite.org].

Keyboard shortcuts can be assigned to Lua scripts[www.aseprite.org], and scripts packaged into plugins[github.com] may include default shortcuts of their own.

Advanced Mode (Missing Menu and Tool Bars)

Aseprite has an "advanced mode" which hides the menu bar and tool bars, depending on which state is toggled. Unless you definitely plan to use this feature, I recommend removing its keyboard shortcut. See the section on keyboard shortcuts above. In the past the default shortcut was listed[www.aseprite.org] as Ctrl+F. In the screen capture above, it is Space+Tab.


To issue an alert when you enter advanced mode, go to Edit > Preferences in the menu, then select Alerts in the left hand column.


If you need to navigate to the edit menu by keyboard, hold down the Alt key and press E, per the underlined 'E' in 'Edit'. For the file menu, it is Alt+F, per the underlined 'F' in 'File'.

Colors Are Weird (Color Mode)

When colors act weird, most of the time, you're in indexed color mode[aseprite.org] but expected to be in RGB color mode. The active sprite's color mode will change many Aseprite behaviors, including palette matching, layer compositing and filters. This can happen if you open a sprite from the Internet without realizing what color mode it will be, then try working off it as a reference.


Go to Sprite > Color Mode > RGB Color to switch.


For new files, pick the appropriate color mode from the new file dialog before you commit.

Colors Are STILL Weird (Color Management)

Even though Aseprite supports color management, as far as I've seen, its color algorithms are designed around the assumption that a color is in standard RGB[en.wikipedia.org] (sRGB).

Don't be surprised If you have a wide-gamut monitor and colors look inaccurate.



General color management settings can be found under Edit > Preferences > Color. Above, the Window Color Profile is set to sRGB, not to current monitor or display profile. The Working RGB Space is sRGB.

If you transfer your work between Adobe Photoshop and Aseprite, you need to take the difference between color profiles[aseprite.org], such as Adobe RGB[en.wikipedia.org] and sRGB, into account.



To check a sprite's color profile, go to Sprite > Properties. The color profile dropdown menu is at the bottom, under the Advanced section header.

When you select a color profile in the dropdown menu that is different from the sprite's current profile, the Assign and Convert buttons will become active.

Pressing the active button will change the profile, but not any colors in the sprite. This will maintain numeric continuity between colors. In other words, the color #AABBCC will have the same hexadecimal code, but may appear different on your display.

The convert button will change the profile and will change the colors in the sprite. This will maintain visual continuity between the colors. The color previously defined by #AABBCC will look the same, but it may have a different hexadecimal code.


To illustrate, here is an image in standard RGB.


Above, the Adobe RGB color profile has been applied to the image.


Above, the sRGB image has been converted to Adobe RGB.

If you compare samples between the converted image and the original, you'll see that #DE0030 becomes #BE0032, #C14F00 becomes #A95013 and so on.


If the converted image loses its reference to the Adobe profile and is assigned sRGB as a default, it will appear washed out.

A sprite can be assigned a profile loaded from an .icc file only through Aseprite's scripting API[aseprite.org]. See the ColorSpace[aseprite.org] constructor which accepts a fromFile parameter. The color space can then be assigned to an ImageSpec's colorSpace[aseprite.org] property.

Canvas Background Checker

Ensure that your sprite canvas checkerboard colors are not similar to colors that you would use in the artwork itself. If you've used digital software for a long time, you've built up a habit, or intuition, that checkerboard means transparent. In this case, that habit can interfere with diagnosing the problem.


To change the checker pattern go to Edit > Preferences.


When the preferences dialog opens up, click on Background in the left hand tab. Then choose your colors and the checker size. Press the Apply button for the changes to take effect.

Take note of the drop down menu at the top of the background preferences. One option is to change the background only for the active document. Another option is to set the default checker for all new documents going forwards.

Indexed Color Mode Transparency

First, to be clear: By transparency, I mean a color with 0 alpha. By opaque, I mean a color with 255 alpha. By translucency, I mean a color with alpha greater than 0 and less than 255.

Aseprite's handling of transparency in indexed color mode has led to a cluster of bugs for a long time. This manifests as problems with .gif export, Edit > FX > Outline, thumbnail previews in the file browser and with selections.

Palette Order

To minimize problems, an indexed color mode palette should have at least one and at most one transparent color. This color should be transparent black, so that all color channels -- red, green, blue and alpha -- are zero. This is so that when the color is represented as a 32 bit integer in the order 0xAABBGGRR, with 8 bits per color channel, it is zero. The color should be located at index zero. This way, whether the color is referred to by its location in the palette or by its color channels, the result is zero.


The palette should be arranged like this.


It should not be arranged like this.

To relocate a color swatch in the palette, click on the color. When you see a border around the color, hover the mouse over the border. The mouse cursor should change to four arrows. Click and drag on the border to move the color. This is easier to do in RGB color mode. If you do this in indexed color mode and the colors on the canvas get screwed up, click the Remap Palette button that appears beneath the palette and above the fore- and background colors.

If it helps to see an animation, go to the Aseprite tutorials[aseprite.org] page, under the section Common tasks and questions, subsection Color/Palette.

Sprite Transparent Color

The first color, clear black, should be the sprite's transparent color. You can tell that a color is the transparent color because it has a little dot in the middle of the swatch. The dot is white or black depending on the color's brightness. Relocating a color will not change the sprite's transparent color.


Instead, you need to go to Sprite > Properties in the menu bar.


Look for Transparent Color under the Advanced section. Click on the color button. When the color picker opens, select the Index button on the far left.

If you have a mouse with a scroll wheel, pressing the wheel like a button, then clicking and dragging, will also relocate the transparent color.

Background Layer

The issue is complicated by background layers. In RGB color mode, a background layer is assumed to be opaque. In indexed color mode, the sprite's transparent color is ignored by the background layer; however, a background layer can have transparency or translucency if colors in the palette do. If you use a background layer in indexed color mode, treat it as you would in RGB color mode; use opaque colors on the layer.


Above, the palette and the background layer contains translucent and transparent colors. If you look at the status bar[www.aseprite.org] on the bottom, the problem is worse than first appears. The status bar shows information from the Eyedropper[www.aseprite.org] tool. Not only is the eyedropper selecting a transparent color, if you recreate this scenario, you'll find it distinguishes index 14 in the circle on the right, from index 2 in the circle on the left, from the transparent color at index 0.

Selections

To debug the selection[aseprite.org] tool, make sure the tool is active, then look at the context bar[aseprite.org]. First check that the Transparent Color Options are set correctly


then check that the transparent color matches that of the sprite

Outlining

A similar check can be done with the outline effect.


This result


is quite different than this one


while this one shows what can happen with a malformed palette.

Compositing

Above is an example of layer compositing issues in indexed mode. The blue dot cel has an opacity of 180; the green dot cel has an opacity of 128. The green layer uses the Subtract blend mode[aseprite.org].


This is the result of exporting the image to a png, then reopening it in Aseprite. It is also what happens when you select Layer > Flatten Visible.


To resolve this issue, wait until you're finished your artwork. When done, convert from indexed color mode to RGB.


Create a new palette from the sprite.


Ensure that colors from the sprite contain alpha.


Flatten your layers in RGB color mode.


Convert back to indexed color mode.


If you want, flatten the sprite layers first, then get the colors from the sprite. The order of these two steps doesn't seem to matter.

Gif export issues will be covered in a separate section below.

I recommend deciding on your palette prior to working in indexed color mode. Remove any translucent colors from the palette. Avoid using cel or layer opacity. Avoid layer blend modes. Avoid alpha compositing inks. In short, work within the constraints of the aesthetic; do all color mixing manually.


For example, consider replacing partial opacity blends with dithering, whether that be horizontal or vertical lines, or a one-by-one checker.

Gif Export Problems

While any graphics editor, Aseprite included, will have limitations or bugs in its image export routine, more likely this problem is more to do with the gif format itself.

Animation Speed

If animation speeds in Aseprite don't match with the export, first check that sprite playback is at 1x speed, not slowed down or sped up. This menu is found by right clicking on the play button in the timeline[www.aseprite.org].


You may also consider, if you are working on a complex sprite with many layers, blend modes and frames, whether the time taken to render the composited frame is slowing down playback.


I've heard one suggestion to play the animation through the preview window[www.aseprite.org], not the main editor, but I've not confirmed that it makes a difference.

To open this window, go to View > Preview > Preview. In the top right corner, the zoom and play control buttons are to the left of the close button.

Research the limitations of the gif format. Each frame should be at least 20 milliseconds in duration; in other words, a maximum of 50 frames per second (FPS). If you're inclined to measure your animations in frames per second, the difference between integer and floating point arithmetic will throw your measurements off. For example, 24 frames per second is 1000 / 24, or approximately 41.667, milliseconds. However, the duration will be truncated to an integer 41 milliseconds in Aseprite. gifs store duration in centiseconds, or 1 / 100th of a second, so the example frame rate will be truncated further still to 40 milliseconds.


To change the frame duration, go to Frame > Properties or Frame > Constant Frame Rate.


The difference between the two is that frame properties will allow you to set the duration for a range of frames you've selected in the timeline, while constant frame rate will set the duration for all frames.


Lastly, when you go to File > Export > Export As, look at the Export for Twitter option, which, according to the tool tip, alters the final frame duration.

Color

First, read the section Indexed Color Mode Transparency above. Read this even if the sprite is in RGB color mode.

gifs exported from Aseprite should have at most 256 colors. gifs in general support 256 colors per frame. However, for Aseprite, the total is 256 across all frames, for the final flattened and composited image. Any more than that, and the sprite colors will be reduced to fit.

gifs do not support translucency. A color may be transparent or opaque, but nothing inbetween.


If your sprite uses smooth gradients, try dithered gradients instead.


With the gradient tool active, look in the context bar[aseprite.org]. The dithering menu can be found to the right of the gradient type buttons (radial or linear).


Custom dithering matrices[aseprite.org] can be installed as an extension[aseprite.org]. For example, see those by JJ Haggar[bitbucket.org].


Multi-color gradients require a third-party solution, either a Lua script[aseprite.org] or another graphics editor.


Using the pencil tool, a gradient can be assigned to pressure or velocity in the brush dynamics menu in the context bar.

Alerts

It may help to set the alerts for gif files.


Go to Edit > Preferences.


This will open the preferences dialog window. In the left hand column, select Alerts. Near the bottom, by Show options when saving files, mark gif as true.


When you export, a window will pop up with the options Interlaced, Animation Loop and Preserve palette order. The last option will be grayed out unless you're in indexed color mode; it has caused problems[community.aseprite.org] in the past.

Palette Count

If you save a sprite to a gif, then reopen it, you may notice the palette change in size. Palette sizes are usually promoted to the nearest greater power of 2. For example, a palette with 42 color swatches will grow to 64 colors, or 2 to the 6th power.

Alternatives

If you don't like the gif's limitations, as far as I know the only other export option in Aseprite that supports animation is webp. You could also export a sprite sheet, but you'd have to store any frame duration in an extra data format.

Bmp Export Problems

The bmp file format has been around a long time. This leads to compatibility problems. Instead of giving you direct control over bmp file's format, Aseprite assumes a format based on your sprite.


If the sprite is in indexed color mode, it writes an indexed bmp. The number of bits per pixel (bpp) depends on the length of the palette. For example, a sprite with greater than 2 and less than or equal to 16 color swatches will use 4 bpp.


If the sprite is in RGB color mode, Aseprite checks for a background layer. If a background layer is present, it writes a 24 bpp file that uses an older and commonly recognized header[learn.microsoft.com]. If Aseprite believes that your sprite might contain transparency, then it writes a 32 bpp file with a less common header[en.wikipedia.org]. This header may not be recognized by other graphics software.

bmps do not have a grayscale format, so gray color mode sprites will be quietly be converted.

There is no direct support for writing 16-bit bmps, so either use a script[github.com] or a program like GIMP.

Pixels 2x Scale When Measured

If you screen capture Aseprite, you'll likely find that pixels are twice as large as you expect them to be. Below, each pixel is 16 by 16, even though the zoom is only 800%.


This is likely because Aseprite defaults to 200% screen scaling. In the preferences dialog, under the General tab, change the screen scaling to 100%. If icons in the user interface look too small, then set UI Elements Scaling to 200% instead.


The dialog can be found under Edit > Preferences.

After you update the preferences, if palette swatches are too small in the color bar[aseprite.org], then go back to the preferences dialog. In the General tab, click on Locate Configuration File. Close Aseprite. Open the aseprite.ini file in a text editor. You can increase the size manually by changing "box_size" in the "color_bar" section. See this thread[community.aseprite.org] for more.

Images Blurred on Social Media

This has nothing to do with Aseprite and everything to do with the assumptions made by Internet browsers and social media sites. The assumption is that images are high resolution photographs, or should be.

When an image is too small, a method to scale it up is chosen according to that assumption. And while there are many methods, a basic one for scaling photographs is bilinear interpolation. An image can be thought of as a grid with color data in each grid cell; when that grid increases in size, the color data becomes sparse, and new colors need to be created to fill in empty cells. Bilinear interpolation does this by sampling neighboring cells and mixing the colors together, first horizontally, then vertically.

Pixel art, by contrast, works best with nearest neighbor interpolation, also referred to as point sampling. This type of sampling does not mix existing colors to create new colors. It only chooses between existing colors in the image.

A better explanation is provided in this video from Computerphile.

So you have to scale the image prior to giving it to a social media site. In-progress work should be saved with the aseprite file extension through File > Save or File > Save As. Completed work should be exported through File > Export > Export As.


For exporting, a dialog window will pop up.


Resize is one of the options. It ranges from 25% (1/4x) to 1000% (10x) and it uses nearest-neighbor interpolation or point filtering.


A sprite can also be scaled prior to export by going to Sprite > Sprite Size.


The interpolation method can be found in the drop down menu at the bottom.


The sprite size dialog should not be confused with the canvas size dialog. The latter changes the size of the sprite's canvas, but does not scale any of its contents.

Upscaling is usually not a problem for exporting to game engines. However, for game engines that specialize in 3D rather than 2D games, you may need to read the documentation on how to change the default image import settings. Do not assume that because an image looks incorrect in the game engine that the problem is on Aseprite's end.

Snap To Grid Works Improperly

Beginners often do not understand how to properly get around the blurry images problem above. So what they try to do is work with upscaled pixels. For example, they create a 256 x 256 image when they want to work in 64 x 64, then work in 4x4 pixel blocks. They complain when, for example, the line tool doesn't snap to grid in a way that fits with this workflow.


In the screen capture above, beginners want the red line, left, to look like the green line, right, when snap to grid is enabled.


Do not waste your time trying this. The toolbar contains a zoom tool which lets you increase small images' size in the editor. The default keyboard shortcut is Z.


When either the zoom or hand tool, keyboard shortcut H, are active, the context bar[aseprite.org] will contain three buttons that are also helpful: 100%, Center and Fit Screen.

The downsampling is relevant when you are zoomed out and you want to specify how Aseprite should sample pixels that are smaller than a screen pixel.


If you want to view art at two different zoom levels as you work, consider opening a preview window under View > Preview > Preview. You can also create a split workspace[www.aseprite.org] by dragging and dropping sprite tabs.


If you need to enable or disable snap to grid, go to View > Grid > Snap to Grid. As you can see from screen shots above, when snap to grid is enabled a "Disable Snap to Grid" button will appear in the bottom right corner of the canvas.

Downscaling An Image

If you need to scale down an image in Aseprite, choose the marquee selection[aseprite.org] tool.


Then, click and drag to measure the size of a scaled pixel in the image.


The status bar[aseprite.org] on the bottom of the application will indicate the width and height of the selection, 16 x 16 in this case.


Then go to Sprite > Sprite Size in the menu bar.


Like many other numeric inputs in Aseprite, the sprite size width and height allow you to enter mathematical expressions. For example, in the image above, 320 / 16 will be calculated as 6.25% scale or 20px on your behalf.

Beware of jpg or jpeg images for this reason. The compression in these file formats will blur pixels, making it difficult to find an appropriate measure.

Pencil and Eraser Problems

The context bar[aseprite.org] is a horizontal bar of extra options that appears above the sprite canvas and below the open sprite tabs. The options available depend on the active tool.


For the eraser tool, opacity can be counter-intuitive. Check that your eraser's opacity is 255, not 0.


For the pencil tool, much depends on which ink[aseprite.org] is active. Be sure that the ink type is Simple Ink, not an ink which requires there to already be color on the canvas, e.g., Lock Alpha or Shading. If the ink type enables an opacity slider, check that its opacity is not 0.


In the color bar[aseprite.org], ensure that the foreground color's alpha is greater than 0. Above, the reticle for the bottom-most bar with the checkered background is at the far left, meaning the color is transparent.


If you've enabled dynamics, check that the settings match your expectations. For example, if gradient is enabled, the color on the canvas may not match the fore- or background color. If the pencil feels delayed or laggy, reduce or turn off the stabilizer.


If the eraser or pencil's shape seems jagged, off-center, the wrong size or pixel perfect doesn't seem to work, check that the brush is not rotated. For square shaped brushes, rotations of -180, -90, 90 and 180 degrees will change the brush's shape, even though they shouldn't.


If the eraser leaves behind an opaque color, but can't erase to transparency, then check the timeline[www.aseprite.org] to see if you're working on a background layer. A background layer is underlined and is usually named "Background." It can be converted to a normal layer by going to Layer > Convert To > Layer in the menu. You can also right click on the layer's name in the timeline and select the conversion from the menu.


Also check that the layer is not hidden or locked. A layer's visibility is indicated with an eye icon. A layer's editability is indicated with a padlock icon.


You may have created a selection unknowingly and are attempting to draw outside that selection. Go to Select > Deselect in the menu bar if this is the case.

Paint Bucket Problems

If the paint bucket is filling outside certain regions, first look at the context bar[aseprite.org] when the paint bucket tool is active.


Ensure that the contiguous box is checked. When it is not checked, the paint bucket will fill disconnected islands of color. Then, ensure that the tolerance slider is zero. When tolerance is high, the fill will escape enclosing edges when the fill and the edge color are considered to be similar.


Next, check the fill options menu. Pixel connectivity refers to how a pixel checks its neighbors to see if it is within an edge or not.

When refer visible layers is true, the paint bucket refers to the sprite's flattened composite; otherwise it refers only to the active layer. When the paint bucket refers to the active layer, you'll want to check that you're on the correct layer.

The paint bucket also has an ink type option. So you need to troubleshoot that in the same way as the pencil tool in the previous section.


Symmetry[aseprite.org] alters fill behavior. Disable this if fill is behaving unexpectedly.


If you learn through experimentation, it may help to create a few shapes like the ones above, then test your paint settings. Note that the inner, cut-out edges in the image above are actually on a separate layer from the outer edges.

Eyedropper Problems

First, check the context bar[aseprite.org] while the eyedropper[aseprite.org] tool is active.


The sample can be drawn from the active layer, current layer, or from a reference layer.


There may also be an issue with how the eyedropper is representing color. For example, if the eyedropper selects the nearest match to the active palette rather than the color itself.


In the example above, the eyedropper finds #916583 with an alpha of 247 when placed over the intersection of the three circles and all layers are sampled. This information is displayed in the status bar[aseprite.org] at the bottom of the app. Were the active layer sampled instead, the color hex code would be #58B055.

The eyedropper is subject to issues with color management; see the section Colors Are STILL Weird above.


If you copy and paste pixels, and the content is surrounded by the marching ants of a selection, but you've not yet confirmed the paste, then the eyedropper may not register the color. In Aseprite, any selection is potentially transformable. Since transformations are destructive operations, they have a preview phase until confirmed. See the section Filters and Transforms Only Apply to Active Layer.

Jagged Strokes When Zoomed Out

Aseprite is designed to create pixel art. It is not a general painting program. It assumes that most brush strokes will be made at 1x zoom at least.


When brush strokes are made while zoomed out, the stroke may have abrupt diagonals. When you zoom back in on the canvas, this becomes apparent.


For less extreme cases, these artifacts can be somewhat reduced by setting the Screen scaling to 100% in general preferences. UI Elements scaling can be increased after if icons are too small to see.


For the pencil tool, enabling Pixel-perfect in the context bar[aseprite.org] or the Stabilizer in the Brush Dynamics menu may also mitigate the issue.


This problem crops up when users don't understand how to work at 1x zoom and upscale upon export. See also the sections Snap To Grid Works Improperly and Images Blurred on Social Media.

Color Bar or Timeline Fills Screen and Can't Be Moved

Usually when a panel fills the entire screen, you can hover over the panel edges with the mouse cursor. If the cursor turns to a double-ended arrow, then clicking and dragging will change the panel's size.


If that doesn't work, then go to Edit > Preferences.


In the left hand column of the preferences dialog, select General.

Click on the link Locate Configuration File, near the bottom. This should open an operating system file browser. Close the preferences window.

Close Aseprite. This is important because you want to prevent Aseprite from changing the configuration file while you make manual changes.

In the file browser, open the aseprite.ini file in a text editor or code editor, such as Notepad++[notepad-plus-plus.org] or Visual Studio Code[code.visualstudio.com].


Use the editor's search functionality to find "layout:main_window". Under this heading you'll find the partitions for the color bar[aseprite.org] and timeline[www.aseprite.org] in pixels. If the numbers are large, set them to a small amount, say 64 pixels.

Bear in mind that reasonable pixel values should be in accord with Aseprite's theme, screen scaling and UI scaling, and your display monitor's size in pixels. Screen scaling and UI scaling can be changed in the ini file, or in general preferences as pictured above.

If you can't see the OK, Apply or Cancel buttons in the general preferences dialog, you can use keyboard shortcuts: Alt+O for OK, Alt+A for Apply, Alt+C for Cancel. You can also navigate the preferences dialog via keyboard with the Tab key.

Timeline Thumbnails and Overlays

Sometimes it's handy to see layer[aseprite.org] thumbnails in the timeline[aseprite.org], so you can tell which pixels belong to each layer. This works best when the timeline is docked to the left or right of the canvas.

However, when the timeline is docked on the bottom, such as when you're focusing on animation, these thumbnails take up a lot of room.

It's also possible to activate thumbnails by mistake, by holding down Ctrl and moving the scroll wheel when the mouse is over the timeline. The scroll wheel will increase and decrease thumbnail size.


To turn off thumbnails or adjust their size, click on the timeline options menu button, which looks like three horizontal sliders, above the layer names. This is also how you can change where the timeline is docked.


The overlay setting may also be a compromise option, as it only displays a thumbnail on mouse hover over a cel. Overlays work even when the Thumbnails checkbox is not ticked.

Colors Out of Order in Palette Loaded from Image

The easiest way to maintain the ordering of a palette's color swatches is to use a gpl or pal file format. An advantage of these files is that they are human readable if you open them in a text editor. A disadvantage is that they are not color managed.

GIMP Palette
Name: RYB
Columns: 4
255 0 0 FF0000 1
255 106 0 FF6A00 2
255 162 0 FFA200 3
255 207 0 FFCF00 4
255 255 0 FFFF00 5
129 212 26 81D41A 6
0 169 51 00A933 7
21 132 102 158466 8
17 89 166 1159A6 9
60 42 146 3C2A92 10
105 12 133 690C85 11
170 0 85 AA0055 12

If you have a palette stored as an image, don't load it into Aseprite as a palette through the hamburger menu in the color bar.


Instead, load it as a sprite via File > Open. Then go to the hamburger menu, select New Palette From Sprite.


A dialog window will appear. Change the RGB to palette index mapping from the default Octree to Table RGB 5 bits + Alpha 3 bits.


Hopefully the order will match your expectations. It helps if you expect colors to be in rows and columns starting at the top-left corner and proceeding row-major, column-minor to the bottom-right corner. Save the palette to a different format if and when satisfied.


Some palettes are arranged as a network of ramps. For example, see AAP-64 by Adigun A. ♥♥♥♥♥♥[lospec.com].

For such cases, it may be better to drag and drop sprite tabs into a split workspace[www.aseprite.org].


A split workspace can come with UI/UX issues of its own. In particular, make sure both the palette image and working sprite are the same color mode and have the same palette. As pictured above, check the eye dropper's context bar[aseprite.org] to make sure color is being sampled from an image per your expectations.

Inconsistent Grayscale

A color's gray value depends on where and how you measure it.

For an individual color examined in the color bar, Aseprite uses the HSL lightness calculation (max(r, g, b) + min(r, g, b)) / 2. For example, the sRGB color #FEAE14 will have a lightness of about 53%, or about 137 out of 255 in grayscale.


To see multiple color representations simultaneously, hold down the Shift key and select the tabs in the top left of the bar, in this case RGB, HSL and Gray. The sliders can be undocked from the bottom left corner by hovering in the area between the hex entry field and the close button, then clicking and dragging once the mouse cursor changes.

To convert a sprite to grayscale, Aseprite provides three options: HSL, HSV and Luminance. HSV uses max(r, g, b) and Luminance uses a weighted average. Luminance is the default. If you place #FEAE14 on the canvas, then convert to grayscale with the default, the color #B3B3B3, or 179 out of 255 in grayscale, is the result.


To change which conversion Aseprite uses, go to Sprite > Color Mode > More options.


In the dialog window, select Grayscale, then choose your preferred method.


Certain layer blend modes[aseprite.org] use yet another calculation. For example, if you fill a layer with #FEAE14, then create a new layer above it and fill it with white, then change the top layer's blend mode to Color, you'll get a slightly different result, #B5B5B5, or 181.


You can also access a layer's properties by right clicking on its name in the timeline and selecting from the menu.

I've addressed the topic in greater detail here: https://steamcommunity.com/sharedfiles/filedetails/?id=3014911194

Palette Matching Woes

Aseprite will match a sprite canvas to the palette when you convert to indexed color mode. Matching is not done outside this context, so you can't, for example, match a single cel or layer, without a script.


Indexed images allot 1 byte, or 8 bits, to each pixel. They can reference palettes with at most 256 colors. Aseprite can load a palette with more colors than this limit, but when the sprite canvas is matched to the palette, only the first 256 colors will be used. If this is the case, try software that matches to bigger palettes.


Minor improvement may come from ensuring that the palette contains a transparent color in the initial index, as described in Indexed Color Mode Transparency.

Background

Matching the colors in an image to those in a palette is a complex task. Different graphics editors will match with different color models (e.g., CIE LAB[en.wikipedia.org] vs. sRGB[en.wikipedia.org]), partition and search methods (e.g., octree[en.wikipedia.org]) and distance metrics (e.g., Euclidean). Overarching all these choices is the choice of how to balance quality against computational speed. Imagine waiting more than a couple of minutes for a 1000x1000 pixel sprite with 32 frames to load because the palette matching algorithm is slow. Furthermore, depending on the source image and the palette to be matched, the faster, naive algorithm might give better results than the more complex method.

As far as partition and search methods go, graphics editors run into issues with when to engage them. Searching through colors often involves reordering them in such a way as to speed up the search. Octrees, for example, organize colors into boxes that nest inside each other in 3D space. That's why storing palettes as images is a problem -- see above.


To illustrate potential problem areas, take this source image of a flattened sRGB color cube.


Under Sprite > Color Mode > More Options, you can select a dithering option from a dropdown menu. With the Color Best Fit Criteria, you can select a more accurate match, CIE LAB, or a faster one, RGB. For example, here is the sample image matched to a variant[github.com] of Apollo by Adam C Younis[lospec.com].


Then, with a CIE LAB match.


Then, with a Floyd-Steinberg dither[en.wikipedia.org].


Through an extension, a custom dither matrix[aseprite.org], can provide more options for an ordered dither.

Quantization

Palette matching is different from color quantization. Color quantization can be used as a preparatory step to speed up palette matching, as looks to be the case with Aseprite. Color quantization is possible in just about any representation where values have a definite lower and upper bound. For example, below is a quantization in Okhsl[bottosson.github.io]:


However, in pixel art, much of the focus is on reducing the bit depth of colors in sRGB. Below on the far left, the image is quantized to two levels, or one bit, per channel: 0x00 (0b0) or 0xff (0b1). To the right, it is quantized to four levels, or two bits, per channel: 0x00 (0b00), 0x55 (0b01), 0xaa (0b10) or 0xff (0b11). And so on.


If you use palette matching as a surrogate for color quantization, it's better to find a script or other graphics editor that quantizes directly. This holds especially for any bit depth greater than 8. For example, a 3-3-2[en.wikipedia.org] bit depth will work within indexed color mode. A 3-3-3[en.wikipedia.org] bit depth with 512 colors will not.

Even with quantization, Aseprite colors are 32-bit RGBA. In indexed color mode, the 8-bit canvas refers to a 32-bit color palette. Quantization only simulates lower bit depth. A Lua script is necessary to export to a file format that supports lower bit depths, such as a bmp[github.com] or ppm[github.com].

Palette Export Problems

Despite having the same file extension, Aseprite files that end in .ase do not follow the same file format as Adobe Swatch Exchange palettes. To import and export .ase palettes, use a Lua script such as this[github.com].

When Aseprite exports a GIMP[www.gimp.org] palette with the .gpl extension, it does not give the palette a name. In graphics editors that name palettes and swatches, such as Krita[krita.org], this will cause an error.

When your palette contains a color that is either translucent or transparent, i.e., has less than 255 alpha, then Aseprite will use a special subset[github.com] of the .gpl or .pal format. This subset includes the alpha as a fourth color channel. This palette may fail to load, or the alpha channel may be misinterpreted as part of the swatch's name.

Filters and Transforms Only Apply to Active Layer

There is a longstanding limitation with Aseprite's renderer where the preview will show changes only for the active layer. However, once the transformation or filter is committed, it will impact either the selected elements or all elements, per your choice.


For filter dialogs, the Selected to All toggle is located beneath the OK, Cancel and color channel selector buttons.

If you're new to pixel art, it's easy to forget that the transformations[www.aseprite.org] rotate[www.aseprite.org], skew and scale[www.aseprite.org] are destructive. Their destructive nature is much easier to see in pixel art than in high resolution raster graphics.


That is usually why the transformation tool has a cancel and confirm button in the context bar[aseprite.org]. Until you hit the confirm button, what you see is a preview of the changes. Note that, unlike other context bar information, this information will not appear when you choose the selection tool; it will appear after you make a transformation.

Skew Transform Erases Selection

If a skew transform[www.aseprite.org] erases the selected image, and nan or -nan appear in the input fields in the context bar[www.aseprite.org], then try resetting the pivot[www.aseprite.org] to the center.

Hue Saturation Adjustment

The hue/saturation adjustment is found under Edit > Adjustments.


When selected, a dialog like this opens.

In indexed color mode, the adjustment targets the colors in the palette, not those on the canvas. To isolate certain colors, select the swatches you want to change in the color bar[aseprite.org] prior to opening the adjustment.

The difference between the modes with the plus sign, +, and those without, is in how they treat gray colors. Modes with the plus sign saturate gray colors and treat their initial hue as red, i.e., zero. Modes without the plus sign leave grays as grays.

If you are comparing the hue/saturation adjustment in Aseprite to that of another graphics editor, then read the Colors Are STILL Weird section first.

HSL and HSV[en.wikipedia.org] are deeply flawed ways of representing color. Some graphics editors will include options to compensate for these deficiencies, such as a "preserve lightness" feature, or will use HSY instead, where Y stands for relative luminance.

If you're a beginner learning about color value[en.wikipedia.org], do not use this adjustment to desaturate or to resaturate images. If, for example, you are depicting a screen across four seasons or across a day-night cycle, do not use this adjustment. To show why not, below is a tree created by Michele "Buch" Bucelli and sourced from Open Game Art[opengameart.org].


On the far left is the original tree sprite. In each column, the hue is shifted by 30 degrees. Aseprite's adjustment is on the top row. The Okhsv and Okhsl[bottosson.github.io] adjustments were made with a Lua script from this code repository[github.com]. The SRLCH[www.magnetkern.de] adjustments were made with a script from this repo[github.com]. On the bottom row, the Krita[krita.org] adjustment uses Hue/Saturation/Luma option.

The primary objection against HSV and HSL is that they do not measure a color's lightness correctly. This causes color values to change for the worse as hues change. Notice especially in the ranges 150 to -90 degrees above. However, as the Okhsl and Okhsl adjustment show, it is also important to preserve consistent chroma -- rather than saturation, which is more of a relative percentage -- as hues change.

Note also that different color spaces distribute hues differently on the color wheel. For example, in Okhsl, red is about 29 degrees hue; in SRLCH, about 41.

Reference Layers

A reference image can be imported by going to Layer > New Reference Layer from File.

Reference layer images depend on the color mode[aseprite.org] of the sprite that contains them. For example, a reference layer imported into an indexed color mode sprite will be palette-matched. Reference layers can be translated with the move tool[aseprite.org]. They can be scaled by clicking and dragging on the bottom-right corner with the move tool. They cannot be rotated.

A reference layer's opacity and blend mode[aseprite.org] can be changed like any regular layer's, through Layer > Properties.

If you do not want to deal with these restrictions, you need to find another, third-party solution. I have not tried PureRef[www.pureref.com], but this is the most frequent recommendation I've seen.

I don't know of an easy way to convert a reference layer to a normal layer except through Lua script[github.com].

Slices

Slices[aseprite.org] have been a buggy, incomplete feature for as long as I can remember. I do not recommend using them, particularly with sprites that contain multiple frames.

If you use slices for meta-data when exporting to a game engine, I suggest a script-based[aseprite.org] approach instead, including but not limited to custom user data or a custom export.

An exception is if you are developing a custom theme, in which case you'll encounter slices when editing the theme's icon sheet.

Opening Indexed Images As Sequence

At some point, the Aseprite developers seemingly experimented with, then abandoned, the possibility of multiple palettes per sprite.

You can stumble onto this feature accidentally if you open a sequence of images that use indexed color mode. If all the images have the same palette, you may not even realize that multiple palettes are being used.

Because this feature was never fully developed, and can cause issues if you use a non-zero sprite transparent color, it should be avoided.


Open the Edit > Preferences dialog.


Go to the Alerts section in the lefthand column. At the top of this section, a dropdown menu is labeled "Open a sequence of static files as an animation." There are three options: yes, no and ask. At the very least, I recommend changing this to ask.

More info can be found at this thread[community.aseprite.org] on the community forum.

Onion Skin Woes

The onion skin[aseprite.org] is toggled on and off by pressing the icon of overlapping frames in the timeline[aseprite.org] that is beneath the play button and above the stack of layer names. Onion skin options can be found in the timeline options menu, to the left of the on-off toggle.


I recommend turning off Loop through tag[aseprite.org] frames when convenient. Even if it weren't buggy for some tag directions, it makes the onion skin display counter-intuitive. This preference is based on each sprite, not on the application as a whole, so a Lua script[aseprite.org] is needed to turn it off consistently.

The opacity and opacity step are important for how many frames you want to see skinned. In the image above, the initial opacity is 68, while the decrement step is 28. If you work out the math for the sequence -- 68, 40, 12 -- the onion skin will go for three frames before it drops below zero alpha.


While you can extend the onion skin by clicking and dragging on the brackets that appear around the frame column headers in the timeline, it won't matter until you either raise the skin's base opacity or reduce its step.

Tile Map, Tile Set Woes

Tile maps[aseprite.org] and sets are a new feature in Aseprite version 1.3. For that reason, documentation and tutorials are less common than other features.

First and foremost, a tile set is not the same as a tile map.


A tile set is a one-dimensional collection that contains only unique tiles, i.e., no duplicates. The tiles are in no particular order, and can be rearranged[aseprite.org] just like colors in a palette. Blank tiles are an exception to these rules. The tile at index zero is always blank. A tile set can contain multiple blank tiles; dragging the double vertical bars at the end of the tile set will append more.


A tile map is a two-dimensional collection of indices that reference a tile set. It can contain duplicate indices. It also allows a small amount of meta-data which directs a renderer to flip tiles horizontally, vertically and diagonally. Through a combination of these flips, 90 degree rotations can also be supported.


In Aseprite, a tile map is a special type of layer. A special icon identifies it in the timeline[aseprite.org]. For each new frame on this layer with a cel, there is a new tile map image. A sprite can contain multiple tile maps that reference multiple tile sets. More than one tile map layer can reference the same tile set. Each tile set can contain tiles of different width and height.

Individual tiles are not animated, as is the case with other tile map systems. A tile set does not have multiple layers, so for example, associating a diffuse and normal tile map would require custom tooling.


A new tile map layer can be created under Layer > New > New TIlemap Layer.


An existing layer can be converted to a tile map via Layer > Convert To > Tilemap. A background layer must be converted to a regular layer before it can become a tile map.

For either choice, a similar dialog will follow.


This menu lets you select an existing tile set or create a new one.

If your goal is to export to Tiled[www.mapeditor.org], note that Tiled renders tile sets with varying widths and heights in the same file differently than Aseprite.


You can also go to Layer > Properties, then click on the tile icon to the right of the blend mode to select which tile set the map references and edit most of the properties of that set.


Once a tile set is created, its tile width and height cannot be changed. A workaround for this is to convert the layer to a normal layer, then convert it back using new dimensions. This workaround is also useful for sorting a tile set according to a tile's first appearance in a tile map.


To manage all the tile sets in a sprite, go to Sprite > Properties.


The list of tile sets includes the tile map layers that reference each. Hovering over a set in the list will make a Duplicate and Delete button appear.


To display the flipping flags and tile index numbers on the canvas, go to View > Show and select Tile Numbers. View > Show > Layer Edges must also be active.


When the proper tile editing mode[aseprite.org] is active, the default keyboard shortcuts to flip the foreground tile before painting on it on the tile map are Space+X for horizontal flips, Space+Y for vertical flips and Space+D for diagonal flips. Space+R rotates the tile 90 degrees clockwise.

Whether the Show Tileset button pictured above is selected can greatly change how some tools work, or whether they work at all.

The other editing modes are explained by the tool tips that appear when the mouse hovers over the buttons:


Manual modifies existing tiles, but doesn't create new ones automatically.


Auto reuses existing tiles, but creates or removes tiles where appropriate.


Stack prioritizes creating new tiles over modifying existing ones.


The palette menu contains a feature that will highlight tiles in the tile set that are in use.


The tile set export feature is under File > Export.

I do not find this export useful, so I use a script[github.com] to export tile sets and maps to Tiled. Tiled's file formats are in XML, and the documentation[doc.mapeditor.org] explains all you need to know. Tile flipping flags[doc.mapeditor.org] are the same between Tiled and Aseprite for orthogonal maps.

2,3221225475,1610612739,
2684354562,2684354563,3,
3221225474,1610612738,0

Regardless of your export target, the core idea is to export the tile map as data, not as an image. Above is a csv[en.wikipedia.org] formatted tile map, where the larger numbers are due to the flipping flags being composited with the tile index.

There is no import for either tile maps or sets. About the best you can do is open an image containing a map, set or both, then convert the layer as described above.

Lua Script Installation

Lua scripts[aseprite.org] are typically installed by going to File > Scripts > Open Script Folder. After the files are pasted into that folder, then Aseprite is updated by going to File > Scripts > Rescan Scripts Folder. Some are packaged into extensions or plugins that are installed through Edit > Preferences, under the Extensions tab.

If you have copy and pasted code from a website, ensure that the code is not subject to a formatting issue. For example, when copying from Github, look at the raw code. Also make sure that the code is saved with the file extension lua. Sometimes a txt extension will be surreptitiously added to a file, such as "myFile.lua.txt". Getting to the root of this problem is made harder by operating systems that default to concealing file extensions.

If the file path of Aseprite's script folder contains a character that is outside of the basic ASCII character set, such as an e with an umlaut, then that may be the cause of scripts not loading.

For plugins especially, read any instructions provided by the plugin's developer. Contact the developer first if you encounter issues before asking on a public forum.