Aseprite Bridge — Documentation

Version 1.0.6 · Windows · Your own Aseprite 1.3+ required

A written guide to setup, texture transfers, previews, animation and palettes. Read the file-handling notes before using Live Sync on an important texture. Chapter links open the selected section in a new tab.

1. Requirements and package

Aseprite Bridge 1.0.6 is a standalone Blender add-on. You need Windows and your own installed copy of Aseprite 1.3 or newer. Aseprite is not included. The bridge also installs a companion Lua extension into Aseprite.

Use universal_bridge_aseprite-1.0.6-blender3.3-5.2.zip. It contains Blender source, the Aseprite-side extension and DOCUMENTATION.md. Install the package once and avoid enabling duplicate copies of this bridge.

The separate universal-bridge-aseprite-1.0.6-documentation.zip includes the expanded manual, quick start, FAQs, release notes, notices and full GPLv2 text. Extract it to read the documentation; do not install it as a Blender add-on.

• Legacy add-on metadata: Blender 3.3 minimum.
• Extension manifest: Blender 4.2 minimum.
• Supplied filename/documentation range: Blender 3.3–5.2. This is a declared range, not a completed test matrix.
• No exact tested Blender/Aseprite/OS build matrix accompanies this package. macOS and Linux are not supported by the supplied Windows workflow.

The transfer uses local commands, status files and images. Aseprite opens its own documents and exports image data; Blender does not parse the native .aseprite format itself.

2. Install and locate the controls

1. Save your Blender project and make a copy of any texture you intend to use for the first trial. Keep only one installed copy of this bridge enabled.
2. In Blender Preferences, use the installation command for your version: Install on older releases, or Install from Disk where available. Select the supplied ZIP, then enable Universal Bridge: Aseprite. Installation of this exact package across the declared range still needs verification.
3. Open a 3D Viewport. Viewport Card is enabled by default in the add-on preferences, so the card is the primary interface and the duplicate sidebar panel is hidden.
4. To use the sidebar instead, turn off Viewport Card in preferences or use the card’s top-right switch. Press N in the 3D Viewport and open the Aseprite tab. With Universal Bridge Manager active, the controls can be placed under Universal Bridge.
5. Use Install / Update Aseprite Extension. It copies the companion extension into Aseprite’s extension directory. Close and restart Aseprite afterward; extension loading happens at startup.
6. In add-on preferences, set the Aseprite executable path if discovery does not find your installation. The connection status should change from Aseprite not connected to the active sprite status.

Install the companion extension and restart Aseprite · Edited workflow demonstration

Blender product version and companion extension version are different version lines. They are not expected to be numerically identical. If the bridge reports that the running extension differs from the shipped version, update it and restart Aseprite before transferring work.

3. Your first texture round trip

1. Save a test .blend. Select a UV-unwrapped mesh with an active material containing an Image Texture node. Use a file-backed texture copy for this first result.
2. In the card’s Draw picker, choose the image to update. The fallback sidebar calls this property Texture. Check the image name before sending.
3. Click Send. Send logic can use an open Image Editor image, the selected texture or a fallback material texture; check that the image opened in Aseprite is the intended one.
4. In Aseprite, make a small visible change. Keep the sprite open.
5. Use Get Sprite in Blender and inspect the same image and material. Referencing Image Texture nodes are set to Closest interpolation.
6. If Live Sync started with the transfer, switch it off while learning the manual workflow. Save the .blend and inspect the texture file separately.

Draw selects the intended destination image · Edited workflow demonstration

4. Send an image or build a texturing document

Send an image

Select the destination texture explicitly. The send logic prioritizes an Image Editor image, then the selected material texture, then a fallback material texture. A running connected Aseprite receives the request; otherwise the bridge can launch the configured executable. Always inspect the opened image before painting.

A returned image keeps the existing Blender datablock when a destination has been selected. This preserves references from materials and other users of that image. Without a destination, a returned image can appear as a separate image rather than updating the intended material.

Send Mesh for Texturing

1. Select the active mesh and ensure it has a UV layer. Check that the intended material is active.
2. Save the material maps to files. This workflow transfers file-backed maps; it does not convert every procedural shader into a painted texture.
3. Connect Aseprite, then choose Send Mesh for Texturing.
4. Inspect the Aseprite document: material maps become layers and the UV layout appears as a dimmed, locked guide. Paint the map layer, not the UV guide.
5. Return the sprite or use Get Layers as Maps when you want named maps reconnected to the material.

Maps and a locked UV guide prepared for painting · Edited workflow demonstration

“Send Mesh” prepares a 2D texturing document. It does not transfer editable 3D geometry into Aseprite.

5. Pixel filtering and canvas sizes

