PIE File Specifications

By: Stratadrake

Build: 1.2.5

Date:12/26/2004

Based on observations made apart from, and with the WZ Source Code.

== File Header ==
Warzone PIE files can be written in either text or binary; however, whether WZ uses the binary format at all, I don't know; only the text PIE format seems to ever be used in the PC version. Nonetheless, WZ's source code contains routines for both.

'''Introductory Note:''' As a text format, PIE files obviously contain a lot of numbers. Only integer numbers and hexadecimal are allowed -- floating-point is not supported, and may even cause Warzone to crash.

Simple Header:
PIE 2
TYPE 200

Full Header:
PIE n
TYPE ver

''n'' PIE type number, one of the following. Only PIE type 2 is proven to be supported by Warzone. 
1 = Original (depreciated) PIE format 
2 = Current PIE format. Supports NOTEXTURE directive and long texture filenames. 
3,4 = Supported, but exact effects unknown. 
9 = PSX only: Sprite 
10 = PSX only: Line projectile

''ver'' PIE subtype number, a hexadecimal combination of flags. Warzone's source code includes a full listing of constants, but there is no clear distinction between TYPE flags and polygon flags, and thus it's difficult to identify what flags are used where:

+0x1 = XEffect 
+0x2 = View Plane 
+0x4 = World Plane 
+0x8 = Projectile effect 
+0x10 = Binary 
'''+0x20 = Indicates the presence of two-sided polygons in the model ''' 
+0x100 = Flat 
'''+0x200 = Textured - requires TEXTURE or NOTEXTURE directive to follow next ''' 
+0x400 = Wireframe 
+0x800 = Trans 
+0x1000 = Gouraud 
+0x2000 = No Cull 
+0x4000 = Outline 
+0x8000 = Fix View

'''NOTE:''' The presence or absence of the +20 flag has no effect. Warzone automatically sets the +20 flag itself when it reads a two-sided polygon from the PIE file.

== Texture Definition ==
If the PIE file's type includes the +200 flag (and it usually does), a texture directive must follow next. PIE files are a hardware-dependent format in the sense that they include supplemental information describing how the PIE file was created, that is not necessarily used when loading the file for use in WZ. The format of the TEXTURE directive is indicative of this.

NoTexture Definition -- PIE 2 format only:
NOTEXTURE 0 NOTEXTURE 256 256
(This is not a full understanding, but it works. Pie files rendered with NOTEXTURE appear solid white.)

Typical Texture Format:
TEXTURE 0 page-##.pcx 256 256

Full Texture Format:
TEXTURE type page-##.pcx w h
''type'' 0=PCX texture, other values are not supported. 
''page-##.pcx'' This is the filename of the model's texture page. The filename must begin with page-## and end in .pcx , where ## is a page number to identify the texture by in memory. Warzone will use whichever texture with a matching page number was loaded by the current video-memory WRF. If Warzone cannot locate one, it will return an error and crash.

'''NOTE:''' EditWorld / World Edit, unlike Warzone, require the texture filename to be exact. 
'''NOTE:''' The PIE 1 format does not support spaces in the texture filename. 
'''NOTE:''' The PIE 2 format does not support periods in the texture filename apart from the ".pcx" extension.

''w h'' Dimensions of the texture this PIE file was created with. Since Warzone is wired for 256x256 textures, both values are usually set to 256.

Warzone will automatically scale 512x512 textures to 256x256 in size. The reverse, however, is not true. If you supply a 128x128 sized texture, it will not be scaled or even padded out to the 256x256 size. Instead, areas outside of the 128x128 area are invalid, may contain data such as other, adjacent texturepages, and should not be used.

== Submodel Definition ==
PIE files are divided into submodels, or levels. Submodels are used for animation purposes -- currently limited to scavenger infantry, cyborgs, and the oil derrick. All other Warzone models are 'static' and only the first submodel is used.

The submodel structure of a PIE file can be summarized like this:
LEVELS n-models
LEVEL 1
.
. data for submodel 1: points, polygons, connectors, BSP data...
.
LEVEL 2
.
. data for submodel 2
.
LEVEL 3
.
. etc.
.

''n-models'' This is the number of submodels contained in the PIE model; it also indicates how many "Level ##" lines you'll need to include. If your Warzone model contains only one submodel (it usually will), then the only lines you'll need to worry about are the first two--"Levels 1" to indicate one submodel and "Level 1" to specify the model data.

