Special colors in the JSON Animation format


while extracting DEF animations into JSON animations and back, I noticed that one place which supports JSON animations are the creature animations in the fort. See the attached image to see how it looks like.

The underlying PNG images are indexed/palette PNG images which have the exact same palette as the DEF files from which they were created. As one can see, the first color in the palette gets correctly handled as transparency. But other special colors like for the shadow do not get interpreted this way. While this shortcoming is probably on your TODO list I wondered about the following questions:

  1. What kind of PNG images do you or do you plan to support with the JSON animation format? Do you plan to restrict it to palette PNG images or do you allow RGB as well?

1.1. If you allow only palette images, then content creators have to take care that whatever program they use to generate PNG images from their SVG graphics or 3D models, that the first eight colors in the palette are indeed the special ones that map to transparency, shadows and selection highlight. This would require a conversion program which can arrange colors in the palette accordingly. Such a program has to take care that those special colors do not unintentionally appear anywhere else in the image.

1.2. If you allow RGB images, then how do you plan to support special colors mapping to transparencies, shadows and selection highlights? Will it just be fixed RGB values that will represent them? If yes, what RGB values will it be? It seems that most (82%) DEF files use the following first eight colors as the first ones in their palette: #00ffff #ff96ff #ff64ff #ff32ff #ff00ff #ffff00 #b400ff Does this look right? This method bears the problem that, in contrast to the palette method, these special colors cannot be used in any image in the whole game. With using a palette it doesnt really matter what the actual color values are. Only the palette index matters. With RGB the special colors have to be avoided entirely. This includes that one must take care not to accidentally produce a special color through antialiasing or resizing effects. Solutions to this problem use the alpha channel to encode special colors:

1.2.1. In an RGBA image, all pixels with an alpha value of 0 are special colors. The RGB values of those pixels must correspond to the special colors #00ffff #ff96ff #ff64ff #ff32ff #ff00ff #ffff00 #b400ff to indicate their function.

1.2.2. In an RGBA image, all alpha values that are not 256 encode a special color. The RGB value is ignored. For example alpha values from 0-7 could encode the eight special colors.

  1. What is your stance on other formats for animation like MNG. Currently, the artist has to take care to use the exact same palette for all frames in their animation (because most animation have to be converted into the DEF format). This requires some post processing to find the overall optimal palette. Formats like MNG would only have one global palette per default.

I am asking these questions because through my packaging vcmi for Debian I came in contact with content creators who are interested in what kind of PNG images to create, how the palette has to look like or what the special colors are. So what is your position on the points above? What rules do you see as sensible? Are RGB images allowed? If yes, what are the special colors? Do you think that RGBA is okay with the special color encoding in the alpha channel?

I’m mostly interested in proper support for RGBA (including full support for alpha channel). There is not much sense in replacing current def container with something that will be as restricted as before. All code that supports Json animation should also work with RGBA images.

Of course this raises some problems like what to do with that glue selection in battle, how to handle some palette-base effects (bloodlust, petrification, clone). I have some ideas on how to implement this but so far this was quite low-priority.

As for this particular case - I think that it can be called as a bug. If an image has palette then special colors should work. Possible issues:

  • palette was reordered during conversion. Not much I can do here - smart detection of proper palette index may be too heavy CPU-wise.
  • we rely on SDL image loader. If loaded image that we receive from SDL does not have palette then this is SDL bug that may be fixed in SDL 2.0 already.
  • image was converted somewhere in our code. I can investigate this if I’ll get such images.
  1. AFAIK both apng and mng have quite poor support in image editors.
  2. Neither one is supported by image loader we use (SDL_Image)
    If somebody among artists think that using one of these formats is a good idea then we may add support for it in vcmi (although this depends on availability of libraries that support these formats)

BTW - if there will be some activity on graphical side then I’ll raise priority of full support for Json animation - so far this was quite low priority since no-one will actually use this.

