Welcome to my tutorial describing the SMD file format.
For easier reading I have divided this tutorial into three parts.
The general information part: here you will get some general information about the SMD file format.
The second part is the reference SMD file part: you will get a description of the SMD file format.
If you want to know more about the sequence SMD file format the third part is definitely for you.
First I would like to tell you some general information/tips about the SMD format: back to the top
- The SMD format is a bone-based animation format (unlike md2 format that has a vertex morph target animation system)
- Each vertices has to be bound to a bone (must not be the same bone for all vertices)
- Each face must have a BMP texture (with 256 colors = 8 bit; better known as indexed color mode)
and the dimensions of a texture must be a power of 2
as in: 2^1 = 2; 2^2 = 4; 2^3 = 8; 2^4 = 16; 2^5 = 32; 2^6 = 64; 2^7 = 128; 2^8 = 256; 2^9 = 512 ; 2^10 = 1024; 2^11 = 2048; ...
- You will have to use the American punctuation and not the German punctuation
(for example one thousand three hundred plus one half would be in
american punctuation : 1,300 + (1/2) = 1,300.5
german punctuation : 1.300 + (1/2) = 1.300,5 )
- The SMD format has two subformats or two subfiles for that matter (both share the same file extension: *.SMD)
- The reference SMD file:
it stores all bone names and how they are related to each another (parent/child),
the base bone positions (and rotation) as well as the UV coordinates for the texture
- The animation (also known as sequence) SMD file:
saves all bone names and how they are related to each another (same as reference SMD file),
and the positions/rotations for all bones for each frame
- You can open SMD files with any program that can display TXT files normally (Notepad for instance)
- 0.000000 equals 0! The compiler will add the missing numbers if you just write a single number
- coordinates.jpg shows the coordinate cross as it is being used in Milkshape3D (the thick strokes representing the axis as they are shown in Milkshape3D);
normal Half-Life player models are facing in the -Z direction!
Now, I am going to discuss the reference SMD file. back to the top
Following a sample reference file from a simple face that consists of:
- six vertices that were the base for two triangles
- a total of 6 bones
- and a basic texture (32x32)
Here is the reference SMD file:
version 1
nodes
0 "bottom" -1
1 "middle" 0
2 "left" 1
3 "right" 1
4 "top" 1
5 "joint6" -1
6 "joint7" 4
7 "joint8" 4
end
skeleton
time 0
0 0.000000 -0.200343 -19.553535 -0.009933 0.000000 1.642886
1 0.000000 0.000000 19.563671 0.000000 0.000000 0.000000
2 0.697414 9.573335 -0.172863 0.000000 0.000000 0.000000
3 -0.749097 -10.368604 -0.503016 0.000000 0.000000 0.000000
4 -0.000009 -0.097472 9.799498 0.000000 0.000000 0.000000
5 0.000000 -6.520811 20.845263 1.570796 0.000000 0.000000
6 0.586276 8.016752 10.282016 0.000000 0.000000 0.000000
7 -0.854270 -11.923694 9.417231 0.000000 0.000000 0.000000
end
triangles
face-two_tris01.bmp
1 -8.2500 8.2500 0.0000 0.2689 -0.9248 -0.2689 0.0000 0.0000
1 11.7500 8.2500 20.0000 0.2689 -0.9248 -0.2689 1.0000 1.0000
1 -8.2500 8.2500 20.0000 0.0000 -1.0000 0.0000 0.0000 1.0000
face-two_tris01.bmp
1 -8.2500 8.2500 0.0000 0.2689 -0.9248 -0.2689 0.0000 0.0000
0 11.7500 15.2500 10.0000 0.4975 -0.7107 -0.4975 1.0000 0.5000
1 11.7500 8.2500 20.0000 0.2689 -0.9248 -0.2689 1.0000 1.0000
end
Take a look at this picture for a colored version of this.
I will quote each section at the beginning of its discussion, so do not worry about the blurry image.
The first line (i.e. Version 1) will be omitted in my discussion because I do not know what it is good for.
Maybe there is a second SMD file format we all do not know about, yet?
Furthermore, note that each section (nodes, skeleton, triangles) has its own end command!
Starting with the red square:
nodes
0 "bottom" -1
1 "middle" 0
2 "left" 1
3 "right" 1
4 "top" 1
5 "joint6" -1
6 "joint7" 4
7 "joint8" 4
end
Here are all bones listed that are in your model, their names and how they are related to another.
The general layout is
nodes
a b c
end
where:
a) is the Number of the bone (starting with 0), this is the chronology of the bones.
b) is the name of the bone in quotation marks
c) is the parental bone; value is from a) !; value of -1 is a starting bone.
In this example joint6 is such a starting bone, but has no child bones.
Furthermore, "bottom" is a starting bone and is the parent bone for "middle". "middle" is the parent bone of 2,3, and 4.
4 is the parent bone of 6 and 7.
Continuing with the green part.
skeleton
time 0
0 0.000000 -0.200343 -19.553535 -0.009933 0.000000 1.642886
1 0.000000 0.000000 19.563671 0.000000 0.000000 0.000000
2 0.697414 9.573335 -0.172863 0.000000 0.000000 0.000000
3 -0.749097 -10.368604 -0.503016 0.000000 0.000000 0.000000
4 -0.000009 -0.097472 9.799498 0.000000 0.000000 0.000000
5 0.000000 -6.520811 20.845263 1.570796 0.000000 0.000000
6 0.586276 8.016752 10.282016 0.000000 0.000000 0.000000
7 -0.854270 -11.923694 9.417231 0.000000 0.000000 0.000000
end
In this section are all bones listed with their attributes (position, rotation) for the baseframe.
Baseframe is how the bones are arranged after you have build your model but did not started to animate it.
The general layout of the skeleton section is:
skeleton
time 0
a b c d e f g
end
Do you know that:
a) is the same value as you have it in nodes-section: a
b) is the position in the X plane
c) Z
d) Y
See coordinates.jpg for more information about negative and positiv values of X,Z,Y
Furthermore, these values are absolut for "-1" parent bones but they are relative for child bones to the parent bone.
e) is the rotation in the X plane
f) Z
g) Y
See rotation-X-plane.jpg, rotation-Z-plane.jpg, rotation-Y-plane.jpg for how the bones will rotate in their corresponding planes.
Note that the rotation is entered as a muliple of Pi (3.1415926....). 2·Pi = 360° is a full turnaround, 1·Pi = 180°, (1/2)·Pi = 90°.
I think you got the impression.
Concluding the blue section.
triangles
face-two_tris01.bmp
1 -8.2500 8.2500 0.0000 0.2689 -0.9248 -0.2689 0.0000 0.0000
1 11.7500 8.2500 20.0000 0.2689 -0.9248 -0.2689 1.0000 1.0000
1 -8.2500 8.2500 20.0000 0.0000 -1.0000 0.0000 0.0000 1.0000
face-two_tris01.bmp
1 -8.2500 8.2500 0.0000 0.2689 -0.9248 -0.2689 0.0000 0.0000
0 11.7500 15.2500 10.0000 0.4975 -0.7107 -0.4975 1.0000 0.5000
1 11.7500 8.2500 20.0000 0.2689 -0.9248 -0.2689 1.0000 1.0000
end
This section stores the information which vertices are bound to which bones, the position of the vertices, and the UV coordinates of the vertices.
The general layout looks like this:
triangles
a
b c d e f g h i j
end
a) is the name of the texture in BMP format (including the file extension *.BMP)
b) is the number of the bone the vertex belongs to. This value is the same as in the nodes-section: a)
c) is the position in the X plane
d) Z
e) Y
Three vertices are forming one face. The order the vertices are listed the way the face is beeing build (clockwise or counter-clockwise).
f) this one influences the behaviour how the model will be drawn (could not find out more).
g) this figure should be changed if you want to highlight certain areas of your model, because it has impact on how fast the model will be drawn black depending on the angle you look at it.
- The value 1 is the normal behaviour. Looking with a 90° angle at the face is the most brightest.
- The more negative the value is the darker it will be drawn.
- The more positive the value is the brighter it will be drawn (even at small angles to the face). Furthermore, the face will fade to black later then normal.
h) This one influences the behaviour how the model will be drawn (could not find out more).
i) This is the U coordinate of the texture
j) This is the V coordinate of the texture
Please note that the value can only be between 0 and 1 (including them) no matter how big your texture is.
U is the horizontal axis. V is the vertical axis.
The upper left corner has a value of 0/0
The lower left corner has a value of 0/1
The lower right corner has a value of 1/0
The upper right corner has a value of 1/1
That is all for now from me about the reference SMD file format.
If you find out what the triangles-section:f) and h) do feel free to post it :D
Now starting with the discussion of the animation (sequence) SMD file. back to the top
For simplicity sake I made an animation of two frames as you can see in the sequence SMD file:
version 1
nodes
0 "bottom" -1
1 "middle" 0
2 "left" 1
3 "right" 1
4 "top" 1
5 "joint6" -1
6 "joint7" 4
7 "joint8" 4
end
skeleton
time 0
0 0.000000 -0.200343 -19.553535 -0.009934 0.000000 1.642886
1 0.000000 0.000000 19.563671 0.000000 0.000000 0.000000
2 0.697414 9.573335 -0.172863 0.000000 0.000000 0.000000
3 -0.749097 -10.368604 -0.503016 0.000000 0.000000 0.000000
4 -0.000009 -0.097472 9.799498 0.000000 0.000000 0.000000
5 0.000000 -6.520811 20.845263 1.570796 0.000000 0.000000
6 0.586276 8.016752 10.282016 0.000000 0.000000 0.000000
7 -0.854270 -11.923694 9.417231 0.000000 0.000000 0.000000
time 1
0 0.000000 -0.200343 -19.553535 -0.009934 0.000000 1.642886
1 0.000000 0.000000 19.563671 0.000000 0.000000 0.000000
2 0.697414 9.573335 -0.172863 0.000000 0.000000 0.000000
3 -0.749097 -10.368604 -0.503016 0.000000 0.000000 0.000000
4 -0.000009 -0.097472 9.799498 0.000000 0.000000 0.000000
5 0.000000 -6.520811 20.845263 1.570796 0.000000 0.000000
6 0.586276 8.016752 10.282016 0.000000 0.000000 0.000000
7 -0.854270 -11.923694 9.417231 0.000000 0.000000 0.000000
end
Again I have made a colored version, thus more structured version of this.
The yellow part is exactly the same, as you will find it in the corresponding reference SMD file.
So, I will skip this one, if you want more information about this section refer to the reference SMD file discussion, please.
Next one is the magenta colored part, which is the important part for the animation.
skeleton
time 0
0 0.000000 -0.200343 -19.553535 -0.009934 0.000000 1.642886
1 0.000000 0.000000 19.563671 0.000000 0.000000 0.000000
2 0.697414 9.573335 -0.172863 0.000000 0.000000 0.000000
3 -0.749097 -10.368604 -0.503016 0.000000 0.000000 0.000000
4 -0.000009 -0.097472 9.799498 0.000000 0.000000 0.000000
5 0.000000 -6.520811 20.845263 1.570796 0.000000 0.000000
6 0.586276 8.016752 10.282016 0.000000 0.000000 0.000000
7 -0.854270 -11.923694 9.417231 0.000000 0.000000 0.000000
time 1
0 0.000000 -0.200343 -19.553535 -0.009934 0.000000 1.642886
1 0.000000 0.000000 19.563671 0.000000 0.000000 0.000000
2 0.697414 9.573335 -0.172863 0.000000 0.000000 0.000000
3 -0.749097 -10.368604 -0.503016 0.000000 0.000000 0.000000
4 -0.000009 -0.097472 9.799498 0.000000 0.000000 0.000000
5 0.000000 -6.520811 20.845263 1.570796 0.000000 0.000000
6 0.586276 8.016752 10.282016 0.000000 0.000000 0.000000
7 -0.854270 -11.923694 9.417231 0.000000 0.000000 0.000000
end
The general layout of this part is:
skeleton
a
b c d e f g h
end
Where the letters stand for:
a) The corresponding frame (it starts with "time 0" so to get the frame in MS3D you have to add +1).
Furthermore, the "time 0" frame replaces the "time 0" frame that is given from the reference SMD file.
If you do not have the "time 0" frame the sequence file will start the animation with the base bone position from the reference SMD file!
b) This is the exact same value as in the reference file nodes-section: a)
c) This is the position of the bone in the X plane
d) Z
e) Y
See coordinates.jpg for more information about negative and positive values of X,Z,Y.
Furthermore, these values are absolut for "-1" parent bones but they are relative for child bones to the parent bone.
f) is the rotation in the X plane
g) Z
h) Y
See rotation-X-plane.jpg, rotation-Z-plane.jpg, rotation-Y-plane.jpg for how the bones will rotate in their corresponding planes.
Note that the rotation is entered as a multiple of Pi (3.1415926....). 2·Pi = 360° is a full turnaround, 1·Pi = 180°, (1/2)·Pi = 90°.
This concludes my little discussion about the SMD file format. I hope you enjoyed the read.
If you have any suggestions or found mistakes fell free to post it!
regards,
Sobek
Thanks to Rat for proof reading this tutorial.