== Submodel Data -- Points ==
Points are the basic building blocks of a PIE model. A submodel's point structure looks like this:
POINTS n-pts
x y z
x y z
x y z
. . . (etc.)

''n-pts'' This indicates how many points Warzone will buffer for the PIE data. Warzone expects to find exactly (3*n-pts) terms following this section. For ease of reference, the points data is usually grouped to three terms per line. 
''x y z'' Coordinates for that point. The positive x axis points east, the y axis points up, and the positive z axis points north; and a value of 128 cooresponds to one map-square worth of distance along the corresponding axis.

'''NOTE:''' All PIE files are implicitly understood to point "south" -- i.e. negative z values will be located towards the "front" of the PIE file.

'''IMPORTANT:''' Pie Slicer's x and z axes point the opposite directions as Warzone's x and z axes.

== Submodel Data -- Polygons ==
Polygons are the visible portions of a PIE model; they are the squares, triangles, and other flat sides that are strung together to make an object visible in Warzone gameplay. A polygon data block is complex, so I'll describe it one step at a time. The overall polygon data block looks like this:
POLYGONS npolys
type npts ptdata ani texdata
type npts ptdata ani texdata
type npts ptdata ani texdata
. . . (etc.)

''npolys'' Indicates how many polygons to buffer in memory. Warzone expects to read exactly this many polygons from the data that follows. 
''type'' This is a 3-, 4-, or 5- digit hexadecimal number that indicates the polygon's properties. Due to a lack of distinction between TYPE flags and polygon flags, not all these flags are known, and only the ones in bold are proven to be supported: 
+0x100 Flat 
'''+0x200''' Textured. It has yet to be confirmed whether non-textured polygons will render in Warzone, so consider this flag required. 
+0x400 Wire Frame 
'''+0x800''' Transparent. Indicates that the polygon's texturemapping includes transparent areas. Due to a lack of color-keyed alphablending, Warzone will automatically disable filtering for this polygon, and its texture will appear to pixelate. Hence, this option is called "No Filter" in Pie Slicer. 
+0x1000 Gouraud Shading 
'''+0x2000''' Two Sided. Indicates that the polygon is visible regardless of camera angle. Otherwise, the polygon is visible only from the direction of its normal vector, and will otherwise be culled (hidden) from view. 
'''+0x4000''' Animated. Indicates that the polygon has an animated texture. This is typically used for explosions and team-color variations. 
+0x8000 Use PSX texture allocation method. Exact meaning for the PC is unknown. 
+0x10000 BSP data. Indicates a polygon generated during BSP creation/conversion. 
''npts'' Indicates how many points (vertexes) to buffer for this polygon. The PIE format supports from 1 to 16, but the rendering code only supports from 1 to 10 vertexes. 
''ptdata'' A list of (npts) point indexes that identify which points are required by this polygon. The first point read from the PIE file is understood to have a point index of zero.

'''NOTE:''' Warzone calculates a polygon's normal vector based on its first, second, and last vertex. Unfortunately, this means that if a polygon is not coplanar/flat, then the polygon may be culled from view even if a part of it should be visible. If this occurs, declaring the polygon as two-sided, or breaking it up into its component triangles, will fix the error.

''anidata'' Type +0x4000 polygons only. A list of four terms identifying the texture animation for this polygon:
max time width height

''max'' The number of animation frames available for this polygon. 
''time'' The time delay between each frame. NOTE: Due to various oversights during Warzone's development, this only works on weapon-firing GFX. Explosion and effect GFX are animated at a fixed 100ms per frame. 
''width'' The horizontal offset between each frame. Must be within the range (1,256), inclusively. Cannot be zero. 
''height' The vertical offset between each frame. Generally, each frame of animation is located to the right of the previous frame, up to a certain point, after which the next frame is wrapped downwards by this value.

'''TIP:''' Animated textures can be made to scroll vertically (instead of horizontally) by specifying 256 for the frame width.

'''NOTE:''' Animated textures loop. If one polygon has 3 frames, another polygon has 8 frames, and Warzone renders frame 5, the first polygon will be drawn using frame 2 (=5 % 3).

