ART tools HOWTO Mathieu Olivier v0.0.3, January 20, 2004 This document aims to describe how to use the ReBUILD Project's tools related to ART files. ______________________________________________________________________ Table of Contents 1. Introduction 2. Art2Tga 3. Tga2Art 4. An example with Monolith's Blood 5. Using "animdata.ini" 5.1 The contents 5.2 The format 6. Links ______________________________________________________________________ 1. Introduction BUILD is a 3D engine written by Kenneth Silverman and used by several well known computer games (Duke Nukem 3D, Blood, ...). This engine uses a particular file format to store its tiles and animations: the ART format. The ART tools are programs that allow you to read, create and modify such files. Currently, the ART tools are only composed by 2 binaries: Art2Tga and Tga2Art. The idea behind them is that it's easier to extract tiles from an ART file, modify them with some painting software, and then convert them back into an ART file, than to just use the old "EditArt" DOS program. 2. Art2Tga Syntax: art2tga Art2Tga is the utility which extracts tiles from an ART file. It puts them in TGA files named "tilesXXXX.tga" where "XXXX" is the internal ART index of the tile. Generated pictures are uncompressed and color- mapped (256 colors) TGA files. Art2Tga also produces a plain text file (anidata.ini) which contains the animation data for each tile of the ART file. You can find in this text informations related to the speed or the type of an animation for example. The whole format of this INI file is a little bit complicated and will be described ``later''. 3. Tga2Art Syntax: tga2art Tga2Art is the utility which allows you to merge several TGA files into one single large ART file. It uses an "animdata.ini" file to set the tile animation flags and values. You would probably use the "animation.ini" generated by Art2Tga as a working basis. Be aware that for now Tga2Art does a simple byte-to-byte comparison for verifying the validity of a TGA header; so, for the moment, it only accepts the TGA format used by Art2Tga. That's why I strongly recommend to use TGA files generated by Art2Tga as a working basis until we write a smarter TGA header parser. Moreover, Tga2Art takes the color palette of the first TGA file as a reference, so each TGA file must have the same palette or be rejected for the merge. Tga2Art does not generate a "palette.dat" file, or compare the TGA color palette with such a file, but it is something that we may implement later. 4. An example with Monolith's Blood Let's make a little modification in Blood. Create a new subdirectory under the Blood directory (call it "Mod" for example; so on my computer, I have "d:\Blood\Mod"). Copy a Blood ART file in it (I choosed tiles008.art because it was the smallest). Then add Art2Tga and Tga2Art binaries, and the "palette.dat" file for Blood. Open a DOS console and go to the newly created directory (on my computer: "d: cd \Blood\Mod:"). Then, unpack the tiles: "art2tga tiles008.art". A lot of TGA files should appear (from tile2048.tga to tile2303.tga) beside a text file (animdata.ini). You may notice that some TGA files are missing (tile2273.tga in my example); this is probably because these tiles are declared as empty (0 x 0) in the ART file, and Art2Tga does not create empty pictures. Open a TGA file of your choice, play with it (add some symbols, change some colors, ...), and save it. DO NOT modify its name or its color palette, or Tga2Art wouldn't be able to merge it with the other TGAs. Changing its height or its width may also be a problem, because the picture may be rendered at an invalid position into the game. This could hopefully be fixed later by modifying the animation data. Let's merge all this pictures: "tga2art tiles008.art 2048 2303". You should now have a new tiles008.art in the current directory, containing your modified picture(s). All you have to do now is to create a backup of the original ART file, and to put the modified one in the Blood directory. 5. Using "animdata.ini" 5.1. The contents Basically, animdata.ini contains 2 types of informations: tile data and animation data. The tile data is: X and Y center offset, and "other flags". I'm unsure about the utility of the center offset, but I think it is used to shift the picture before rendering. It's useful for an animation: you attach it to one point only and the "center offset" of each tile shifts the rendering to fit its moving. The "other flags" is normally unused flags, but some games may use it, so they are also saved. The animation data is: the length, the type, and the speed of the animation. The length is a number of pictures; the type can be "none", "oscillation", "forward", or "backward". The third information is not exactly a speed. It's computed as: frame_number = (totalclock / 2^speed), so a 'speed' of 2 means 30 frames/sec (30 = 120 / 2^2) because BUILD's clock run at 120 Hz (120 ticks/sec). 5.2. The format As you might have guessed, animdata.ini format is the same as classic INI files. It contains sections, which contain key / value pairs. Let's take an example to see which sections and keys can be found in our case. The following lines are extracted from the animdata.ini corresponding to Blood's TILES008.ART. [tile2228.tga] XCenterOffset=0 YCenterOffset=0 OtherFlags=8 [tile2274.tga -> tile2275.tga] AnimationType=forward AnimationSpeed=6 [tile2274.tga] XCenterOffset=0 YCenterOffset=10 OtherFlags=0 The names of the keys are self-explaining. The only little difficulty is to understand the sections. If the section's name contains only one TGA file name, it's a tile data section. If it contains 2 names separated by an arrow ('->'), it's an animation data section. Be aware that if a tile has an animation speed, animdata.ini must contain a section which stores this speed value, even if the tile is not part of an animation. In this case, the section name will be [tileXXXX.tga -> tileXXXX.tga], where both XXXX are the same. 6. Links o The ReBUILD Project : The ReBUILD Project home page o The BUILD port for Linux : the most advanced port of the BUILD engine to another OS. o The Blood source campaign : for the release of Blood source code. o Game File Explorer : a game resource file viewer and ripper.