Support for TexturePacker and trimmed images

sergey.lerg · February 26, 2023, 4:10pm

Together with Artem Anisin we have developed a new feature for Defold.

Texture sizes can be greatly reduced by trimming transparent pixels around the actual sprite image.

Trimmed Images in Atlas

This feature introduces new fields for images in the atlas outline pane. Namely Source Position X, Source Position Y, Source Width, Source Height.

Source Position X and Source Position Y indicate the position offset of the trimmed image inside the original image from the top left corner. Source Width and Source Height indicate the original image size and they are needed to correctly center the trimmed image inside the animation frame.

TexturePacker Support

Now you can use TexturePacker to generate atlas files with trimmed images.

The exporter supports storing atlas settings and animations settings such as margin, padding, FPS, playback and so on.

It has to be installed in TexturePacker as a custom exporter (create a dir, select it as custom exporters dir in TexturePacker settings, copy defold dir from the repo into that dir).

TexturePacker not only can trim images but also can detect identical sprites saving up disk space even further.

Spritesheet Split Editor Script

Use this editor script to split up the spritesheet from TexturePacker into individual files for Defold.

Pull Request

The feature is not yet available in Defold but there is a pull request on GitHub, give it a like!

github.com/defold/defold

Added support for trimmed images in atlases.

defold:dev ← Lerg:dev

opened 02:23PM - 26 Feb 23 UTC

Lerg

+174 -41

Texture sizes can be greatly reduced by trimming transparent pixels around the a…ctual sprite image. The engine itself already has support for arbitrary vertex positions for each image which was introduced with the Sprite Trim Mode feature. Therefore only the editor and bob were modified to add the trimmed images support. This feature introduces new fields for images in the atlas outline pane. Namely `Source Position X`, `Source Position Y`, `Source Width`, `Source Height`. `Source Position X` and `Source Position Y` indicate the position offset of the trimmed image inside the original image from the top left corner. `Source Width` and `Source Height` indicate the original image size and they are needed to correctly center the trimmed image inside the animation frame. This new information about the images can be entered by hand or a special user script can be used to prepare such atlases. ## TexturePacker support https://github.com/Lerg/defold-texturepacker-exporter To ease the generation of such atlases a custom exporter was created for TexturePacker. The exporter generates atlas file for Defold and a JSON file for the Spritesheet Split editor script. The exported supports storing atlas settings and animations settings such as margin, padding, FPS, playback and so on. ### Spritesheet Split editor script https://github.com/Lerg/defold-editor-script-spritesheet An editor script was created that takes a spritesheet image generated by TexturePacker with a JSON file containing information on each image inside the spritesheet and splits up the image into individual files suitable for the atlas. Resolves #3629

There is no guarantee it’s going to be accepted and merged but I hope it will.

Preview

Erica atlas with no trimming is 4096x2048

Erica atlas with trimming is 2048x2048

TexturePacker Exporter

Spritesheet Split Editor Script

Comparison between trimmed sprite and full sprite in the collection
The green area is the sprite polygon shape shown using a custom shader.

Comparison between trimmed sprite and full sprite at runtime
The green area is the sprite polygon shape shown using a custom shader.

gianmichele · February 26, 2023, 6:59pm

This is amazing!
Hopefully your PR will be picked up and integrated with the editor too, once the packing algo is updated.

Pawel · February 26, 2023, 8:27pm

Thank you for such an amazing functionality!

britzl · February 27, 2023, 11:30am

Thank you for the contribution @sergey.lerg and Artem! This is definitely something we want but seeing as it is new functionality we need to make sure it is well implemented and follows our design principles. We usually start with a design document to discuss how to implement the feature before we start implementation.

github.com

defold/defold/blob/dev/CONTRIBUTING.md#new-features

# Contribution Guidelines
Thank you for visiting the Defold open source contribution guidelines. We invite you to help make Defold an even better product! You don't even have to be a coder to contribute! You can contribute in the following ways:

* Improve the documentation
* Suggest new features
* Fix bugs
* Implement new features

Before you start contributing we would like to ask you to familiarise yourself with our contribution guidelines and our code of conduct. Following these guidelines will make the contribution process a lot smoother and faster.