As i remember, there are three colours for shadows (you can open your frame in editor and by color detection tool get at least 2 colours (border of shadow and shadow). Deep shadow colour is used very rarely.

Than you can replace these 2-3 colours automatically by transparent shadow colours (they must have alfa-channel value and be grey). You can take that colours from some 32-bit PNG from Internet that has transparent shadows.
Background color (usially 0,0,255 as i remember) to be removed

Sorry for my english.

It’s problem of content maker than, i think.
There is some tool in Photoshop allowing to create 1 pixel contours.
Or some colour effect to frames when unit mouse-selected can be used.
Maybe someone wants to do another type of selection for unit - like oval selection near feet (like in HMM4 etc).


Nearly, but there are a number of irregularities when it comes to the special colors in the beginning of the palette. There are a number of outliers. For example, 2.4 percent of all DEF animations do not have #00ffff as their first color. About 9 percent of animations do not have #ff96ff as the second color but #ff0000 instead. So even when it comes to finding the special colors, it is not 100% clear which ones they are.

Automatic replacement of colors is no problem. In the end (at least for now) my tools have to convert all input images to palette based PNG files and then further on to DEF animations. The reason for my question was rather to find out what the goal of vcmi was with respect to natively supporting RGBA input images. Because there seem to be no such plans yet, we now decided for the following scheme for the RGBA images:

The alpha channel marks whether a pixel contains a special color or not. An alpha value of 0xff means normal color and an alpha value of 0x00 (fully transparent) means special color. The RGB values of all pixels that are marked as special color then decide what special colors is picked. We currently support the following special colors: #00ffff #ff96ff #ff64ff #ff32ff #ff00ff #ffff00 #b400ff. The choice was made based on the fact that 82% of the DEF animations use these as the first eight colors in their palette.

This approach has the advantage that special colors are not taken into account for resizing or antialiasing effects.

It is of course up to vcmi to decide for a different scheme once they support RGBA images as input. I only wanted to know if there was a plan already. In case there was I would’ve implemented that one instead of cooking up a custom solution for now. Once vcmi decides for a solution we will obviously change to that one.

The problem is not how to get a pixel value where I want it. The problem is what pixel values vcmi wants to represent certain special functions like shadows, selections and transparency.

Okay. I’ll just convert everything to palette and DEF animations. That’s no problem.

In case you are curious and have some free time I attached the first frame of the hydra. As you can see the palette of the PNG image has the eight special colors in the beginning. Additionally, converting them into DEF creates working DEF animation with correct shadows. So I doubt it’s a problem with the palette.

Okay. Fair enough :slight_smile:

I didn’t mess with this kind of stuff replacing colours, i didn’t work with creatures in form of JSON.
But i messed up with 32-bit PNGs for town screen.
There is no some special colours.
I make set of frames in Paint.Net, save them as PNG, and than make JSONs for them.
Creatures have about 21 groups of animation. I think you just draw creature frames in 32-bit ordinary PNG, not forgetting to use transparent background and transparent shadows. There are some frame groups that need selection graphics drawn in every frame of them (Mouse Up group for example). They just will show as they are in graphic editor, as it is now.

Oh - and there is another alternative to mng/apng. We can use spritesheets instead. Yes - they will need some coding time to make them work but so does mng/apng support.

What exactly we should use for animation (apng/mng/spritesheets) - I’d rather leave this to artists. If there will be some more-less common position among artists on what format is most suitable for vcmi I can look into implementing it.

I think you can use proper RGBA instead of special colors everywhere.

So for all conversions from def’s -> convert to proper RGBA, with semi-transparent shadows
For all new content - just forget about presence of special colors. Making image work with vcmi will be my problem.

Yes, right now this will work only in places where json animation work but with time I’d like to have it supported anywhere. Currently biggest issue here is CPU usage - not much can be done here till we’ll get hardware acceleration.

Right, spritesheets are yet another option. As you said it’s ultimately up to the designers what they feel most comfortable handling. I cannot create art but I can write some code converting it to whatever vcmi wants :slight_smile:

Full RGBA support could allow some nifty things like different kinds of shadows, dragons breathing transparent fire, see-through water elementals etc. Though as you also already said, some things get lost. One such thing are palette based spell effects and others are for example the selection outline or the shadow border. On the other hand, both can be computed by vcmi itself: Most palette effects can be accomplished by rotating the color hue and selection outlines can be calculated by region growing around all non-transparent pixels. So there are ways to work around that but they need implementing and more CPU and of course there are many other things that are more important to do right now :slight_smile:

But I see that in the future you want to use RGBA images as they are, using their transparency as real transparency and creating shadows through semi transparent alpha information. Once somebody starts implementing support for that, there will be a phase where RGBA images are supported somewhere while the rest still relies on DEF animations. So there must be a way to convert the full RGBA images to DEF animations.

So lets scratch my earlier plan and do it the following way: artist creates some full RGBA image and my script converts full transparency (alpha=0) to palette value 0 and interprets anything between full and no transparency as shadow (no matter their RGB value), converting it to palette value 4 (that should be the correct entry for shadows, right?). It will then calculate the pixels that are the shadow border (by finding shadow pixels adjacent to fully transparent ones) and give them palette value 1. The selection highlight can be found by finding those pixels which are opaque but bordering transparent pixels. These would get palette value 5. I deduced the palette values from the comments in client/CAnimation.cpp - are those meaning accurate? Do the other palette values which I didnt mention hold some special value that I should take care of?

I save the result either as palette PNG image for all objects that support JSON animations or convert them to DEF animations for everything else.

Does that sound reasonable?

Actually it already supported - try converting those animations from 1st post into proper RGBA replacing special colors with proper alpha - this should give you fort window with fully functional 32-bit animations (possibly - along with 100% CPU usage).
If not - then you’ve found a bug that must be fixed.

CPU usage as well as all special effects - I’d like to fix them with hardware acceleration support. SDL 2.0 looks promising so it may be easier than it looks like.

So for places that support json animation - convert images to 32-bit graphics, ignoring such issues like lack of special effects (reporting them to make sure that I know about these issues is a good idea though)
Othervice - convert to def’s with palettes and special colors. Not much we can do here at the moment.

You haven’t mentioned colors #6 and #7 - those are selection highlight on top of shadow and on top of shadow border respectively

Wow! It actually seems to work to set an alpha value of like 50% for the shadow!

That’s because I have no clue what “highlight on top of shadow and on top of shadow border” mean. Can you give me an example DEF animation where those colors are used and what they are supposed to denote in these animations?

In the creature DEF files I only see three different special values being used. Index 0 for full transparency, index 1 for the shadow border and index 4 for the main part of the shadow. I can find selection highlights (index 5) in town buildings if I remember correctly.

These colors are for situations where shadow intersects with selection highlight. Check this image from lich animation (CPLICH.DEF)
dl.dropboxusercontent.com/u/223 … colors.png

Purple bits are #6 “selection over shadow”.
When selection is visible this color acts as selection (#5), othervice - it acts as shadow (#4).

Green bits are #7 “selection over shadow border”.
When selection is visible - acts as selection (#5), othervice - as shadow border (#1)

for your purposes - what about splitting image into two:

  1. Fully colored image that contains creature itself and shadow
  2. Grayscale image that contains only selection.

Second set of images should be registered in Json as group #23

Then during gameplay when vcmi needs to draw selection on top of unit vcmi will draw normal frame first and then - selection (including recoloring to needed color & with required transparency)

This will allow us to avoid finding methods to generate selection in runtime which can become too complicated in case of semi-transparent units.

Thanks, that made me understand colors 6 and 7.

Should the selection image not be black&white (binary) and not grayscale?

Currently I see groups 1 and 2 with selection highlights. Are therefore not also two groups of selection images needed, each corresponding to group 1 and 2 respectively?

I guess such a solution would even make more sense in general because if the units themselves are transparent, then no algorithm can tell where they start or end (at least no cheap algorithm). With your solution it is up to the artist to define the contour of the object. I think that makes perfect sense. And of course it avoids costly computation at runtime.

For H3 images it will contain only two colors - white for pixels with selection and black for empty pixels (or vice versa). But I’d like to keep possibility of non-opaque selection highlight so shades of grey can be used to indicate semi-transparent highlight. So I’d rather keep image grayscale.

Yes, you’re right. Then we’ll have to use groups #23 and #24.

Right. That makes sense.

Attached is a screenshot of RGBA animations in the fort. I made the shadows white transparent instead of black transparent to make sure that the shown shadows are my modified RGBA images and not accidentally the original DEF animations. As you can see the transparency works just as expected! Unfortunately, as you said, CPU usages goes up. Before I had 8-10% in the fort and now it’s 25-30%. Certainly not a good thing for vcmi on low end devices.

I also modified my converter code according to your suggestions how real RGBA animations should work in the end. It now unpacks DEF animations to RGBA images (storing the shadow with the transparency values that vcmi uses for them) and repacks RGBA images into a DEF by calculating a common palette and transforming transparent areas into the special shadow colors. I attached an image of one full round-trip of DEF to RGBA to DEF. Everything looks exactly as it is supposed to look (I tested all start buildings in the town and a battle) except the fog of war boundaries. That the fog of war boundaries do not work is easily explainable by the fact that the original boundary gets translated to some alpha value but when converting back to DEF all alpha values are interpreted as shadows. Thus information gets lost. I guess this small slip is acceptable until the adventure map supports RGBA animations.

It’s because no hardware acceleration. Fully build town screen lags significally now.
Hope this will be improved one day.

By the way, there is some project of now unknown state aiming to create game based on VCMI:
Developer is trying to use open graphics. So maybe you can contact him in search for graphics content for debian version.
Or you can help him release his game on Debian. There are less towns than in VCMI/HMM3. But VCMI allows to disable standard towns, maybe this will be already enough to Debian package to proceed.

Hello Ivan. From my point of view I would like to see Vcmi support PNG files with alpha channel. All animation frames as separate files (png) . For example a folder called “Creature Animations” and inside of it folders for creatures like “pikeman” “medusa” etc. In those folders frames of animation :
… and so on

Furthermore some json setting file to set some things like : movement (normal walks or teleport) , range attack type (arrow or beam or lightning bolt like)
maybe the size of pngs (resolution) and some pixel cordinates to where animation should be placed in game (it is easier to fix such thing in conf file then re edit all the frames in graphical program)

Separate files are nice to have a work in progress and edit frames and check how they end up in game.

When starting legends I decided to do anims (I do have most of the needed anims as 3d animations) at the end because I hoped for high color palette and something more friendly then def. I still have a lot to do with non animated 2d graphics (map objects and menu, all the icons) so for now it is not a priority at least for me, since I’m not gone use it yet… However someday I will need it :slight_smile:

The state is active and in development .

movement (normal walks or teleport) - gameplay-wise flying units behavior is identical to teleporting units. Therefore teleportation is subtype of flying bonus - check wiki for description of flying bonus. Setting subtype to 1 will turn flying units into teleporting.

range attack type (arrow or beam or lightning bolt like) - definitely should be configurable but this feature is still not implemented.

maybe the size of pngs (resolution) and some pixel cordinates to where animation should be placed - this is a possibility, although I can’t say for sure at this point. Quite a lot of code relies on size of animation and its position on screen. Replacing all of it will take time.

On the other hand - to properly add all of this to the game you’ll need to have moddable engine to begin with Switching my priority to animation code will means postponing features in other areas. There is no best choice here unfortunately.
But thanks for letting me know current state of your project :slight_smile:

Already supported. Creature animation through PNGs with alphachannel is not working on battle field, but in town is already implemented.
The issue is a high cpu usage currently.