SKM, skeletal models.

SKM is a skeletal model format designed for QFusion engine integration. A SKM model is composed of two archives, the model.skm and the model.skp. The .skm archive contains the model information and bones references, while the .skp archive contains the frames bones poses.

SKM models can be composed of a maximun of 32 different meshes, with each mesh being able of using a different texture name. When using QFusion, it's also possible to create .skin files, matching Quake 3 skinfile format, for them, so the SKM models are capable of using custom textures on all their meshes. 

The SKM model, or the .skp file if you prefer, can contain up to a maximum of 65536 frames, each frame containing up to a maximum of 256 bone poses, since 256 is the maximum number of bones of SKM models. Another limit is that animation names can't be superior to 64 characters lenght. Maximum vertex count is also 65536, which means a limit of 21845 triangles. Obviously that's a triangle count absollutely not recommended to use.

The .skp files contain frame based skeleton poses, to transform the model meshes by them. This skp files can be used with different .skm files, as long as the different skm models were originally binded (or skinned, depending on your favourite modelling tool) to exactly the same skeleton. This means, a skeleton with the same bones, having the same bone names, of the same size and in the same bind pose.

SKM models actually don't contain any collision information.

SKM, compiling a simple model.

SKM models are compiled from SMD models using the command line program of name skmodel. The next paragraphs explain how a SMD model is converted into any generic (not player model) SKM.

SMD is the ascii model format used by Half Life and Half Life 2 as source to compile their ingame MDL models. There are 2 types of SMD models: the reference SMD and the animation SMD. The reference model contains the model meshes and skeleton information in the bind pose, each other smd model will contain a single animation. A group composed of the reference SMD + as many animation SMDs as wanted is parsed into the skmodel converter, so it compiles a unified SKM (the same process as it's done for HL/HL2 models).

Since SMD models are the official Half Life 2 source model format there are many exporters available in the net. It's important to know if the exporter you are going to use was made for HL or HL2, though. Both HL and HL2 smd exporters will work, but smd exporters created for Half Life (1) only export a single bone influence per vertex, while the exporters for Half Life 2 write several influences, and SKM is capable of making use of those multiple influences. This doesn't only help achieving a smoother animation, but also makes skin binding much easier. For more information about SMDs, and how to export them from each different 3D modelling program, just google for Half Life 2 and SMD. 

Using skmodel:

skmodel is a command line tool. It requires to receive the name of a text file containing the parsing commands. It's run like this:

skmodel model_definition.txt

The model definition text file can contain the following commands:

outputdir <path>				The output path. .\ for the program folder
model <name>				Name of the .skm and .skin files to be generated
export <name>				Name of the .skp file to be generated
scale <value>				Scale up or down the model
origin <value> <value> <value>		Offset the model origin
scene <name.smd>			SMD models. Once for the reference model, and repeated for each animation.
					There are as many 'scene' commands as SMD sources used.

A important factor to take in count when creating SKM models which could be tagged is that skmodel will not save into the SKM model any bone that is not binded to any vertex. So, making unbinded bones to be used like tags will not work right now ( I might change this in the future if we find it's causing us any troubles ).

Note: Since the SMD models don't contain meshes names, skmodel will generate the meshes names by their numbers in the meshes array. In short, meshes names in the skin file will be a number.

SKM, creating player models for QFusion's Skelmod.

Skelmod is a QFusion mod which adds animation blending for SKM player models. Animation blending is made by the game code, and it's, in short, the code selecting into what bones it will use what animation. For this reason, it requires information of what animations to play, and what bones are part of each group inside the skeleton. This information is provided by the animation.cfg.

Skelmod accepts up to 3 animations for the player model, but we are, by now, only using 2, upper and lower, since head animation is always at frame 0. For defining what bone belongs to each group, Skelmod uses bone Keys, this is just a name as any other, and it refers to the first character in the bone name. For example, all the bones playing the torso animation will begin with the letter 'u', and all bones playing the legs animation will begin with the character 'l'. The characters may vary for each different player model, since they are defined in the animation.cfg, by using the command bonekeys.

This is the list of available commands to be used in the animation.cfg:

bonekeys <count> <lowerkey> <upperkey> <headkey>	Sets the number of bone groups to be animated, and the
							character acting as keys for each group bone names.

sex <m or f>						Sets player model sex.

fps <value>						Sets model FPS ratio. Note, ratio is the same for all the animations.

rotationbone <type> <bone name>			Defines that bone as a rotator. There are 2 possible types: upper and head.
							You can set as many bones as you want as rotators of the same type, the
							rotation angle will be divided by all them.

tagmask <bone name> <tag name>			Defines a tag mask for that bone, so, the bone will be used as the tag
							when looking for a tag of name <tag name>. This is done so different
							models, with different skeletons can use the same tag name.

isnumframes						Makes the third value in the animation definition
							to be read as animation frames count, instead of the
							frame number where the animation finishes.

islastframe						The opposite as isnumframes. It's used by default.

offset							Makes the first value in the animation lines have offset in it's first
							value (as Q3 animation configs). By default the offset isn't applied,
							and every animation is defined by it's real frame value in the model.

alljumps						Makes use of the different jump animations to simulate bunny hopping.

And finally, each animation is defined by 3 values in a line, meaning this by default:

<first frame> <last frame> <looping frames>

Note: looping frames don't have to be the same lenght of the animation extension.

This being the list of animations which are defined in Skelmod:

BOTH_DEATH1
BOTH_DEAD1
BOTH_DEATH2
BOTH_DEAD2
BOTH_DEATH3
BOTH_DEAD3

TORSO_GESTURE

TORSO_ATTACK
TORSO_ATTACK2

TORSO_WEAP_DOWN
TORSO_WEAP_UP
	
TORSO_STAND
TORSO_STAND2

LEGS_WALKCR
LEGS_WALK
LEGS_RUN
LEGS_BACK
LEGS_SWIM_FWD

LEGS_JUMP
LEGS_LAND

LEGS_JUMP3	
LEGS_LAND3	

LEGS_IDLE
LEGS_IDLECR

LEGS_TURN (ignored by the game)

LEGS_JUMP2	
LEGS_LAND2	

LEGS_SWIM
LEGS_WALKBACK
LEGS_WALKLEFT
LEGS_WALKRIGHT
LEGS_RUNLEFT
LEGS_RUNRIGHT

TORSO_RUN
TORSO_SWIM

TORSO_DROP_HOLD	
TORSO_DROP

TORSO_PAIN1
TORSO_PAIN2
TORSO_PAIN3