Get and import operations call the pixel-filtering helper. It sets Image Texture nodes referencing returned images to Closest and attempts nearest filtering for the image. If another image remains soft, inspect the image actually used by that material and its interpolation setting.

Returned texture nodes use Closest interpolation · Edited workflow demonstration

Square size presets run from 16 to 1024. Width and Height can be set separately; custom values run from 1 to 8192 in the source properties. Choose dimensions appropriate to the asset. Preview Size is a different setting and does not change the painted texture’s dimensions.

Separate canvas width and height with pixel-art presets · Edited workflow demonstration

6. Live Sync

Live Sync connects Aseprite edits to Blender image updates. On Save sends when you save in Aseprite. While You Draw schedules an export after changes. Min Gap is the least interval between updates; raise it when frequent transfers interrupt work.

1. Choose the correct Draw/Texture destination first.
2. Enable Live Sync and select the update mode. On Save is the default.
3. Make a small change and observe the selected Blender image. Use a copied texture to verify the destination before continuing.
4. Switch Live Sync off to stop automatic returns. A manual stop is remembered, so later Send/Get actions do not silently turn it back on.

Live Sync update modes and timing control · Edited workflow demonstration

A first Send/Get can start sync if you have not manually stopped it. Aseprite exports a scratch copy, but Blender can then write the returned result to the selected texture’s original path. Timers and file processing still run; there is no claim of zero overhead.

If a transfer goes to the wrong image, stop sync immediately and reselect the destination. Restore an overwritten file from your backup before resuming.

7. See Blender’s model inside Aseprite

3D Preview in Aseprite opens an Aseprite dialog displaying a viewport image produced by Blender. Keep Blender open with a usable 3D Viewport. Set the view and material display in Blender before requesting the preview.

1. Select the mesh and texture you are editing.
2. Use 3D Preview in Aseprite and inspect the preview window in Aseprite.
3. Use its arrow/orbit controls, Zoom +/− and Frame to request changes to Blender’s viewport. Refresh requests a new image without moving the view.
4. Keep the preview update switch on for new captures after transfers. Turn it off to hold the last image.
5. Use Preview Size to balance clarity and capture cost. The source default is 480 pixels on the longest side; the exposed range is 160–1024.

Aseprite preview window with controls routed to Blender · Edited workflow demonstration

Aseprite’s View > Blender 3D Preview menu also opens the dialog. This is a Blender viewport capture in an external application window, not an independent Aseprite 3D renderer. A stale picture can mean the update switch is off or Blender has no usable 3D view.

8. Bring back animation

Open the intended animated sprite in connected Aseprite, then use Get Animation. Choose the output that fits your next step.

• Frame Sequence: exports numbered PNGs and loads the first image as a Blender image sequence. If a material already references that returned image, the bridge sets frame count, cyclic playback and auto refresh on those referencing nodes. A newly returned sequence may still need selecting in an Image Texture node.
• Sprite Sheet: returns one horizontal sheet plus JSON data describing frame positions, durations and tags. Use that data in your engine or shader workflow. The bridge does not create every possible sheet-playing shader for you.

Enable Match Scene FPS only when changing the scene frame rate is appropriate. It derives a rate when all Aseprite frame durations are equal. Variable-duration timing is stored in JSON; automatic reproduction of unequal durations in Blender is not promised.

Animation as a sequence or sprite sheet · Edited workflow demonstration

After import, verify the assigned image, scene frame range and playback on the intended material. Disable Match Scene FPS if the scene’s existing timing must remain unchanged.

9. Exchange palettes

Send Palette

1. Set the Principled BSDF Base Color defaults of the materials whose colors you want to collect.
2. Choose Send Palette. The bridge gathers unique material Base Color values, up to 256 colors, and sends a palette Aseprite can read.
3. Inspect the resulting palette before painting. Texture pixels and arbitrary selected Blender palettes are not sampled by this operation.

Get Palette

1. Make the intended sprite active in Aseprite.
2. Choose Get Palette.
3. In Blender’s paint palette selector, choose Aseprite. The operation replaces that named palette, up to 256 colors, so preserve any previous palette you need before running it.

Scene material colors sent out and sprite palette brought back · Edited workflow demonstration

10. Layers as maps and native documents

Get Layers as Maps

1. Select the Blender mesh and active material that should receive the maps.
2. In Aseprite, make the intended document active and show the top-level layers or groups you want exported.
3. Name map layers clearly, for example basecolor, roughness, metallic, normal, emission or opacity.
4. Run Get Layers as Maps. Visible top-level layers/groups become files; recognized names are merged into the active material.
5. Inspect node connections and color-space treatment for the intended shader. Unrecognized names remain files on disk rather than being guessed into arbitrary inputs.

Named layers converted to material map files · Edited workflow demonstration

Import an Aseprite File