'''NOTE:''' Warzone stores a separate copy of this data (presumably) to record whether the overall PIE file has any animated textures or not. The "overall" data is equal to the anidata specified by the last type +4000 polygon read from file. Whether this produces any ill effects or not is unknown.

''texdata'' Type +0x200 and +0x8000 polygons only. The texture data for the polygon is stored as a list of (2*npts) terms, arranged into pairs of u/v coordinates. In theory, each coordinate would be within the dimensions allowed for the texturepage, but since Warzone is hardwired towards 256x256 textures, the texture coordinates must be in the range (0-256), inclusively.

Since the polygon format is flexible and may include a widely varying number of terms, here are a few examples of polygons:
200 3 14 13 12 111 208 111 216 106 210
2200 3 18 19 21 106 210 111 216 111 208
4200 4 33 32 31 30 8 1 11 11 36 114 34 103 29 103 27 114
6A00 3 26 25 24 8 1 11 10 110 224 115 234 104 234

== Submodel Data -- Connectors ==
Connectors are points used to assemble multiple PIE files together into a model. In short, they identify where another PIE file attaches or "connects" to the current PIE file.

CONNECTORS nccs
x z y
x z y
x z y
. . . (etc.)

''nccs'' Indicates how many connectors to buffer in memory. Warzone expects to find (3*nccs) terms following this line. Up to 256 connectors are supported, but only the first two connectors in a PIE file are of any real use. 
''x z y'' The location of the connector. They use the same axes and scale as points, but for some reason, the Z and Y axes are listed in reverse order.

== Submodel Data -- BSP ==
BSP data is used to optimize the polygon rendering order in a PIE file, a process used primarily before the arrival of z-buffers. Since Warzone uses a z-buffer, the BSP data is essentially moot. Nonetheless, it is formatted as follows:

BSP nBSP
LeftLink FwPolyIndexes -1 BackPolyIndexes -1 RightLink
LeftLink FwPolyIndexes -1 BackPolyIndexes -1 RightLink
LeftLink FwPolyIndexes -1 BackPolyIndexes -1 RightLink
... (etc)

''nBSP'' The number of BSP criteria to buffer for the PIE file. Warzone will expect to read that much data from the file. 
''LeftLink'' A BSP index, or -1 for none. 
''FwPolyIndexes'' Optional, may be omitted. A list of polygon index for rendering. 
''BkPolyIndexes'' Optional, may be omitted. A list of polygon index for rendering. 
''RightLink'' A BSP index, or -1 for none.

How BSP Data Works: 
When Warzone evaluates the BSP tree at run time, it evaluates a sorting plane hidden with each BSP criteria and determines whether the camera is viewing the plane from in front or behind.

If the front of the sorting plane is visible, WZ will:
# Evaluate the BSP data at node #LeftLink (recursive)
# Renders polygons #FwPolyIndexes (polygons #BkPolyIndexes will be culled)
# Evaluate the BSP data at node #RightLink (recursive)

Otherwise, WZ will:
# Evaluate the BSP data at node #RightLink (recursive)
# Renders polygons #BkPolyIndexes (polygons #FwPolyIndexes will be culled)
# Evaluate the BSP data at node #LeftLink (recursive)

Other Notes: 
* When no BSP data is supplied, Warzone will always render a PIE file's polygons in the same order that they were loaded from file, and a z-buffer must be present to sort them properly.
* A BSP tree has a maximum capacity of 65,534 (0xFFFE) items. Obviously there is no real risk of hitting this limit.
* Due to the nature of BSP rendering, the total number of BSP items will be approximately equal to the total number of polygons.
* Any polygon index not included in the BSP tree will not be rendered. Conversely, no polygon index may occur more than once in the BSP tree.
* The nature of BSP data also includes support for culling normal (one-sided) polygons.
* The first BSP link in the BSP tree is often -1 -1 -1 1.
* ''BkPolyIndexes'' are usually omitted.
* No polygon may be indexed more than once.

== Sample PIE File - blderik.pie ==
Here is an example of the Oil Derrick PIE file - notice that it is split into three submodels, and they are used to make its swinging animation during Warzone. The exact values for the swinging motion are stored in a sepatate file with a different format, so that is another story.

