SKM (3D Skeletal Model) File Format Specs

SKM - SKeletal Model

SKM is a file format used to define the in-game 3D meshes (models), such as critters, items, scenery objects, and so on. This is a Troika's proprietary format and it's not used directly in any known 3D suite (3ds Max, Maya, etc.). All 3D models for ToEE were originally made in Maya and then exported into SKM. Therefore, it may be (relatively) easy to write a Maya plugin that would export and import SKM files.

The SKM file is subject to the following limitations: there can be a maximum of 1024 bones per SKM, a maximum of
32767 vertices per SKM, and a maximum of 65535 triangles per SKM.

1. The Header.
The SKM header is as follows (I will use the C++ notation for the sake of simplicity of writing a plugin, if someone wil agree to make one in the future):

int BoneCount; // the number of bones in the SKM
int BoneOffset; // the offset to the bones' definition
int MaterialCount; // the number of materials in the SKM
int MaterialOffset; // the offset to the materials' definition
int VertexCount; // the number of vertices in the SKM
int VertexOffset; // the offset to the vertices' definition
int TriangleCount; // the number of triangles in the SKM
int TriangleOffset; // the offset to the triangles' definition
unsigned UNUSED_1; // padding, unused
unsigned UNUSED_2; // padding, unused

2. The Bone Definitions.
The bone definitions are located at the BoneOffset and can be represented by the following structure:

unsigned short BoneFlags; // the bone flags, see below
short BoneParent; // the parent of this bone
char BoneName[48]; // the name of the bone, a maximum of 48 chars, all symbols after the first zero char (0x00) are ignored
mat4x3 WorldInverse; // the 4x3 matrix for the WorldInverse. I'm not personally sure what this means, my friend who's a 3D modeller was telling me about this, so 3D modellers will probably have more idea about what this is.

The bone flags can be as follows:
0x00000000 - The Bone is non-static?
0x00000001 - The Bone is Static
Other flags may be in there, but they are unknown to me at the moment.

3. The Material Definitions.
The material definitions are located at the MaterialOffset and can be represented by the following structure:

char MaterialName[128]; // the name of the material, a maximum of 128 chars, all symbols after the first zero char (0x00) are ignored

4. The Vertex Definitions.
The vertex definitions are located at the VertexOffset and can be represented by the following structure:

vec3 Position; // the vertex position (vec3 = a combination of four floats; x,y,z, and an unused float value that may be coming from the fact that the structure is aligned to 128bits for SSE - thx to Leksey for finding out this extra padding that was missing!)
vec3 Normal; // the vertex normal (position normal?)
vec2 Texture; // the position of the texture (vec2 = a combination of two floats)
short UNUSED; // padding, is ignored
short WeightCount; // the count of weights for this vertex to follow (defines the number of associated bones and their weights to follow)
short Bones[6]; // the list of bones associated with this vertex; always six entries.
float Weights[6]; // the array of weights for the associated bones; always six entries.

5. The Triangle Definitions.
The triangle definitions are located at the TriangleOffset and can be represented by the following structure:

unsigned short MaterialID; // the ID of a material for this vertex, per the Material Definitions.
unsigned short Vertices[3]; // the three vertices comprising the triangle, per the Triangle Definitions.

-------------------
And that comprises the SKM file format. Hopefully these specifications will be of help to someone some day.

I'd like to say thanks to Steve Moret for clarifications made on this file format, and to SVZ for explaining some 3D stuff to me that helped me understand the contents of the SKM files.

NOTE: SKA (animation) specs are to follow shortly, as soon as I figure out some of its details. It appears to be harder than the SKM format, and needs some stuff to be sorted out before I can understand it completely and post the specs.

- Agetian

 

@ Everyone: I fixed the specs. Thanks to Leksey for pointing out a big mistake!

@ Leksey: Oops, my bad, I don't know where I was looking when I wrote those out.. Seems like I copied them out of my older blueprint which was totally wrong. Check them out again, I fixed them. Note that the last two elements always contain 6 entries, and the Weight is actually an array of floats, not shorts. Try to match this up, lemme know if it doesn't match again and I'll dig it some further.

SKA: this file format definition is progressing steadily but slowly, because I have some tough time decyphering some of the data in there. But it'll be released soon.

P.S. What are you using the SKM specs for? Are you willing to write a plugin? Please say yes, we definitely need a good 3D plugin.

- Agetian

 

Sweet, good job! It'll be nice to see a converter like that. Personally I'm not sure where to get the SDKs for Maya/3ds, so sorry - can't help with that. I'll let you know once I have some solid info on the .SKA format as well.

- Agetian

 

Hmm, maybe those are padding bytes necessary for the code to align structures to a certain boundary (and useless for the model itself). When I decyphered most of the ToEE file formats I noticed that there's a lot of room for padding because the structures that are written to disk are not packed, and therefore get padded according to the standards of the x86 architecture. If I'll be able to trace the data through a disassembler and if it proves to be meaningful, I'll update the specs. As far as I can see it by tracing the code, there's virtually nothing between the normal and texture coords. It may just be that the normal coords is a vec3, while the texture coords is a vec2, so it gets padded somewhere in-between. Also, note how a 'short' value follows a 'vec2' value. Short is 16bit, while a vec2 is a 32+32bit value. So, there's certainly room for another, rather large padding there.

As usual, I'll be on the lookout for some info on what this may be. For now, it's rather safe to assume that they are unused and serve the x86 padding purpose.

- Agetian

 

Hey, good job! This is exactly how I suppose it is, thanks for the clarification! Updating the specs...

- Agetian