1. Connect Aseprite and choose the receiving Blender mesh/material.
2. Choose Import an Aseprite File, then select your .aseprite or .ase document.
3. Enable Leave it open in Aseprite if you want to continue editing it there. Otherwise Aseprite closes the imported document after exporting copies.
4. Inspect the returned visible layers and flattened image. The external application performs the reading; the Blender add-on does not contain a native .aseprite parser.

Import a document through Aseprite · Edited workflow demonstration

Use Open the Bridge Folder to inspect exchanged files. This workflow reads Aseprite documents and writes image copies; it does not author .aseprite documents, tilemaps or tilesets.

11. Preferences and file handling

• Aseprite executable: set the installed executable path if automatic discovery fails.
• Viewport Card: switches between the card and fallback sidebar. Card hue, saturation, opacity, icons, button effects and hover explanations are appearance preferences.
• Update / Min Gap: choose the sync trigger and minimum interval.
• Preview Size: controls viewport-capture size separately from texture size.
• Match Scene FPS: optionally changes scene timing for uniformly timed sprite sequences.

Images with an existing path may be saved back to that path. For images without a file, the implementation uses a textures folder beside the saved .blend, or temporary ub_textures storage when the .blend is unsaved. Save the .blend and inspect actual image paths before treating returned images as permanent project assets.

File writes and Aseprite-side changes are outside a simple Blender Undo guarantee. Save copies of source textures and palettes, and stop sync before switching projects or changing destinations.

12. Troubleshooting

The panel is missing

The viewport card is enabled by default and hides the duplicate sidebar panel. Check the 3D Viewport first. To use the sidebar, turn off Viewport Card and open the Aseprite tab with N. With Manager present, check Universal Bridge. Confirm that only one bridge installation is enabled.

Aseprite not connected

Install the companion extension, restart Aseprite and check its Edit > Preferences > Extensions list for Tachyon Blender Bridge. Confirm the executable path if the app cannot be found. Keep Aseprite open while requesting actions that need a live connection.

The running extension version differs

Use Update the Extension and restart Aseprite. Product and extension version numbers are separate. If the mismatch persists after reinstalling the supplied extension, stop transfers and contact Tachyon Studio with the reported versions; do not edit package version files to conceal it.

The texture did not update

Check Draw/Texture before sending. Without a destination, the result can arrive as a new image unattached to the intended material. Inspect the actual Image Texture node and its image. Check writable file paths and the bridge status message, then try one manual Get with sync disabled.

The preview is stale or unavailable

Keep Blender open with a usable 3D Viewport. Check the preview update switch and click Refresh. Reduce Preview Size if captures are slow. The preview is generated by Blender, so opening a dialog alone does not establish a new capture.

My animation is not playing on the material

Assign the returned sequence image to the intended Image Texture node, then check its frame count, start frame and Auto Refresh. Match Scene FPS only covers uniformly timed frames; inspect JSON for unequal durations.

A sprite will not close because it has unsaved changes

Save or close it inside Aseprite. The bridge avoids triggering a save-confirmation dialog that would block unattended requests. Do not discard changes merely to clear the connection status.

13. Updates, removal and version notes

This page describes the supplied 1.0.6 package. No separate changelog was supplied, so it does not attribute particular fixes or new features to this release.

1. Before updating, save your .blend, source sprites and texture backups. Stop Live Sync and close Aseprite.
2. Disable/remove the previous bridge using Blender Preferences, then install the intended package once. Avoid leaving duplicate legacy and Extension installations enabled.
3. Use Install / Update Aseprite Extension and restart Aseprite to refresh the companion files. Verify a copied texture before resuming production work.
4. To remove the bridge, stop sync and disable/remove it in Blender Preferences. Remove Tachyon Blender Bridge from Aseprite’s Extensions preferences if no longer needed, then restart Aseprite.
5. Preserve project textures and useful exchange files. Do not delete folders broadly as an uninstall shortcut.

Installation, migration, uninstall and workflows have not been tested across the declared range for this draft. The source implements the described workflows, but source review is not a completed application test.

14. License, purchase options and support

The supplied Blender source declares GPL-2.0-or-later, copyright 2026 Tachyon Studio. The software license governs code rights; purchase options do not replace it. Aseprite is a separate application from Igara Studio and is not included. Tachyon Studio is not affiliated with or endorsed by Igara Studio.

• Individual: For 1 person (1 seat). Commercial use included.
• Team: For a team of up to 6 people (6 seats). Commercial use included.
• Studio: For a studio of up to 20 people (20 seats). Commercial use included. Need more than 20 seats? Contact us directly.

All three purchase options receive identical complete features and downloads. Contact Tachyon Studio through Superhive messaging or the Tachyon Discord. Include the Blender version, Aseprite version, bridge version, action attempted and exact error text. Discord is optional support, not activation.