Extend the import functionality to automatically import atlases

[JoanPotatoes2021]

Describe the project you are working on

2D isometric rpg, which uses 8 directions for each animation per character. By that logic, a single character can have up to hundred thousand sprite frames on the finished project, having all animations stiched into a atlasTexture from individual renders of a 3D app, like Blender.

Describe the problem or limitation you are having in your project

Atlases creation from individual images cannot be automated, and it is not easy to modify the current behavior.

Having a couple thousand individual animation frames rendered from blender, decided to use atlas textures to improve perfomance and workflow, thus the creation of atlases became a problem. Current workflow is:

1> Copy all your sprites to godot project file, in my case I use the example of 1.000 .png sprites, with dimestions around 128x256, which corresponds to animations of walking, running, crouching, proning, etc. All of those are from a single character.

2> Wait for godot to import all of the sprites as individual textures, which takes around 5 - 10 minutes for that amount of images. Even with ETC2 deactivated, the texture import process takes too much time, but that is not the issue, the issue is that this import process is not desired, because the final result is a atlas texture, so all of those imported and compressed resource textures will not be used, only the final atlas will be used on .import .

3> So, re-select manually from the folder all the images I want to belong to the atlas, change their type to atlasTexture and select re-import, this time however, it's much faster, because it's compressing only one big atlas, not thousands of individual textures, taking around some seconds to make the atlas and re-import it.

TLDR: Too much time spent on manually selecting the sprites that will belong to the atlas and not having the option to tell Godot to not import all the thousands of individual sprites as textures, because that makes a thousand of individual textures, which also takes too much time to read/compress/save.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The goal is to create automatically a atlas texture from all image files from a folder that have a unique file inside a folder, similar how .gdignore works, if you put them into a folder Godot fileSystem ignores the folder, the idea is a file that tells Godot that all those image textures belong to a atlas, thus allowing Godot to not automatically import them as individual textures but make them as a atlasTexture directly, maybe a .atlasImport , the only thing left was where to place the atlas, which could be a default folder parent of that one or a specfic default folder setted on project settings.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

1 - Copy the logic of having a .gdignore file, but to make a atlasTexture instead, all the image textures from that folder will be inside the atlas texture without having you to manually select them and press re-import. The atlasTexture path can have a pre-defined path from the project settings or be in a parent folder from those textures.

or

2 - Make a new import process for directly importing atlasTextures, which could use a unique format, like .atlasTextureFile, but that would require the user to have their own renaming utilities. Or, having the import process check for a file with all the atlas data, similar to option 1, the text file is to simple tell the atlasTexture where to put the atlas texture, and what import mode it uses:

If this enhancement will not be used often, can it be worked around with a few lines of script?

No, because it is asking for a automatic atlasTexture creation, which currently is part of the core import code, having one to make a import plugin from scratch if it wants to modify how the import works. I did not found a way to easily tell Godot to not import all the thousand textures as individual resources but as atlasTexture automatically.

It is frustrating, because Godot has a excellent atlas packaging algorithm, even with current limitations, but we cannot tell Godot to import them automatically.

Is there a reason why this should be core and not an add-on in the asset library?

This enhancement allows big projects to use atlasTextures as they expect, because currently it is only workable to small projects, due to having the manual workflow of selecting individual files to be part of a atlas and pressing re-import button, which is inviable for big project that have hundred of folders, with thousands of textures.

Due to the nature of atlas textures, if you use a thirdpartytool, you will need a plugin to handle the information transition of which frames are where, their size and padding, Godot do all of this automatically, I don't see a reason to not have this in the core, it's extending the functionality.

[Calinou]

Note that texture atlas functionality hasn't been reimplemented in the master branch yet, and may be removed as there's less need for it nowadays (with devices having more memory than before). Therefore, this may take a while to be implemented (if ever).

[JoanPotatoes2021]

My project doesn't need the atlasTexture per say, it is a premature optimization because it will be handling a lot of sprites, usually people work with pixel art, but not high-res, I will upload a old atlas version of our project to give a idea, our worry is that handling thousands of individual textures to the engine will result in wasted vram and cpu loads, that being said, we didn't tested it, it is just natural to do atlas packages for perfomance.

If there are no or little perfomance hickups to working with individual sprite frames, I say there is not a need for atlasTexture.

Don't mind the odd coloring, it's watermark. All of this atlas represents is one character, using a pistol, running, walking and firing and reloading. The atlas algorithm in Godot is superb, all the rendered transparent areas get's compacted efficiently.

[JoanPotatoes2021]

We render our sprites from blender and pack them into the atlas using Godot, for people who don't know why use atlases, it's because without the option to make a atlas, it would result in too much wasted space being taken as texture,

[Giwayume]

We render our sprites from blender and pack them into the atlas using Godot, for people who don't know why use atlases, it's because without the option to make a atlas, it would result in too much wasted space being taken as texture,

Exactly this. In an extreme example, you need to give as much empty space in your render as necessary in order to fit all the animations, so a character with a long weapon might require a ton of extra empty space. This extra space needs to be added to every single sprite in the animation so all of the animations align.

I don't want to be shipping a ton of 720x720 animation frames where only 25% of it is used. Even high end computers be struggling swapping out animation frames this size. Huge 2d animation frames is an issue the developers of Ori and the Blind Forest mentioned. https://www.youtube.com/watch?v=m8lOwrWNbEY

See even with this much empty space, the character doesn't quite have enough room to fully extend the spear.

[Giwayume]

And it's not just a performance problem, it's a download size problem as well. Many game hosting sites have upload limits.

I could walk into a Best Buy and pick up a new $300 Chrome book, it wouldn't be able to play my game with the default dedicated 1GB vram (shared across all applications), without creating atlases.

Think 720px x 720px, 32 bpp images (around 300KB per frame uncompressed), with a generously low animation count of 20 per character, 24fps for each animation at 1 second per animation.

300KB * 20 animations * 24 frames = 144MB per unique character, uncompressed images.

Obviously Godot runs vram compression algorithms on the images, but I'm not comfortable with 14% of total VRAM (not even what's dedicated to the game) being taken up by one character even in this uncompressed scenario.

Assuming Vulkan gets a WebGL counterpart at some point, or even Godot 4 starts supporting WebGL 2.0 again, you'll also have an even lower limit than what's in the system. Probably around 12%.

The idea that atlases are not needed because the average device has more VRAM is nonsense. Games always catch up to the hardware. Someone makes a higher resolution monitor, higher VRAM graphics card, a game developer matches that with higher resolution sprites which increase exponentially the amount of VRAM needed.