Aseprite file format: User Data Chunk?

duke_of_germany · September 14, 2025, 2:51pm

Hello!

I am current implementing a parser for the Aseprite file format, following the format specification on GitHub. The documentation is really good!

The only thing that is a bit unclear to me is the User Data Chunk and its Property Maps.

The following questions came up for me regarding the property maps:

Regarding the “vector” property (type 0x0011):
Which element types can the vector contain? (Is it all property types? And if so, can it even contain vectors, or a nested property map?)

Regarding the “nested property map” (type 0x0012):
Can it contain another nested property map, so that theoretically, there would be no nesting limit?

I would appreciate any hint!

behreandtjeremy · September 14, 2025, 7:58pm

It might help to open the developer console and test for yourself (or write a Lua script that prints to console).

You can assign a keyboard shortcut to open the developer console by going to Edit > Keyboard shortcuts, then searching for it in the input with the magnifying glass.

As far as I can tell, a vector can contain the same data types that a properties map can, including a property map, a vector and some – but not all – Aseprite specific objects (points, rectangles, sizes, uuids). A vector can contain a mixture of data types. A property map can contain another property map; not sure of any nesting limits.

I don’t know much on implementation details, but if you wanted to look at the source code, here are some places to start:

github.com/aseprite/aseprite

src/doc/user_data.h

main

// Aseprite Document Library
// Copyright (c) 2022-2023 Igara Studio S.A.
// Copyright (c) 2001-2015 David Capello
//
// This file is released under the terms of the MIT license.
// Read LICENSE.txt for more information.

#ifndef DOC_USER_DATA_H_INCLUDED
#define DOC_USER_DATA_H_INCLUDED
#pragma once

#include "base/uuid.h"
#include "doc/color.h"
#include "fixmath/fixmath.h"
#include "gfx/point.h"
#include "gfx/rect.h"
#include "gfx/size.h"

#include <cstddef>
#include <limits>

This file has been truncated. show original

github.com/aseprite/aseprite

src/dio/aseprite_decoder.cpp

main


      
              // not user data for tags).
              tag->setColor(doc::rgba(r, g, b, 255));
          
              tag->setName(name);
              tag->setAniDir((doc::AniDir)aniDir);
              tag->setRepeat(repeat);
              tags->add(tag);
            }
          }
          
          void AsepriteDecoder::readUserDataChunk(doc::UserData* userData,
                                                  const AsepriteExternalFiles& extFiles)
          {
            size_t flags = read32();
          
            if (flags & ASE_USER_DATA_FLAG_HAS_TEXT) {
              std::string text = readString();
              userData->setText(text);
            }
          
            if (flags & ASE_USER_DATA_FLAG_HAS_COLOR) {

duke_of_germany · September 15, 2025, 7:45am

Wow, this is so helpful!

(And I had no idea about the developer console!)

Now I have everything I need to know to finish my parser.

Thank you so much!