Heos Text

V2. Small addition: There was already a line break in use, but it was a bit awkward to use (\n). Now, a shortcut button has been added for this, and it doesn't lose focus on the text box, making it more convenient.

I hate Aseprite's built-in text input feature. You have to guess the size, and the window closes as soon as you apply it… if you want to adjust it, you have to reopen the text input window, and not all the settings are saved. I've tried to fix that with this script. It only has two embedded fonts, but I've also added an easy way to create and use your own fonts in various sizes.

Heos Text is a Lua script for Aseprite that renders bitmap text with live preview, custom fonts, and template generation. Perfect for adding crisp, readable typography to pixel art without the frustration of Aseprite's native text tool.

---

Workflow

1. Open a sprite: Make sure it is in RGB or Grayscale mode (indexed sprites are not supported).
2. Type your text: Write your message in the text field. Use \n for line breaks.
3. Pick a font: Choose between the two built‑in fonts or a custom one you have loaded.
4. Adjust style and position: Change scale, spacing, color, alignment, and margins.
5. You don't need to click “Allons-y!” to save the text, but it's there just in case. You never know. 
6. Edit or clear: Change any setting to update live. Press Clear to remove the text layer.

---

How the Font System Works

The script comes with two built‑in fonts: Heos 5x7 (real lowercase, includes Ñ/ñ) and Heos 3x5 (small‑caps style, also includes Ñ). You can also load your own fonts from an image sheet.

Loading a custom font: Use the "Template" button to generate a blank sprite sheet with a grid and the characters you need. Draw your glyphs inside each cell on the "Font" layer (the faint guide lines are ignored during import). Then go back to the script, pick the image file, set the correct cell size, and press "Load font". The font will appear in the dropdown.

Auto‑fit: When loading, this option automatically trims empty space around each glyph, making proportional fonts easier to create.

---

⚠️ Important – Loading a Custom Font

Just selecting an image file is not enough. You MUST click the "Load font" button after choosing the file. The template is only a guide for drawing; the actual font is imported only when you press Load font.

---

Parameters

Text: The string to render. Use \n to break lines.
Scale: 1 to 16; multiplies each pixel of the glyph.
Spacing: Extra pixels between characters (0 to 4).
Color: The main text color. Not used if "Original color" is enabled.
Original color: Keeps the original colors from a loaded font instead of using the solid color.
Align: Left, center, or right horizontally.
V‑Align: Top, middle, or bottom vertically.
Margin X / Margin Y: Offset from the edges (in pixels, before scaling).
Cell W / Cell H: The width and height of each glyph cell in the source image (when loading).
Charset: Which character sets (uppercase, lowercase, numbers, special) to include when generating a template or loading a font. Use the "Edit" button to customise the characters in each set.

---

Tips

When designing your own font, draw only inside the cells. Use a background color that is clearly different from your ink (for example, bright magenta) and set that color as "Bg" in the Load tab – this helps the script ignore the guide lines. Turn on Auto‑fit for proportional fonts, turn it off for monospaced fonts.

The script respects the sprite's colour mode (RGB or Grayscale). This allows you to create fonts that are much more creative and rich in detail—or maybe even something that isn't strictly a font? The text layer is updated live, so you can tweak parameters while seeing the result. Use the "Clear" button to completely remove the text layer when you are done.

You can use the script to animate text. Type a letter, create another frame, and type the next one. You can also move the text or change its color. 

---

Compatibility

Requires Aseprite 1.3.x or later. Works with RGB and Grayscale colour modes. Indexed sprites are not supported.

---

Examples

If you create a font using the template, please let me know in the comments (including the size), and I'll be happy to link to it.

---

Feedback & Support

I love seeing how you use Heos Text in your projects. If you have questions, ideas, or just want to share what you've made, feel free to leave a comment or reach out directly. It's always great to see your work in action.

If you found this tool useful, taking a moment to leave a rating really helps. Thanks for the support.