PIE 2
TYPE 200
TEXTURE 0 page-11-player buildings.pcx 256 256
LEVELS 3
LEVEL 1
POINTS 54
-52 7 -21
51 7 -21
51 7 22
-52 7 22
-52 0 -21
51 0 -21
51 0 22
-52 0 22
-15 30 -6
43 30 -6
43 30 7
-15 30 7
-20 7 -8
48 7 -8
48 7 9
-20 7 9
-57 0 -39
57 0 -39
57 26 -39
-57 26 -39
57 0 39
57 26 39
-57 0 39
-57 26 39
-42 7 -18
-45 8 -18
17 82 -4
17 77 -4
-45 8 -20
17 82 -9
-42 7 20
-45 8 20
17 82 12
17 77 12
-42 7 18
17 77 7
17 82 7
-45 8 18
-24 71 -1
-27 71 -1
-27 5 -1
-24 5 -1
-24 71 1
-24 5 1
-27 71 1
-27 5 1
22 8 -20
22 80 -8
17 80 -8
17 7 -20
22 80 9
17 80 9
22 8 21
17 8 21
POLYGONS 28
200 4 3 2 1 0 65 8 127 8 127 15 65 15
200 4 0 1 5 4 254 48 210 48 210 0 254 0
200 4 1 2 6 5 1 140 57 140 57 176 1 176
200 4 2 3 7 6 254 48 210 48 210 0 254 0
200 4 3 0 4 7 1 140 57 140 57 176 1 176
200 4 11 10 9 8 92 10 123 10 123 13 92 13
200 4 8 9 13 12 235 14 213 14 211 4 237 4
200 4 9 10 14 13 20 165 38 165 41 173 18 173
200 4 10 11 15 14 252 14 230 14 228 4 254 4
200 4 11 8 12 15 20 165 38 165 41 173 18 173
2a00 4 19 18 17 16 64 37 106 37 106 47 64 47
2a00 4 18 21 20 17 64 37 106 37 106 47 64 47
2a00 4 21 23 22 20 64 37 106 37 106 47 64 47
2a00 4 23 19 16 22 64 37 106 37 106 47 64 47
200 4 27 26 25 24 242 36 242 39 219 4 220 4
200 4 29 28 25 26 42 147 57 173 54 173 36 147
200 4 33 32 31 30 242 36 242 39 219 4 220 4
200 4 37 36 35 34 115 9 82 14 82 13 113 9
200 4 36 37 31 32 20 147 5 173 2 173 13 147
200 4 41 40 39 38 104 8 106 8 106 10 104 10
200 4 43 41 38 42 94 8 98 8 98 10 94 10
200 4 45 43 42 44 86 8 87 8 87 10 86 10
200 4 40 45 44 39 94 8 98 8 98 10 94 10
200 4 49 48 47 46 255 48 210 48 210 0 255 0
200 4 48 51 50 47 109 15 83 15 83 8 109 8
200 4 51 53 52 50 255 48 210 48 210 0 255 0
200 4 46 47 50 52 58 140 42 176 17 176 0 140
200 4 51 48 49 53 41 176 17 176 0 140 58 140
LEVEL 2
POINTS 8
-26 73 -5
-20 73 0
-26 73 5
-32 73 0
-26 22 -5
-20 22 0
-26 22 5
-32 22 0
POLYGONS 5
200 4 3 2 1 0 84 12 87 11 90 12 87 12
200 4 0 1 5 4 104 14 96 14 96 10 104 10
200 4 1 2 6 5 96 14 88 14 88 10 96 10
200 4 2 3 7 6 104 14 96 14 96 10 104 10
200 4 3 0 4 7 96 14 88 14 88 10 96 10
LEVEL 3
POINTS 26
12 80 7
8 98 7
26 103 7
31 85 7
12 80 -6
31 85 -6
26 103 -6
8 98 -6
-59 66 2
-61 75 2
17 96 2
19 88 2
-59 66 -1
19 88 -1
17 96 -1
-61 75 -1
-60 95 3
-67 90 3
-67 90 -2
-60 95 -2
-68 64 3
-68 64 -2
-50 35 3
-50 35 -2
-44 39 3
-44 39 -2
POLYGONS 16
200 4 3 2 1 0 247 40 246 48 239 46 240 38
200 4 7 6 5 4 226 46 219 48 217 40 224 38
200 4 5 6 2 3 20 146 20 140 38 140 38 146
200 4 6 7 1 2 114 13 105 13 105 10 114 10
200 4 7 4 0 1 38 141 38 147 20 147 20 141
200 4 11 10 9 8 111 14 110 15 68 13 69 13
200 4 15 14 13 12 123 13 82 15 81 14 122 13
200 4 14 15 9 10 110 12 68 12 68 11 110 11
4200 4 19 18 17 16 8 1 31 11 31 252 30 247 30 247 31 252
4200 4 18 21 20 17 8 1 31 11 30 247 17 241 17 241 30 247
4200 4 21 23 22 20 8 1 31 11 17 241 0 244 0 244 17 241
4200 4 25 19 16 24 8 1 31 11 1 248 31 252 31 252 1 248
4200 4 22 24 16 20 8 1 31 11 0 244 1 248 31 252 17 241
4200 3 20 16 17 8 1 31 11 17 241 31 252 30 247
4200 4 19 25 23 21 8 1 31 11 31 252 1 248 0 244 17 241
4200 3 19 21 18 8 1 31 11 31 252 17 241 30 247