Thanks! ♥

/ The Defold Foundation and the Defold development team

## Code of conduct
We ask of all contributors, project members and users to follow our [Code of Conduct](CODE_OF_CONDUCT.md) to create an open and welcoming environment. We will remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to our Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that we deem inappropriate, threatening, offensive, or harmful.

## Documentation
The Defold manuals and examples are hosted in a [separate repository](https://github.com/defold/doc). Please pay it a visit if you wish to help improve our documentation! We need help to fix typos, update images and to write or improve tutorials and manuals.

This file has been truncated. show original

This is a crucial step and since you skipped it we may need to iterate more on the PR before it can be merged.

But again, thank you for such a great contribution. I sure hope we can work together to get it merged!

sergey.lerg · February 27, 2023, 2:19pm

I understand that you would’ve preferred a prior design discussion but this feature was developed for a company for the needs of the current project and it is being used at the moment. And we are just sharing what we’ve developed with the community hoping our internal solution would benefit others as well.

I understand our solution might not align with the Defold vision of the feature that’s why I said the PR might not get accepted. I hope eventually our solution in one form or another will find its way into the core.

And I am sorry for any improper code in Clojure, it’s my first time coding in it and I struggled a lot with it. At least it’s working for our use cases.

AndreasLoew · February 28, 2023, 1:29pm

This looks quite good - I had no time to test it yet - but we are happy to see TexturePacker exporter for Defold.

We would even include it in TexturePacker to make things easier for the users.

A direct integration into Defold would of course be great - but using the editor script should not be too hard for the users.

Is it possible to automate the splitting when importing/updating the sprite sheet instead of requiring the user to manually use the split menu?

sergey.lerg · February 28, 2023, 2:04pm

Oh, hi! Nice to see you here.

I guess I’ll make a list of the things I think would benefit the exporter:

Add an option in exporter.xml to make “Prepend folder name” always on.
Add custom properties for each smart folder for things like animation FPS, animation playback (once, loop, backward).
Add custom properties for each image (not too important but still nice to have, would be used for better support of the “Sprite Trim Mode” option in Defold).
Add file access for the exporter script with PNG read/write lib.

The last point would make it possible to split the sprtiesheet without the use of the editor script and doesn’t require big changes to the TexturePacker itself. I know that file I/O is dangerous but it is possible to sandbox it inside a specified dir and only allow reading and writing image files. That should be safe enough.

Alternatively it might be possible to extend so called Hooks Editor Script (/hooks.editor_script) with an extra event to detect new files in project and call the split spritesheet script if it detects a TexturePacker export. But still it would require installing these scripts, they won’t be available out of the box.

In my opinion the more capabilities of the exporter script inside TexturePacker the better.

Also the error message can be improved for when users select the exporter dir as the custom exporters dir.

Say if it detects that there is no exporter.xml but there is ../exporter.xml present a user with a message like “Looks like you’ve selected wrong Custom Exporters Directory, change to /Path/To/Parent/Dir?”

AndreasLoew · February 28, 2023, 3:48pm

I think that the idea of splitting the sheets is bad. What it would require in my opinion is a way to directly import sprite sheets into Defold. Not to pack them, split them and re-import the images.

It seems that the way to do that would be to place a feature request.

britzl · February 28, 2023, 5:47pm

What we’ve discussed internally in the Defold team is to natively support TexturePacker files as an alternative to our built-in texture packer. @JCash and @jhonny.goransson have spent time thinking about this and know more about the technical details of how that would work.

sergey.lerg · February 28, 2023, 10:24pm

That would be great! I hope eventually that would be implemented.

Mathias_Westerdahl · March 1, 2023, 7:21am

I concur with @britzl in that we need more time to think around the design of this feature.
Currently, I don’t believe this PR will be merged at this time, but it for sure is a feature we want, and we should dedicate more time to it this year.

As it stands right now, we shouldn’t involve e.g. @AndreasLoew until we have come further with this task.

AndreasLoew · March 2, 2023, 8:38am

@britzl @Mathias_Westerdahl We already had some contact on email 2020… I’ll re-open that conversation…