The Incredible Machine 2-3 ANM File Format

From ModdingWiki
Jump to navigation Jump to search

The animation (.ANM) sub-files are found in the archive file of The Incredible Machine 2 (TIM 2) and 3 (TIM 3). They contain the information required for drawing puzzle part sprites, which are often comprised of multiple sub-images of image files and for animations of the puzzle parts. They are also used for animated parts of the game's user interface (for example the animated icons of the main menu). It can also contain commands for playing sound effects.

Most .ANM files (all in TIM 2) contain two chunks, starting with "ANM:" and "TAG:", respectively. Both use the typical "Dynamix chunk" format, starting with the 4-byte chunk type ("ANM:"/"TAG:", followed by the chunk size in 32-bit, little endian format. Unlike other Dynamix file formats, the most significant bit in the 32-bit size of the first chunk is not set. A small number of files in TIM 3 contain a third chunk, "LAB:", with an unclear meaning.

The "ANM:" chunk

Not counting the chunk type and size, an "ANM: chunk has five parts, a 16 or 22 byte header, and four sections containing the actual sprite/animation frame/animation data, labeled here as A-D.

Header

The "ANM:" chunk (not counting the "ANM:" chunk type identifier and the chunk size) starts with a header, with a size of 16 or 22 bytes, depending on the magic number. It has the following Format: 

 UINT16LE magic_number_1;
 UINT16LE magic_number_2;
 UINT16LE size_section_a;
 UINT16LE size_section_b;
 UINT16LE size_section_c;
 UINT16LE size_section_d;
 UINT16LE anm_width;
 UINT16LE anm_height;
 /* 3 members, found only in files with a magic number of 0x54 0x42 0xEA 0x03: */
 UINT16LE unknown_16;
 UINT16LE unknown_18;
 UINT16LE unknown_20;
  • magic_number_1, magic_number_2: The header starts with a 4-byte magic number. The first two bytes are always 0x54 0x42. The second two bytes are a 16-bit little endian file version number. In TIM 2, the possible values 1000 (0x3E8) or 1001 (0x3E9). There is no obvious difference in the format of the files using these two numbers, however, 0x3E9 is much more common and 0x3E8 is mostly used for relatively small and simple files. In TIM 3, a small number of files use a newer version of the .ANM file format, with a magic_number_2 value of 1002 (0x3EA). Such files have a slightly different format compared to files with the other two numbers. The "newer" format is used in the user interface and the game menu, but never for puzzle part graphics.
  • size_section_a: The number of entries in the A section of the "ANM:" chunk, one entry is 2 byte (i.e. the section is an array of 16-bit integers). Several files do not have an A section (size_section_a == 0)
  • size_section_b: The number of entries in the B section. One entry is 12 bytes in the files in files with magic_number_2 = 0x3EA, 10 bytes in all other files.
  • size_section_c: The number of entries in the C section, one entry is 4 bytes.
  • size_section_d: The size of the D section in bytes.
  • anm_width, anm_height: Width and height of the animation. In .ANM files for puzzle parts, the two structure members usually have the same value as width_1 and height_1 for the part in puzzle/level files.

Structure members found only in files with the longer header (magic_number_2 = 0x3EA):

  • unknown_16: 0x14 in all files, perhaps the size of header minus magic_number_1. Files with the longer header do not contain additional section in "ANM:" chunk, so it cannot be a size of such a section.
  • unknown_18: 0 in all files
  • unknown_20: 0x17 in one file, 0 in all others. Clearly not the size of an additional section in "ANM:" chunk. ! Additional research needed

Section A

Section A is empty in a large number of .ANM files. If present, it is an array of 16-bit little endian integers. It contains all numbers from 0 to the number of items in B section minus 1, in increasing order, with some numbers repeated. For example 0 1 1 1 2 means that the animation frame with index 1 in section B must be shown for the duration of 3 timer ticks instead of 1.

Section B

Section B is a list of structures containing 16 bit integer members, 6 if magic_number_2 is 0x3EA, 5 in the other versions of the file format. It contains essential information about each animation frame. One structure has the following members: 

 INT16LE relative_pos_x;
 INT16LE relative_pos_y;
 UINT16LE width;
 UINT16LE height;
 UINT16LE section_d_offset;
 /* Note that the last member is only present in files with */
 /*     magic number 0x54 0x42 0xEA 0x03 */
 UINT16LE unknown_10;
  • relative_pos_x, relative_pos_y: The coordinates where the animation frame must be drawn, relative to other frames. For the first item in the B section, the value of both tare typically 0, however there are a few exceptions. The relative position may be negative.
  • width, height: The width and the height of the graphics in the specific animation frame.
  • section_d_offset: An offset in section D, points to the first command required for drawing the animation frame.
  • unknown_10: The meaning is unclear. Often, but not always a number divisible by 3. ! Additional research needed

Section C

A section C item has the following format: 

 UINT16LE first_frame_id;
 UINT16LE state_id;
  • first_frame_id: The meaning of first_frame_id is slightly different between files containing or not containing an A section. If the A section is not present, this is the index in section B for the first animation frame for a particular animation. If there is an A section, first_frame_id is an index in the A section, and the 16-bit array item at this index is the required section B index. The section B indices determined this way essentially divide the B section into sub-sectons. One sub-section corresponds to the "animation" of a puzzle part or an user interface element in one specific state. If an "animation" has only one section B item, then the puzzle part or button/icon is not animated in this state.
  • state_id: An internal identifier used by the game for a state of the puzzle part or an user interface element. In a specific "state", the puzzle part (or user interface element) may or may not be animated, the animation frames belonging to such a state must be determined using the first_frame_id member.

Section D

The D section contains the instructions on how to draw each animation frame (or to play a sound). The section_d_offset field in the corresponding section B entry determines where the sequence of commands start for each animation frame. There are 6 different types of commands, numbered 0-5. Each command starts with its number in a 16-bit, little endian format. For commands 2-5, this is followed by a list of 16-bit integer parameters, the number of the parameters depends on command number.

Command 0: End of animation frame

Command 0 indicates the end of an animation frame in the file. It terminates the list of commands associated with a section B item. Command 0 has no parameters and is always 2 bytes long (the 16-bit command number).

Command 1: End of "ANM:" chunk

The last two bytes of section D (and the "ANM:" chunk) are always 01 00 (1 in 16-bit little endian format). These two bytes can be interpreted as a 2-byte command that terminates section D and the entire "ANM:" chunk. Command 1 is not found anywhere else in section D.

Command 2: Draw BMP sub-image

Command 2 is an instruction for the game engine to draw a sub-image from a .BMP image stored in the archive file of the game. It should be noted that a part sprite is often "cut into" multiple .BMP sub images, and in a few cases, they are stored in more than one file. Command 2 has five 16-bit integer parameters (size is 12 bytes, including the command number). 

 UINT16LE command_num;  /* 2 */
 UINT16LE bmp_file_num;
 UINT16LE bmp_sub_image_num;
 INT16LE draw_pos_x;
 INT16LE draw_pos_y;
 UINT16LE flip;
  • bmp_file_num: Index of the .BMP file in the TAG: chunk. The index of the first image is 1.
  • bmp_sub_image_num: The "sub-image" number of the .BMP file to draw. .BMP images in TIM 2 can have multiple sub images.
  • draw_pos_x, draw_pos_y: The position of the image (top left corner), relative to the x and y coordinates in the corresponding section B item.
  • flip: The image can be drawn horizontally and/or vertically flipped relative to its original orientation. 1 = vertical flip, 2 = horizontal flip, 3 = both, 0 = no such transform is applied.

Command 3: Draw rectangle

Command 3 draws a rectangle with a border and fill color provided as arguments. It is mainly used in user interface elements and in the graphics shown in the part help screen, rarely in puzzle part graphics. It has the following format: 

 UINT16LE command_num;  /* 3 */
 INT16LE draw_pos_x;
 INT16LE draw_pos_y;
 UINT16LE rect_width;
 UINT16LE rect_height;
 UINT16LE border_color;
 UINT16LE fill;
  • draw_pos_x, draw_pos_y: Coordinates of the top left corner of the rectangle.
  • rect_width, rect_height: The width and height of the rectangle.
  • border_color: The border color for the rectangle. In TIM 2, one color from the 16-color palette.
  • fill: The value of the fill parameter is either 0 - no fill, border only - or a value between 0x8000 and 0x800f where the least significant nibble contains the fill color.

Command 4: Draw line

Command 4 draws a line between two end points with a specific color. Like the rectangle command, it is mainly used for game interface graphics, not the puzzle parts. The format of the command is: 

 UINT16LE command_num;  /* 4 */
 INT16LE x1;
 INT16LE y1;
 INT16LE x2;
 INT16LE y2;
 UINT16LE line_color;
  • x1, y1: The coordinates of one end point.
  • x2, y2: The coordinates of the other end point.
  • line_color: The color of the line, one color from the 16-color palette in TIM 2.

Command 5: Play sound

If the command list for an animation frame includes command 5, a sound effect will be played when the particular frame is shown. It has one 16-bit parameter, the ID of the sound. TIM 2 contains sounds in two different formats. Sounds with a number >= 3000 are stored in the archive file of the game (SX_3???.RAW). .RAW files are uncompressed 8-bit PCM audio files without any header. The rest of the files (with numbers < 300) are found in TIM2.SX. TIM 3 has .WAV files instead in the archive file an there is no TIM2.SX. (! TIM 3 sounds with numbers below 3000).

The "TAG:" chunk

The "TAG:" chunk contains the names of the .BMP sub-files (in the archive file of the game) required for displaying the animation. Not counting the "TAG:" chunk type identifier and the 32-bit chunk size, the first two bytes of the data contains the number of image file names in 16-bit little endian format. The remaining part of the data is the list of image file name entries. A single entry is a 16-bit image ID followed by a null-terminated string containing the name of the image. In TIM 2, the ID of the first image is always 1, however, there are exceptions to this rule in TIM 3 (but never in part graphics). There is no gap in the numbering of the images, this makes the image ID field somewhat redundant.

The "LAB:" chunk

The "LAB:" chunk is present in a small number of .ANM files in TIM 3. .ANM files for puzzle parts never contain such a chunk. The structure of the "LAB:" chunk is similar to "TAG:", it consists of the number of entries stored as 16-bit integer, followed by item ID-null terminated string pairs. The strings are apparently not user interface texts visible to the player.

Tools

The Incredible Machine level/image resource viewer (VOGONS) supports viewing animations in TIM 2-3 .ANM files.

Credits

This file format was reverse engineered by knt47. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

Retrieved from ‘https://moddingwiki.shikadi.net/w/index.php?title=The_Incredible_Machine_2-3_ANM_File_Format&oldid=10687’