AB Sprite Editor
Contents
Introduction
This software is a sprite converter and editor intended for use with the Arduboy game console.
It is written in C# with the WinForms API.
Please note that this software is not intended to replace a proper image editor like GIMP, it is intended to provide only basic editing features. If you need advanced features like layers, please use another image editor in conjunction with this software.
Other relevant information can be found on the forum thread.
Licence
The software is available under the Apache 2.0 licence.
Be sure to also read the licence information for the associated resources.
Licence Permissions
You may
- Create derivative works from the software
You must
- Reatain all copyright and licence notices
- Provide recepients of this software or derivative software a copy of the Apache 2.0 licence
- Ensure that any modified files contain a prominent notice stating that you have modified the files
Platforms
Windows binaries are provided by myself. (I.e. the author of the repo, @Pharap.)
Mac binaries are provided based on the availability of someone to contribute them.
At the time of writing (2023-02-01) the only contributor of Mac binaries is @ArdFlamingo and the only binary available is for v0.5.0-beta.
If you (the reader) wish to volunteer to provide binaries for other platforms (e.g. compiled with Mono, Wine, et cetera) then please either raise an issue or contact me via other means.
Disclaimer: I (the author of the repo, @Pharap,) take no responsibility for the quality of executables contributed by others as I have no means to test them.
Note for Mac Users
I have been told by @ArdFlamingo that it may be necessary to run the following xattr command on the Mac executable:
xattr -cr "<path-to>/AB Sprite Editor.app"
Where <path-to> must be replaced with the necessary path to reach the extracted AB Sprite Editor.app.
(For more on xattr see ss64's article.)
Contributing
Feature Requests
Before making a feature request, please make sure to check that the feature has not already been requested, both in the issues and on the forum thread. If it has, you would be better off giving your support to the initial request than instating a new one.
If you would like to make a feature request, please either raise an issue, leave a comment on the forum thread, or send me a PM over on the forum.
Please bear in mind that I am only one person, and that I like to retain creative control of my software, so I may dismiss feature requests that I am unsatisfied with or believe would take too much work for me to either implement or review. (If this dissatisfies you, feel free to fork the software and add your desired feature to your personal fork.)
Code Contributions
Before attempting to make any kind of PR, please raise an issue first to explain your intentions and discuss the implementation. Discussing a feature, bugfix or other contribution prior to the production of the actual code helps to prevent mistakes or conflicts of intention by allowing time for communication, discussion and decision making. If a PR is created without any prior discussion, there is a high chance it will be rejected.
In the immortal words of Donald Knuth:
"Always remember, however, that there’s usually a simpler and better way to do something than the first way that pops into your head."
- Donald Knuth (1986), “The METAFONTbook”
Bug Reporting
If you would like to report a bug, please either raise an issue, leave a comment on the forum thread, or send me a PM over on the forum.
Features
Existing Features
These are features that have already been implemented and are present and (in most cases) presumed correct within the software. Some features may have known bugs or limitations.
Colours
- Black - Shortcut: 1
- White - Shortcut: 2
- Transparent - Shortcut: 3
Tools
- Pencil - Shortcut: P - Fills a single pixel at a time, can be dragged
- Flood Fill - Shortcut: F - Your standard 'fill a connected group of same-colour pixels' flood-fill algorithm
- Outline Rectangle - Shortcut: O - Draws an unfilled rectangle, thus an 'outline' of a rectangle
- Fill Rectangle - Shortcut: R - Draws a filled rectangle, thus a solid block of colour
Actions
- Flip Horizontally - Flips the image around the X axis so that pixels above are swapped with pixels below
- Flip Vertically - Flips the image around the Y axis so that pixels on the left are swapped with pixels on the right
- Rotate Left - Rotates the image 90 degrees anticlockwise
- Rotate Right - Rotates the image 90 degrees clockwise
Editor Panel
- Drag the canvas around with the middle mouse button
- Zoom in and out with the scroll wheel
- A little bit tempermental at the moment because the edit control must have focus first due to a quirk of WinForms
- Automatic zoom
- When a sprite frame is selected for editing, the control defaults to a centralised view of the image at the largest scale in which it will fit into the edit box
Saving and Loading
- Sprite data can be saved to
.xml files
- Sprite data can be loaded from
.xml files
Exporting
Sprites can only be exported to .h files
- Export to various sprite formats
- Export sprite without mask (
Sprites::drawOverwrite)
- Export sprite with interleaved mask (
Sprites::drawPlusMask)
- Export sprite with external mask (
Sprites::drawExternalMask)
- Export to uncompressed bitmap (
Arduboy2::drawBitmap)
- Export to compressed bitmap (
Arduboy2::drawCompressed)
- It is possible to designate a licence text to be included near the top of the generated
.h file
- If the generated C++ code would violate the one definition rule, a message box appears to warn the user and give them chance to correct this or to continue generating the code anyway
Tree View
- Renaming frames, sprites and namespaces
- They can be named either by clicking twice on a tree node's name box or by using F2
- Drag files into the tree view to import them
- Dragging onto a namespace or the main file node will generate a new sprite of the appropriate size
- Dragging onto a sprite adds frames to the sprite if they are of a suitable size
- Dragging onto a sprite frame will overwrite a span of frames, and add new frames if more are needed
- Reordering frames, sprites and namespaces
- This can be done either by draging nodes around, or using the up and down buttons either in the tree view tool strip or on the right-click context menus for nodes
- Note: Only the ordering of frames is actually saved at the moment. Reordering namespaces and sprites does not affect file output due to how sprite files are internally represented at the moment. See Planned Features.
- Dragging nodes around
- Dragging a frame onto a sprite removes the frame from its source sprite and adds it to the target sprite
- Dragging a frame onto a frame swaps the frames
- Draging a sprite onto a namespace moves the sprite (and its frames) into that namespace
- Draging a namespace onto another namespace moves the namespace and all of its contents into the target namespace
- The file itself counts as a namespace for destination purposes, but not source purposes - i.e. sprites and namespaces can be dragged onto the main file node, but the main file node cannot be used as a drag source
- All node entities can be deleted without issue
- All node entities can be duplicated
- Pressing the 'duplicate' button will insert a copy of any frame, sprite or namespace directly below the original
- 'Zooming' in and out on the tree view, which changes the image list icon sizes from 16x16 to 32x32 and vice versa
- Individual frames can be exported in multiple formats: PNG, BMP, TIFF, GIF, ICO and JPEG
Tab Control
- Close multiple tabs
- Close to the left
- Close to the right
- Close others
- Close all
- Which files have been saved is tracked, as indicated by a floppy drive icon on each tab
- If you try to close an unsaved tab, you will be asked if you want to save it
- This also occurs when closing the whole program
Planned Features
These are features that are planned to appear in future versions, though I may not be actively working on them at the moment.
- Display the compression ration of compressed images
- 'Rolling' frames around an axis
- Generating arrays for uncompressed frames
- More commenting
Potential Features
These are features that aren't planned to be added in the immediate future, but are likely to occur some time in the long-term future
- Potential overhaul of internal representation/framework
- Possibly the inclusion of a form of limited 'undo' feature
- FX-related features
- Bundled licence texts
Vetoed Features
Vetoed features are features that have been ruled out either in the short term or long term. A feature being on this list doesn't mean that it will never happen, merely that it is considered either less important or (more likely) too much work to be implemented any time in the near future.
- Changing the format of the generated
.h file
- Purely because it means cluttering up the export form with everybody's favourite formatting options, and I worry about how many different options people will want if given the option.
- Saving and loading sprites to and from
.json files instead of .xml
- At the moment I can't be bothered to find or write a library that I like, and wouldn't consider it unless someone can demonstrate a suitable use case/requirement. I'm sorry if you don't like XML, but that was the easiest option given the tools I had available.
- Frame duplication generating a unique name
- Changing brush size
- Dither patterns
- Animation features of any kind
- Ensuring that frame dimensions are multiples of eight
- The Arduboy library documentation claims this is a requirement, but
Sprites has accomodated non-multiples-of-eight for at least 4-6 years, so I consider the documentation to be erroneous until proven otherwise
Tutorial
To be added at a later date.
Frequently Asked Questions
Why does reordering namespaces and sprites not reorder them in the output file?
This is because of how sprites and namespaces are currently represented internally. I would like to fix this oversight at some point when I have settled upon the most appropriate solution.