Animation Format

From VCMI Project Wiki
Jump to: navigation, search

VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def this format allows:

  • Overriding individual frames from json file (e.g. icons)
  • Modern graphics formats (targa, png - all formats supported by VCMI image loader)
  • Does not requires any special tools - all you need is text editor and images.

Note that right now this replacement is not supported fully: there are still some areas that can't use it. Most notable areas are:

  • Adventure map
  • Battles

Format description

{
    // Base path of all images in animation. Optional.
    // Can be used to avoid using long path to images 
    "basepath" : "path/to/images/directory/",

    // List of sequiences / groups in animation
    // This will replace original group with specified list of files
    // even if original animation is longer
    "sequences" :
    [
        {
            // Index of group, zero-based
            "group" : 1,

            // List of files in this group
            "frames" :
            [
                "frame1.png",
                "frame2.png"
                    ...
            ]
        },
        ...
    ],

    // Allow overriding individual frames in file
    "images" :
    [
        {
            // Group of this image. Optional, default = 0
            "group" : 0,

            // Imdex of the image in group
            "frame" : 0,

            // Filename for this frame
            "file" : "filename.png"
        }.
        ...
    ]

}

Proposed format extensions

Void format

  • vcmi client [Todo]
  • map editor [Done]

Json header may be omitted. In such case a single frame will be loaded from same resource ID. Resource id should have no extension, image must be in SPRITES/ virtual directory.

Texture atlas format

TODO

  • arbitrary texture coordinates
  • margins
  • grid-like layout

Texture atlas format

{
    // Base path of all images in animation. Optional.
    // Can be used to avoid using long path to images 
    // If a path is a filename is is treated as single texture atlas
    "basepath" : "path/to/images/atlas/bitmap.png",

    // List of sequences / groups in animation
    "sequences" :
    [
        {
            // Index of group, zero-based
            "group" : 1,

            // List of files in this group
            "frames" :
            [
                {"x":0, "y":0, "w": 64, "h": 64},
                {"x":64, "y":0, "w": 64, "h": 64}
                    ...
            ]
        },
        ...
    ]
}

Texture atlas grid format

  • vcmi client [Todo]
  • map editor [Todo]
{
    // filename is is treated as single texture atlas
    "basepath" : "path/to/images/atlas/bitmap.png",
    
    //optional, atlas is a grid with same size images
    //located left to right, top to bottom
    //[columns, rows]
    //default [1,1]
    "gridCols":3,
    "gridRows":3,

    // List of sequences / groups in animation
    // sequence index -> images count in sequence
    "sequences" :
    [
        1,3,5
    ]
}


Modding related articles

Main articles
Modding changelog Modding guidelines Mod Handler


Formats
Mod file Format
Town Format Creature Format Hero Classes Format
Artifact Format Animation Format Hero Format
Bonus Format Object Format Spell Format


Work-in-progress formats
Building bonuses Map format
Bonus Type Format Random map template


Outdated pages
Mod system proposal