vcmi/docs/modders/Animation_Format.md

< Documentation / Modding / Animation Format

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.

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"
        }.
        ...
    ]

}

Creature animation groups

Animation for creatures consist from multiple groups, with each group representing specific one animation. VCMI uses groups as follows:

Basic animations

• 0

• 1

  moved on the creature

• 2

  not acting

• 3

• 4

  defending and was hit in melee

• 5

• 6

  killed by ranged attack

Rotation animations

• 7

  part of animation, with stack turning towards viewer

• 8

• 9

• 10

Melee attack animations

• 11

• 12

• 13

Ranged attack animations

• 14

• 15

• 16

  downwards

Special animations

• 17

  group attack animations were not found

• 18

  group attack animations were not found

• 19

  group attack animations were not found

Additional H3 animations

• 20

  animation starts.

• 21

  ends.

Additional VCMI animations

• 22

  dead. If not present, will consist from last frame from "Death" group

• 23

  creature is dead after ranged attack. If not present, will consist from last frame from "Death (ranged)" group

• 24

  is resurrected. If not present, will consist from reversed version of "Death" animation

Spellcasting animations

• 30

  upwards

• 31

  facing front

• 32

  facing downwards

Group attack animations

• 40

  multiple target, with primary target facing up (Dragon Breath attack, or creatures like Hydra)

• 41

  multiple target, with primary target facing front (Dragon Breath attack, or creatures like Hydra)

• 42

  multiple target, with primary target facing downwards (Dragon Breath attack, or creatures like Hydra)

Proposed format extensions

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

{
    // 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
    ]
}