== Sample Pie File - TrmVCan.Pie (HPV Cannon muzzle) ==
This is an example of a PIE file utilizing BSP data (note the presence of type +0x10000 polygons).

When Warzone reads a BSP tree from a PIE file, it will use the tree's data to determine the back-to-front rendering order at run-time instead of simply rendering them in the order which they were loaded from file (and relying on a z-buffer to sort them properly). Note that the BSP tree data includes every polygon index in the file, which is important because any polygon index not included in the BSP tree will not be rendered.
PIE 2
TYPE 200
TEXTURE 0 page-17-droid weapons.pcx 256 256
LEVELS 1
LEVEL 1
POINTS 22
-15 0 16
16 0 16
12 0 -20
-12 0 -20
-18 14 -11
-20 14 1
-23 7 0
-21 6 -14
-12 0 -15
-4 13 -12
-6 13 3
-14 0 0
5 13 -12
7 14 14
-7 14 14
-12 0 -16
-17 13 -11
-7 13 14
-13 0 0
-5 13 2
-12 0 -14
-13 0 -6
POLYGONS 17
14200 3 8 21 20 8 1 18 9 2 47 0 43 2 46
14200 4 9 15 18 19 8 1 25 7 5 21 2 27 13 27 15 20
14200 4 7 20 21 11 8 1 18 9 18 45 2 46 0 43 0 40
14200 3 7 11 6 8 1 18 9 18 45 0 40 17 39
4200 4 5 6 11 10 8 1 18 9 16 40 17 45 0 47 0 38
14200 4 0 17 19 18 8 1 25 7 25 27 24 20 15 20 13 27
10200 4 10 9 16 5 16 205 15 193 1 195 2 208
14200 3 14 9 17 8 1 25 7 24 20 5 21 24 20
4200 4 14 13 12 9 8 1 16 19 16 19 2 19 4 0 13 0
4200 4 7 6 5 4 8 1 18 10 5 46 17 46 18 40 8 41
10200 3 4 5 16 1 196 2 208 1 195
4200 4 7 4 9 8 8 1 18 9 0 35 2 30 17 29 16 37
14200 3 3 15 9 8 1 25 7 0 27 2 27 5 21
4200 4 9 12 2 3 8 1 18 9 4 29 14 29 16 37 2 37
4200 4 13 14 0 1 8 1 18 9 2 38 16 38 18 47 0 47
4200 4 3 2 1 0 8 1 18 9 2 37 16 37 18 28 0 28
4200 4 12 13 1 2 8 1 25 7 5 21 24 20 25 27 0 27
BSP 18
-1 -1 -1 1
2 16 -1 -1 -1
3 15 -1 -1 -1
4 14 -1 -1 -1
5 13 -1 -1 -1
6 11 -1 -1 17
7 9 -1 -1 16
8 6 -1 -1 14
9 4 -1 -1 13
10 1 -1 -1 11
-1 0 -1 -1 -1
12 3 -1 -1 -1
-1 2 -1 -1 -1
-1 5 -1 -1 -1
15 8 -1 -1 -1
-1 7 -1 -1 -1
-1 10 -1 -1 -1
-1 12 -1 -1 -1