DTS File Format Info & Help

Hopefully if you're reading this you want to know what the DTS file format is, or have some knowledge of it.

I've search high, I've search low, I've searched varying levels inbetween. My resounding conclusion is that anyone who knows what the format is all about hasn't the time to document anything, which is all too often the case with stuff like this.

So, as I'm going I've decided to simply splurge out my findings right here in public. They may (will) be wrong, incomplete, and incomprehensible. But it's better than nowt. Hopefully someone will be able to make some sense of what I've written out here.

Personally, I'm only insterested in making static models. So no bones or animation. Which is a pretty good low-spec starting point to work out what's what in the DTS.

Just before we get down and dirty, some thanks going out to Chris Calef for helping me out and pointing me in the right direction, and to Sven 'RaCooN' Knie who wrote out an earlier specification in German. Cheers chaps.


--------------------
From this point foreward, everything's subject to errors and thus change
--------------------


So, where to begin? Well if you've read around the subject already then you aught to know that to be of any use a minimal DTS needs:

1 Bounds-node containing info as to size, position, and orientation
1 Mesh
1 Mesh-node containing mesh info
1 Collision mesh
1 Collision-node containing collision mesh info

(In 3DS models I've looked at there exist a base-node and a start-node, though they don't seem to be in the final exported DTS, I'm assuming they are merely for structure with 3DS and it's exporter)

With this in mind I put together my very own lump of programmer-art in 3DS: a cube with a cube-collision hull and a cube for the bounds-node. Not visually impressive, but easier to read than a full humanoid when we break open the DTS in a hex editor. Which is the next step...

As a sidenote, I'd like to recommend HxD as a hex editor. Free. Simple. Fast. http://mh-nexus.de/HxD.htm

Primarily a DTS is broken up into 32-bit values. That's four bytes, eight hex-digits. The first value in the DTS is the version number:

18 00 7C 00

However, this is in little-endian format, so it should be read as:

00 7C 00 18

Taking a bit of a trek through some code I came across this little snippet (adding the comments myself):

tsShape.cc [1233]
s->read(&smReadVersion); // read first 32-bits (int)
mExporterVersion = smReadVersion >> 16; // eg: 00 7C 00 18 >> 16 = 00 7C . 00 18 = 7C
smReadVersion &= 0xFF; // eg: 00 7C 00 18 & FF = 18

Assuming here that read() gets the first 32 bits of the file. If you do the maths, ExporterVersion becomes 7C and Version is 18

Whether ExporterVersion is actually used to any grand purpose I'm not sure. But the Version value is used for backwards-compatibility within the engine. We are not bothered about earlier versions, so Version for us will always be 18. We won't deal with anything less than version 18 (note: I'm going to be using hexadecimal pretty much throughout this post, it makes life easier, hex version 18 is version 24 in decimal).

We read in 32-bit integers for each value, corresponding in this order:

[head]
Versions
TotalCount - The total number of 32-bit ints to read in
Offset16 - Byte-offset into data where 16-bit values begin
Offset8 - Byte-offset into data where 8-bit values begin

[data header]
Nodes
Objects
Decals
Subshapes
IFLMaterials
Node Rotations
Node Transitions
Node Scales (Uniform)
Node Scales (Aligned)
Node Scales (Arbitrary)
Ground Frames
States?
Triggers
Details Levels
Meshes
Skins
Names
Smallest Size
Smallest Detail
Checkpoint 00
Radius
Tube Radius
CenterX
CenterY
CenterZ
MinBoundsX
MinBoundsY
MinBoundsZ
MaxBoundsX
MaxBoundsY
MaxBoundsZ
Checkpoint 01

[had to split my post, it's way too long, continued in next post...]