ordoor/doc/formats/obj.md

# Obj format information

The names of Obj files are highly suggestive of them being objects that can be
placed on [maps](map.md). Each map cell seems to have space for four objects to
be placed on it - a `SURFACE`, `LEFT`, `RIGHT`, and `CENTER`. Maps reference
objects in a space-efficient way via sets, which seem to be a kind of object
palette.

## Assign

The `Assign/` directory contains a matching `.asn` file for each `Obj/*.obj`.
It's a plain-text format which seems to assign properties to frames, and has
references to a `<name>.flc` file which does not exist in the tree.

Theory: .obj files were originally generated from `.flc` files. This is an
AutoDesk format for visual data, so this suggests the .obj files contain pixels
\o/

`blank.asn` references 6 frames (0-5):

```
# single pixel tile
# transpix.obj/.asn   
#/--> transpix.flc
#

0-5:DEF 1;   


0-5:TYPE 13;


END OF FILE
```

`jungtil.asn` references 18 frames (0-17):

```
# jungle floor
# jungtil.obj/.asn
#   /--> d:\warflics\missions\jungtil.flc
#

0:DEF 2;
1-11:DEF 454;   


#damaged frames!!!!
12:DEF 2;   
13-16:DEF 454;   
17:DEF 454;


0:TYPE 2;
1-11:TYPE 0;
12:TYPE 2;
13-16:TYPE 0;   
17:TYPE 0;


0:DESTROY 12;  
1-3:DESTROY 13;  
4-6:DESTROY 14;  
7-9:DESTROY 15;  
10-11:DESTROY 16;  
17:DESTROY 15;

1-11:Dmg1Lnk 17;

END OF FILE
```

So it seems this visual data can have quite complicated attributes. At a minimum
we see:

* `TYPE`
* `DEF`
* `DESTROY`
* `Dmg1Lnk`

The `type` field **may** tell us what format each sprite is in.

## OBJ container structure

`.obj` files represent visual data. They contain a number of sprites, which are
assigned attributes in `.asn` files and referenced from `.map` files.

The container format is worked out, but the per-sprite data is still unknown, so
I'm documenting the former here while still investigating the latter.

The file begins with a header, with all values 32-bit little-endians:

| Offset | Meaning |
| ------ | ------- |
| 0x0000 | Number of sprites          |
| 0x0004 | Offset of sprite directory |
| 0x0008 | Size of sprite directory   |
| 0x000c | Offset of the sprite data  |
| 0x0010 | Size of the sprite data    | 

The sprite directory contains an 8-byte record per sprite. That record contains
two 32-bit little-endians:

| Offset | Meaning |
| ------ | ------- |
| 0x0000 | Relative offset of sprite in data block |
| 0x0004 | Size of sprite in data block |

For sanity checks, we can ensure that:

* The header, sprite directory and data blocks do not overlap or extend past the
  end of the file
* None of the individual sprites overlap each other or extend past the end of
  the data block

## Sprite structure

First, the `blank.obj` file. `blank.asn` helpfully tells us that it's a single-
pixel tile and assigns it a type of 13. There are six sprites, all of which are
identical. Data dump:

```
-------------------------------------------------------------------------------
        0  1  2  3  4  5  6  7       01234567     0   1   2   3   4   5   6   7
-------------------------------------------------------------------------------
0x0000 10 01 61 01 01 00 01 00     |   a      |  16   1  97   1   1   0   1   0
0x0008 00 00 00 00 03 00 00 00     |          |   0   0   0   0   3   0   0   0
0x0010 00 00 00 00 00 00 00 00     |          |   0   0   0   0   0   0   0   0
0x0018 01 fd 00                    |          |   1 253   0
```

Total size is 27 bytes, so if there *is* only one pixel, it's tempting to
suggest that the first 24 bytes are header, and the final 3 bytes represent that
one pixel.

I think this is rendered as a 1px dot with the colour `#ff00ff` in WH40K_TD.exe:

![blank.obj as rendered by WH40K_TD.exe](img/blank.obj.png)

In the tile, the dot is in the very centre.

The colour itself doesn't show up in the data directly, so it's not a simple RGB
array of pixels. WH40K_TD.exe is a 256-colour application, so the pixel data may
account for 1 of the 3 bytes.

```
----------------------------------------------
        0  1  2  3  4  5  6  7       01234567
----------------------------------------------
0x0000 fa 00 25 01 2e 00 48 00     |       H  | 250   0  37   1  46   0  72   0 
0x0008 00 00 00 00 f4 0c 00 00     |          |   0   0   0   0 244  12   0   0 
0x0010 00 00 00 00 00 00 00 00     |          |   0   0   0   0   0   0   0   0 
0x0018 80 0f 90 1a 4b 1a 1b 4b     |     K  K | 128  15 144  26  75  26  27  75 
0x0020 1a 4c 1a 4b 19 19 49 19     |  L K  I  |  26  76  26  75  25  25  73  25 
0x0028 4a 18 4a 80 0f 00 80 0b     | J J      |  74  24  74 128  15   0 128  11 
0x0030 98 1a 4c 1a 4c 1a 9e 1a     |   L L    | 152  26  76  26  76  26 158  26 
0x0038 4c 1b 4b 1a 1a 49 19 48     | L K  I H |  76  27  75  26  26  73  25  72 
0x0040 18 18 48 19 4b 19 4b 19     |   H K K  |  24  24  72  25  75  25  75  25 
0x0048 9d 80 0b 00 80 08 9e 1a     |          | 157 128  11   0 128   8 158  26 
0x0050 4a 1a 1b 4d 9e 1a 4c 1b     | J  M  L  |  74  26  27  77 158  26  76  27 
0x0058 1b 4c 1b 4c 1a 1a 49 18     |  L L  I  |  27  76  27  76  26  26  73  24 
0x0060 48 17 49 18 19 4a 19 4b     | H I  J K |  72  23  73  24  25  74  25  75 
0x0068 19 9d 4a 1a 49 80 08 00     |   J I    |  25 157  74  26  73 128   8   0 
0x0070 80 07 a0 19 4b 1a 1b 4c     |     K  L | 128   7 160  25  75  26  27  76 
0x0078 1b 1b 4d 9e 1b 4c 1b 4d     |   M  L M |  27  27  77 158  27  76  27  77 
```

