1PIE 2/3 2======= 3 4Description 5----------- 6 7The PIE format is a custom model format created by Pumpkin. 8 9It has gone through two iterations since the original commercial release. PIE 2 was used until version 2.3 and is still supported. PIE 3 is the de facto standard now, and newer models should use it. 10 11PIE 2 uses integer coordinate values ranging from 0 to 256, corresponding to 1024 pixels for texture pages. 12For example, the coordinates 128,256 refer to pixel coordinates 512,1024. 13 14PIE 3 uses floating point UV coordinates which range from 0 to 1, usually with six digits. 15Thus, the coordinates 0.111111,1.000000 represent offset 113.777777,256 for a picture 1024x1024 pixels large. 16For texture repetition, UV coordinates can be negative numbers. Only Helicopter models currently contain those, with a precision of eight digits. 17 18Format 19------ 20 21### PIE 22 23> PIE 3 24 25The first line specifies the version number -- either 2 or 3. 26 27### TYPE 28 29> TYPE 211 30 31This indicates the type of the file through a hexadecimal combination of the flags 0x200, 0x10 and 0x1. 32The following flags are available: 33 34* 0x00001 -- Disables additive rendering 35* 0x00002 -- Enables additive rendering 36* 0x00004 -- Enables premultiplied rendering 37 38* 0x00010 -- Rolls object to face the camera. Used for projectiles shaped like a cylinder. 39* 0x00020 -- Pitches object to completely face the camera. Used for projectiles shaped like a sphere. 40 41* 0x00200 -- Reserved for backward compatibility. 42* 0x01000 -- Specifies that the model should not be stretched to fit terrain. For defensive buildings that have a deep foundation. 43* 0x10000 -- Specifies the usage of the TCMask feature, for which a texture named 'page-N_tcmask.png' (*N* being a number) should be used together with the model's ordinary texture. This flag replaced old team coloration methods (read ticket #851). 44 45### INTERPOLATE 46 47> INTERPOLATE 0 48 49Optional. Specifies if the model wants to have interpolated frames. Default is set to interpolate. 50 51### TEXTURE 52 53> TEXTURE 0 page-7-barbarians-arizona.png 0 0 54 55This sets the texture page for the model. Each file must contain exactly one such line. 56In theory you could leave out this line, but in practice that makes your models useless. 57Note that the exact texture page file may be modified by WRF files during level loading, so that the texture matches the tileset. 58 59The first parameter (the zero) is ignored. 60 61The second gives you the filename of the texture page, which 62* must only contain the characters [a-zA-Z0-9.\_\\-] ([a-z] is not meant to include any lowercase character not found in the English alphabet). 63* should start with "page-NN-" for correct handling of dynamic texture replacement. 64* should end with the letters ".png". 65 66The third and fourth parameters give the size of the texture, and are also ignored, since we can just read that info from the texture page itself. 67You may fill them out with the correct values for backward compatibility. 68 69### NORMALMAP 70 71> NORMALMAP 0 page-7-barbarians-arizona_normal.png 72 73Optional. As above, but this sets the normal map texture page for the model. 74 75### SPECULARMAP 76 77> SPECULARMAP 0 page-7-barbarians-arizona.png 78 79Optional. As above, but this sets the specular map texture page for the model. 80 81### EVENT 82 83> EVENT type filename.pie 84 85An animation event associated with this model. If the event type is triggered, the model is 86replaced with the specified model for the duration of the event. The following event types are defined: 87 88* 1 -- Active event. What this means depends on the type of model. For droids this means movement, 89 while for power generators it means they are linked to a power source. 90* 2 -- Firing. The model is firing at some enemy. 91* 3 -- Dying. The model is dying. You (almost) always want to make sure animation cycles for this model is set to 1 for the specified model -- if it is zero, it will never die! 92 93### LEVELS 94 95> LEVELS 1 96 97This gives the number of meshes that are contained in this model. Each mesh can be animated separately in ANI files. 98 99### LEVEL 100 101> LEVEL 1 102 103This starts the model description for mesh 1. Repeat the below as necessary while incrementing the value above as needed. 104 105### MATERIALS (disabled) 106 107This feature was removed in commit 823cf08bb18cf24852bac8595b3899aca12d4f7b. 108 109> MATERIALS 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 20 110 111Optional. Specifies the material properties of a mesh. The nine first values give the RGB values for ambient, diffuse and specular lighting, respectively. The last value sets shininess. 112 113### SHADERS (disabled) 114 115This feature is currently unsupported. 116 117> SHADERS 2 vertex.vert fragment.vert 118 119Optional. Create a specific shader program for this mesh. The number 2 is not parsed but should always be 2. 120 121### POINTS 122 123> POINTS n 124 125This starts a list of vertex coordinates (points) with the number of lines *n*, which must be less than or equal to 768. This is followed by the list of points. 126 127#### Point lines 128 129> -4.0 4.0 8.0 130 131Each point *must* be on a separate line and *must* be indented with a tab. It *must* contain exactly 3 floating-point values in the order *x y z*. Y denotes "up". 132 133### NORMALS 134 135> NORMALS n 136 137Optional. This starts a list of vertex normals with the number of lines *n*, which *must* be equal to number of polygons below (otherwise we revert to calculating normals). This is followed by the list of normal lines. 138 139#### Normal lines 140 141> -1.0 0.0 0.0 0.0 -1.0 0.0 0.0 1.0 0.0 142 143Each line *must* be indented with a tab. It *must* contain exactly 3 normals (one per indexed vertex in a corresponding polygon line) and each normal *must* contain exactly 3 floating-point values in the *x y z* order. 144 145### POLYGONS 146 147> POLYGONS n 148 149 150This starts a list of polygon faces with the number of lines *n*, which must be less than or equal to 512. 151 152#### Polygon lines 153 154> 200 3 3 2 1 0.82 0.78 0.186 0.78 0.199 0.82 155 156Each polygon *must* be on a separate line and *must* be indented with a tab. 157 158> Flags Number\_of\_points Point\_order [Optional\_animation\_block] Texture\_coordinates 159 160##### Flags 161 162* +200 means the polygon is textured. Each entry in POLYGONS must have this flag. 163* +4000 means the polygon has a team colour or animation frames. If it is set, an animation block is required. 164* No other flags are supported. Note that if you want a surface to display something on both sides, make two polygons, one for each side. 165 166##### Number of points 167 168* The first number is the number of points for this polygon. Only triangles are supported, so each entry *must* use 3 points. 169 170##### Animation block 171 172If the flag +4000 is set, the following 4 arguments must follow: 173* First, add the number of texture animation or team colour images provided. For team colour, it is always 8. 174* Second, add the playback rate. The units are game ticks per frame (effectively millisecond per frame), and appear to be used exclusively for animating muzzle-flash effects. Unfortunately, the default value is typically '1' which is far too rapid to actually see the muzzle-flash animating. :( 175* Third and fourth add the x and y size (width and height) of the animation frame. The x value cannot be zero -- if you want a texture animation to scroll vertically instead of horizontally, specify a width of 256. 176 177##### Point order 178 179* This is a list of indexes to the list of points given in the POINTS section. 180 181##### Texture coordinates 182 183* Give texture coordinates for each point. There are two texture floating-point coordinates for each point, hence this list should be twice as long as the number of points. The coordinate is given in UV 0.0-1.0 range. 184 185### CONNECTORS 186 187> CONNECTORS n 188 189This starts a list of connectors for the model with the number of lines *n*. 190 191Connectors are used to place and orient other components with this one. 192Not every model requires them; the meaning of each connector is special and hardcoded, but generally speaking: 193 194* PIE models representing vehicle chassis should have two connectors: Connector 1 identifies the turret location for ground vehicles, while connector 2 identifies the turret location for VTOL weaponry. (Note that VTOL weapon turrets are oriented upside-down with respect to ground turrets; this is part of the rendering process and is not actual model geometry.) 195* Likewise, PIE models representing structures may have one connector indicating where to place a sensor or weapon turret. 196* Turrets themselves, weapon or otherwise, are actually assembled from two separate PIE files -- one represents the base mount and one represents the muzzle. Of these two: 197* The turret base mount may have one connector indicating where the turret muzzle is located, however this appears to be respected only for cyborg weaponry (where the "turret base" is the cyborg torso graphic, and the "turret muzzle" is the side-mounted weapon graphic). Turret muzzles on vehicles and structures are both located with respect to the chassis/structure connector, ignoring any connectors present on the base mount. 198* Turret muzzles should have one connector on their business end to indicate where the muzzle-flash graphic is displayed while the weapon is firing. 199 200#### Connector lines 201 202> -8 -14 24 203 204Each connector must be on a separate line and must be indented with a tab. 205It contains the x, y, and z coordinates of a connector. Note that unlike in point coordinates, the Z coordinate denotes "up". 206 207### ANIMOBJECT 208 209> ANIMOBJECT time cycles frames 210 211If the mesh is animated, this directive will tell the game how to animate it. The values 212are the total animation time (of all frames), the number of cycles to render the animation, 213where zero is infinitely many, and finally the number of animation frames that follows. 214 215#### Animation frame lines 216 217> frame xpos zpos ypos xrot zrot yrot xscale yscale zscale 218 219(note order x,z,y order here! but not for scale where its x,y,z!) 220 221Each animation line starts with a tab followed by 222 223* the serially increasing frame number 224* three 3-dimensional vectors, one for position, one for rotation, and one for scaling. 225 226NOTE: For position and rotation - but not scaling - Y and Z are swapped. 227 228If the scaling values are negative, they indicate that the animation is a legacy 229keyframe animation sequence. Do not use this in future content. 230 231### SHADOWPOINTS _(optional)_ 232 233> SHADOWPOINTS n 234 235This starts a list of vertex coordinates (points) with the number of lines *n*. This is followed by the list of points. This (along with `SHADOWPOLYGONS`) is used to provide an alternate (simplified) shadow mesh to improve performance (recommended if the normal mesh is complex / high-poly-count). If unspecified, the normal mesh is used for shadows. 236 237#### Point lines 238 239> -4.0 4.0 8.0 240 241Each point *must* be on a separate line and *must* be indented with a tab. It *must* contain exactly 3 floating-point values in the order *x y z*. Y denotes "up". 242 243### SHADOWPOLYGONS _(optional)_ 244 245> POLYGONS n 246 247This starts a list of polygon faces with the number of lines *n*. This (along with `SHADOWPOINTS`) is used to provide an alternate (simplified) shadow mesh to improve performance (recommended if the normal mesh is complex / high-poly-count). If unspecified, the normal mesh is used for shadows. 248 249#### Polygon lines 250 251> 0 3 3 2 1 252 253Each polygon *must* be on a separate line and *must* be indented with a tab. 254 255> Flags Number\_of\_points Point\_order 256 257##### Flags 258 259* 0 means the polygon is untextured. Each entry in SHADOWPOLYGONS must have this flag. 260* No other flags are supported. Note that if you want a surface to display something on both sides, make two polygons, one for each side. 261 262##### Number of points 263 264* The first number is the number of points for this polygon. Only triangles are supported, so each entry *must* use 3 points. 265 266##### Point order 267 268* This is a list of indexes to the list of points given in the POINTS section. 269
