[Feature Request]: User Data Property Map support

SaxxonPike commented 5 months ago

Purpose

This feature allows accessing extension-specific data that Aseprite extensions store.

Aseprite Spec Reference

These files detail UserData structures and Property Maps:

Bit 2 (0x04, ASE_USER_DATA_FLAG_HAS_PROPERTIES) of the UserData flags indicates the presence of this data structure. This is not supported in AsepriteDotNet currently.

Property Map Use

In order to create files that have this data stored with them, a Lua script must add them as an extension within Aseprite. Here's a simple script for use with Aseprite to add it to the currently loaded sprite:

local spr = app.sprite
-- strings are stored as like others in the format (length, then utf8 bytes)
spr.properties.a = "howdy"
-- arrays are stored as "vector" type
spr.properties.b = { "more complex data can be stored in here", 123, 456, 3.14 }
-- tables are treated as nested property maps
spr.properties.c = { a=1, b="hello", c={ 5, 10, 15, 20 } }
-- single values are stored as the smallest type that will fit them
-- this gets stored as a signed byte
spr.properties.d = 1

After running this script in Aseprite, the file can be saved and we will see the data structure stored as a Property Map.

Performance and Compatibility

Most files (particularly ones saved without any extension data at all) will not have this data, so once the check for the aforementioned bit in UserData is zero, no further Property Map processing is necessary. Performance is unlikely to be even measurably different with this feature in place.

Should more flags be added to the UserData structure in the future, partial support for this feature will still be required in order to know how many bytes large the Property Map structure is anyway.

Proposed API integration

These are an extension of UserData, but I'm curious what others' thoughts are about whether they should be integrated into UserData, or if they should be processed separately on demand (as in, with their own Processor), and if they should also be loaded when using the "load tags only" functionality. Comments welcome.

I have implemented this in a branch to illustrate how this might work, which may serve as the pull request later to address this feature request:

https://github.com/SaxxonPike/AsepriteDotNet/tree/user-data-property-maps

Motivation

Extensions using the Lua API can store additional structured data inside UserData. This allows extensions to store extension-specific data alongside the existing Text and Color which are accessible directly in the standard UI. In fact, any UserData structure can have Property Maps associated with them. Without this feature, only the Tags field serves the function as a general metadata field.

AristurtleDev commented 5 months ago

Thanks @SaxxonPike for opening this (can of worms) up 😆.

This was never implemented because it’s not part of the standard UI interface in Aseprite, so without using Lua extensions, the average user wouldn’t even know they existed.

However, I’ve always said that if it was (1) added to the UI in Aseprite or (2) someone requested the feature, then it wouldn’t added at that point.

So you’re the first to mention and request it, so it’s on the table now haha.

Im not near a computer right now to check your implementation but I’ll give it a look through later this evening and comment some more about it then.

SaxxonPike commented 5 months ago

@AristurtleDev It's no surprise, it probably isn't a very requested or considered feature! As a programmer and scripter myself, I found some interest in attaching more complex data to parts of sprites. This would open up a lot more tooling within Aseprite and application integrations for me personally.

I found this repository to be well maintained and with very good test coverage, so the implementation I linked likewise should have full coverage of the new feature. If you think that this is a good way to go, I'll formally put in the PR.

cyraid commented 2 months ago

@AristurtleDev I also wouldn't mind this addition. ^_^

AristurtleDev / AsepriteDotNet