Total size is 3340. The first 24 bytes look quite different to the remainder of
this file, lending weight to the 24-byte header theory.

Line-by-line comparisons of first 16 bytes (all TYPE 13). 0x10..0x17 are all
0x00 in all examples so far.

```
a: blank.obj sprite 0, 1x1 tile (27 bytes)
b: pillar.obj sprite 1 (3340 bytes)
c: altar.obj sprite 0 (7465 bytes)
d: altar.obj sprite 1 (7368 bytes)

a 0x0000 10 01 61 01 01 00 01 00     |   a      |  16   1  97   1   1   0   1   0
b 0x0000 fa 00 25 01 2e 00 48 00     |       H  | 250   0  37   1  46   0  72   0
c 0x0000 d6 00 16 01 74 00 67 00     |     t g  | 214   0  22   1 116   0 103   0 
d 0x0000 d6 00 19 01 74 00 64 00     |     t d  | 214   0  25   1 116   0 100   0 


a 0x0008 00 00 00 00 03 00 00 00     |          |   0   0   0   0   3   0   0   0
b 0x0008 00 00 00 00 f4 0c 00 00     |          |   0   0   0   0 244  12   0   0
c 0x0008 00 00 00 00 11 1d 00 00     |          |   0   0   0   0  17  29   0   0 
d 0x0008 00 00 00 00 b0 1c 00 00     |          |   0   0   0   0 176  28   0   0 
```

Assuming a 24-byte header, 0x0c matches "remaining pixeldata" size in all cases.

0x04 makes sense as x,y dimension in `blank.obj` where we *know* it's 1x1 pixel.

The pillar has more Y than X; the altar more X than Y, suggesting 0x04-0x05 are
X and 0x06-0x07 are Y. Measuring the rendered pixels by WH40K_TD.exe gives a
close correspondence in all cases.

WH40K_TD.exe crashes trying to load a set referencing `pillar` in it unless it's
in the CENTER position. Interesting.

| Offset | Purpose |
| ------ | ------- |
| 0x0000 | ?
| 0x0004 | x,y size (16 bits each) |
| 0x0008 | ? (blank in all cases so far)
| 0x000c | Size of remaining pixeldata |
| 0x0010 | Padding? |
| 0x0014 | Padding? |

We still don't know what the first 32 bits are all about.

The volume represented by a cell is a little odd. We see three faces of a fake
3D volume of size 64x64x32(ish). This is presented in an isomorphic fashion, so
the height is 32px at the leftmost and rightmost extents and 96 in the centre.
Overall width is 128px, and the minimum rectangle covering the whole space would
be 128x96, or 12288 bytes at 8bpp.

It seems pixels can be larger than a cell - TZEENTCH.OBJ is almost 2 cells high,
for instance.

0x002-0x003 changes in step with total number of pixels, but that doesn't seem
to account for the difference.

Considering sprites with a 1,1 x,y.

```
           u0 u1 u2 u3 X  Y    pixeldata
bgtree_m 24 : ee 00 5e 01 01 01   01 1f 00
blank     0 : 10 01 61 01 01 01   01 fd 00
transpix  0 : 11 01 3c 01 01 01   01 ae 00
```

Sprites seem to end with a \x00 byte in-general, but we *only* see 0x01 in the
first byte of data for these 1x1 tiles.

Sprites with `X= 128 Y=63` *almost always* seem to have a u0..u3 of
`d1 00 42 01` with a few exceptions, e.g. `treemac{1,2}.obj`

Investigating the sprite data a little more, it seems that we tend to have Y
null-separated records: 1 record for sprites with a height of 1, 100 for those
with a height of 100, etc.

The first byte of each record seems likely to specify format - it's mostly
invariant (always 1 for the 1x1 examples, almost always 0x80 for the altar
sprites and the majority of other .obj files). Some other values appear too, but
not a wide distribution.

Number of bytes per row varies. `altar.obj` is diamond-shaped, and the widths
are also diamond-shaped, so perhaps 0x80 means "center the data around the X
origin and assume anything unspecified is transparent"?

Result, with my rendering according to those rules on the left and WH40K_TD.exe
on the right:

![Altar sprite 0 rendering attempt](img/altar_sprite_0.png)

Hurrah!

WH40K_TD.exe loops around "ReadInMissionFLCs", incl. address 0x0041dd10, where
it loads in all the .asc and .obj files in a set.

```
break *0x41DD10
```

This lets me focus very narrowly on what happens when loading sprites, and
might give clues.