[Feature proposal] Import as Sprite and AnimationPlayer

[Kerberross]

Note that the screenshots are from a POC in Godot 4, but doing it in Godot 3 should be possible. I will create a pull request for Godot 3 if this proposal seems good to you, then update the current one for Godot 4.

Why

• allow using the custom duration by frame define in Pixelorama (frame properties)
• allow using the AnimationPlayer features (adding other tracks (function call, other attribute changes…) and AnimationTree)

How

New import type, Sprite (Godot 3)/ Sprite2D (Godot 4) & AnimationPlayer

Import properties

Parameters explanation:

• Sprite[2D] > scale: Scale of the sprite[2D] that will be generated. Default value: vector2.ONE (seems useful since pixel art is usually bigger than the number of pixel of the image)
• Animation > External save: If checked, the animations (Godot 3)/animation library (Godot 4) will be saved in the project instead of bundle in the imported resource. This allows to add new custom tracks. Default value: false
• Animation > External save path: The directory where the animation will be saved if External save is checked. Default value: current directory of the pxo file.

Import process details

The import will create a packedScene with a tree like:

• Sprite[2D]
  • AnimationPlayer

Generated tree

Changed done on the created Sprite[2D]:

• Texture set to the spritesheet generated
• Name set to the pxo file name (it's used when adding the packed scene to a tree)
• Scale set to the one provided by the import settings
• Set the Hframe/Vframe to the correct number
• Godot 4: Filter mode set to nearest (since it's pixel art) (For Godot 3, it's already defined in the current import of the texture)

Changed done on the created AnimationPlayer:

• Create animations based on Pixelorama tags
• The keyframes will take into account the fps and the frame duration define in the pxo file
• The looping of the animation can be defined by starting/ending the animation name by "loop"/"cycle" like the 3d import

Example of variable fps animation (fps = 6, second frame have the duration set to 2 => with a fps of 12)

In case of the animations are stored separately, the import will only replace the tracks linked to the frame animation, leaving the others tracks added by the user. The animation length will also be updated.

Questions

• For the current SpriteFrames import, the fps is an import parameter and not the one define in the pxo, there is a reason for that?
• For the external save, which file naming should we use? My proposal:
  • For Godot 3: {pxo-name}-{animation-name}.tres for each animation
  • For Godot 4: {pxo-name}-animations.tres for the animation library (one file to store all animations) This resource isn't available in Godot 3. I don't see a reason to store each animation separately, but it's still possible if needed
• It may be a good idea to have some project parameters to define the default value of the import, as well as the default import (since it required an editor restart to change it), what do you think? It would have:
  • A dropdown list with the different import type (default to Single Image at the plugin activation)
  • the default scale (set to vector2.ONE at the plugin activation)
  • the default external save (set to false at the plugin activation)
  • the default path (set to empty at plugin activation) (if empty: default to the directory of the pxo)
  • If there is a reason for the fps in the SpriteFrames import, a similar parameter can be added

I think I covered everything I had in mind, feel free to add new thing if it makes sense :smiley:

[Technohacker]

Thanks for the proposal!

Animation > External save path: The directory where the animation will be saved if External save is checked. Default value: current directory of the pxo file.

See if this field can be hidden when External Save is disabled, to make sure it's clearer to the end user :)

In case of the animations are stored separately, the import will only replace the tracks linked to the frame animation, leaving the others tracks added by the user. The animation length will also be updated.

So in case the pxo file defines a new animation with a name matching a custom animation that's already present, that may need overwriting, right? Unless we maybe have a special prefix for import-generated animation tracks

For the current SpriteFrames import, the fps is an import parameter and not the one define in the pxo, there is a reason for that?

I don't quite remember the justification off the cuff :sweat_smile: I believe I hadn't implemented it at the time, likely just focusing on having a basic importer to start with, or that the pxo file didn't specify project FPS. Feel free to remove it :)

For the external save, which file naming should we use?

One suggestion I have is {pxo-name}/{animation-name}.tres for Godot 3, mainly because in case someone happens to have multiple pxo files saving to the same folder, their animation files will be grouped together under a common folder rather than everything being listed out in the parent folder (Granted, this situation is unlikely, and it may just be my personal preference speaking here)

It may be a good idea to have some project parameters to define the default value of the import, as well as the default import (since it required an editor restart to change it), what do you think?

Are these for the game's Project Settings? There may be issues for when the Project defaults have changed, but existing imports have been done

Otherwise LGTM :D

[OverloadedOrama]

For the current SpriteFrames import, the fps is an import parameter and not the one define in the pxo, there is a reason for that?

I don't quite remember the justification off the cuff :sweat_smile: I believe I hadn't implemented it at the time, likely just focusing on having a basic importer to start with, or that the pxo file didn't specify project FPS. Feel free to remove it :)

If I remember correctly, it was because pxo's weren't storing the fps back then, so it had to be an import parameter. Now they do, so I don't think the parameter is needed any longer.

[Kerberross]

Animation > External save path: The directory where the animation will be saved if External save is checked. Default value: current directory of the pxo file.

See if this field can be hidden when External Save is disabled, to make sure it's clearer to the end user :)

There is a get_option_visibility available, so it should be possible

In case of the animations are stored separately, the import will only replace the tracks linked to the frame animation, leaving the others tracks added by the user. The animation length will also be updated.

So in case the pxo file defines a new animation with a name matching a custom animation that's already present, that may need overwriting, right? Unless we maybe have a special prefix for import-generated animation tracks

I am not quite sure that I understood the question:

A track is an attribute change. In the screenshot, it's the frame line. Somebody could add another track changing the position of the sprite, or another one calling a function in the same animation. What I was saying is that the track for the position of the sprite will be untouched, and the track for the frame will be updated. So for a track, a prefix is impossible, since it's a path to a Godot attribute (".:frame" is this case).

For the animation itself, in Godot 3 I am not quite sure that it's possible to add new one, since the list of animation is in the packed scene I guess, but I need to test that. Since the packed scene is in the .import directory, the user cannot modify it. In Godot 4, with the animation library save externally, it should be possible, but I don't really know what the best things to do.

I suggest that I do a first version in Godot 3, tests what's possible, to have a clearer view. Same thing later with Godot 4

For the current SpriteFrames import, the fps is an import parameter and not the one define in the pxo, there is a reason for that?

I don't quite remember the justification off the cuff 😅 I believe I hadn't implemented it at the time, likely just focusing on having a basic importer to start with, or that the pxo file didn't specify project FPS. Feel free to remove it :)

If I remember correctly, it was because pxo's weren't storing the fps back then, so it had to be an import parameter. Now they do, so I don't think the parameter is needed any longer.

Ok, I will do that

For the external save, which file naming should we use?

One suggestion I have is {pxo-name}/{animation-name}.tres for Godot 3, mainly because in case someone happens to have multiple pxo files saving to the same folder, their animation files will be grouped together under a common folder rather than everything being listed out in the parent folder (Granted, this situation is unlikely, and it may just be my personal preference speaking here)

You are right, putting everything in a folder seems a better idea!

It may be a good idea to have some project parameters to define the default value of the import, as well as the default import (since it required an editor restart to change it), what do you think?

Are these for the game's Project Settings? There may be issues for when the Project defaults have changed, but existing imports have been done

Yes. I didn't test it yet, but I think those settings will be used only for new imports, since Godot stored the one used for each import in a separate .import file. I will do a quick test and come back with the answer tomorrow

[Kerberross]

It may be a good idea to have some project parameters to define the default value of the import, as well as the default import (since it required an editor restart to change it), what do you think?

Are these for the game's Project Settings? There may be issues for when the Project defaults have changed, but existing imports have been done

Those projects settings are only used for new import. Older import keeps their values

In case of the animations are stored separately, the import will only replace the tracks linked to the frame animation, leaving the others tracks added by the user. The animation length will also be updated.

So in case the pxo file defines a new animation with a name matching a custom animation that's already present, that may need overwriting, right? Unless we maybe have a special prefix for import-generated animation tracks

In godot 3: Since the file is imported as a scene, the only 2 way to add an animation is by inherited it or making child editable. In both cases, the animation is stored outside of the imported file, so when reimporting the file, it's not possible to know if an animation was created. In case a new animation is imported and an inherited scene added one with the same name, the one in the inherited scene will overwrite it. Deleting the one in the inherited scene will bring back the imported one. It's the same behavior for 3d import.

I still need to have a look in godot 4.

[Kerberross]

In case of the animations are stored separately, the import will only replace the tracks linked to the frame animation, leaving the others tracks added by the user. The animation length will also be updated.

So in case the pxo file defines a new animation with a name matching a custom animation that's already present, that may need overwriting, right? Unless we maybe have a special prefix for import-generated animation tracks

In godot 4, if the animation is created in the same AnimationLibrary, the track related to the frame will be overwriten. But multiples AnimationLibrary can be added, so adding another for custom animations will avoid overwriting them.

[nklbdev]

I am very proud to have touched these projects in the course of my work. And I want to offer you an alternative - Importality, the bundle of importers, which can import Pixelorama files and other formats. Including in the form of a Sprite with AnimationPlayer.

I just now discovered this repository and would like to support its development, or invite the contributors of this plugin to join the development of Importality.