View source for Skeleton

{{wip}}
<div style="float:right;padding:0 1em;background:#FFF;">__TOC__</div>
A model's [[Skeleton]] is sometimes called the model's ''Rig'' or ''Bonetree''. Every model in Source must have a Skeleton, even if it is just a single, invisible "bone". A Model's Skeleton is the reference framework for all of the model's [[vertex geometry]]<!-- 3D coordinates, normals, etc -->, and it is the Skeleton's "rootbone" that locates the model's geometry to the [[Model Entity]]'s position and orientation in the World.

A [[Model]]'s Rendered '''[[Skin]]''' is ''[[UV|projected]]'' over the '''[[Mesh]]''' which ''[[enveloped|envelopes]]'' the '''[[Skeleton]]'''.

Every Skeleton must have:
* a rootbone.

[[#Vertex_geometry|shortcut]]

== Skeleton Types ==
By far ''the most important'' distinction between types of Skeleton is whether they are [[Rigid]] or [[NotRigid]].
=== [[Rigid]] Skeleton===
Most models in source have [[Rigid Skeleton]]s, which means they may change position and orientation, but they may not "bend" in any way and have ''no moving parts''. Happily, a Rigid Skeleton is so simple that most SMD compilers will include one by default, so the modeller doesn't have to do anything about it. 

=== [[NotRigid]] Skeleton===
only when the Skeleton has more than one bone can it have a joint to articulate. ...

* prop_ragdoll : passive/physics ... [[$collisionjoints]]
* prop_dynamic : active/animated ... see [[skeletal animation]]
** machine model (wheeled vehicle ?)
** character model (rigid npc: [[npc_rollermine]],...)
** viewmodel

== Movement hierarchy ==
By default, each object inherits its [[Origin]] and [[Angles]] (position and orientation) from its parent. <!--When constrained, an object cannot move freely in relation to it's parent's position, but it can rotate about its own origin.--> An object's geometry may include an attachment point, offset from the object's origin. For the sake of brevity, we will say that the child's origin inherits its position and orientation from it's parent's attachment point. If each object's attachment is offset from its origin, 

Each object's Origin is its center of rotation and its position relative to the World Origin.

* WorldOrigin [worldspawn]
** (Vehicle) WorldPosition : all entities' position and orientation are relative to WorldOrigin.
*** (Seat) Parent Entity Attachment point is offset from its WorldPosition
**** (NPC) Child Entity Model offset [$origin] 
***** (Pelvis) Skeleton Root_bone_end offset
****** (Chest) Joint_bone1_end offset
******* (Torch) Attachment point offset
******** (Torchbeam) Sprite
******* (Arm) Joint_bone2_end offset
******** (Sleeve) Mesh vertex offset
******** (Muscle) Physbox vertex offset
******** (Hand) Attachment point offset
********* (Shotgun) Sub-model Root_bone_end offset
********** (Muzzleflash) Sprite


* Entity : the entity's position and orientation in the World are "inherited" by the 
** Model Origin : is the reference point for ... offset with [[$origin]] ...?
*** [[rootbone]] : is any bone "parented" (directly) to the Origin. Usually only one root bone per model... offset with [[$root]]
**** [[bone_joint]] : where this bone connects to its [[parentbone]]
**** [[bone_name]] (see also [[SMD#nodes]])
**** [[bone_attach]] : Has position and orientation properties, = the "origin" for this bone's ''children'' :
***** '''mesh'' : Render model and Collision model vertices are [[enveloped]] to one or ([[weightmap]]ped to) more than one bone.
***** '''physbox'' : Collision model vertices are [[enveloped]] to one bone. 
***** '''sub-model''' : Detachable sub-models (eg w_weapons) are [[attachment|attached]] to one bone_attach. {{todo|would it be better to say each collision convex is ''attached'' to skeleton, rather than ''enveloped'' to it ? ie enveloping implies weightmapping ?}}
***** [[childbone]] : the next named bone in the skeleton hierarchy

*nb sub-models include "rigged" weapons (w_weapon) and [[movement hierarchy]] children ...
* LOD skeleton : [[$lod|bonetreecollapse]], [[$lod|replacebone]],
* [[$ikchain|IK chains]]

===Joint & bone_names=== 
* Intuitively, we think of each named bone as having two ends. The "head" of the bone is called its [[joint]], and is always the end that connects with its [[parentbone]]. The other end is ''offset from the joint'' and seems to be called the "bone" or "bone-end". Because every joint is (by default) a ball-joint, the bone-end position can be described by the bone's radius (length) and spherical angle from the joint. (In [[SMD#skeleton|code]] it's somewhat different!) The bone-end's orientation may also include rotation (about it's long axis).
* [[Envelope]] or [[attachment]] offsets (coordinates) refer to the bone-end coordinates rather than the bone-joint. 
* Joints are referred to by the joint's bone_name; eg ankle = foot_bone, knee = shin_bone, etc. Sometimes bones are named after the joint, eg foot = ankle_bone, shin = knee_bone. However this can cause confusion: something [[attachment|attached]] to the knee_bone will be offset from the ankle joint rather than the knee joint.

A skeleton is comprised of "chains" of bones, joints, effectors, and a root. Some good things to know:
* '''[[Root]]:''' Where your skeleton starts. Moving the root moves the skeleton as one unit.
* '''[[Joint]]:''' Joins two bones, and is where bending and [[$ikchain|IK]] occur.
* '''[[Bone]]:''' This is the principle object in the skeleton and is what the mesh will be attached to.
* '''[[Effector]]:''' These move a bone system around. The end point of a bone chain.

== Root ==
Root or rootbone is a special kind of bone. It is parented to the EntityOrigin, and therefore aligns all of the skelton's geometry to the Entity's World position and orientation. 

A "default" skeleton has nothing but a rootbone, with zero length, all vertices enveloped to it are aligned to the Origin.
 // eg: a "default" [[SMD]] skeleton :
 version 1
 nodes
   0 "root_bone" -1
 end
 skeleton
 time 0
   0 0.000000 0.000000 0.000000 0.000000 0.000000 0.000000   
 end
* To offset part or all of the model from the Entity's position on the map, see [[$origin]] and [[$root]].

==Rigging==
* {{todo|clarify:}}[[rigged]], [[rigging]], [[rig]] ... if "rig" = the whole skinned, enveloped, jointed, etc model, ready and waiting for animations to be applied, then "rigged" means animation-ready or complete, and "rigging" is the process of attaching & tweaking the relationships (uvmap, weightmap, jointconstraints, etc) between all the elements. On the other hand, "rigging" might refer specifically to configuring all the bone properties for a given skeleton - jointconstraints, attachments, IKrules, etc - so "rig" = a NotRigid skeleton, and "rigged" still means "animation-ready".

* {{todo|clarify:}}[[deformer]] = a bone, deforms the mesh, so the "[[deformation]]" would be applied to the mesh & skin, ... however if [[deformation]] = a bone movement, either animation or (ragdoll) vphysics applied to the bone, then bone = "deformee" !

* [[$weightlist]] defines the skeleton's [[bone weight]]s, used for "cross-fading" when [[blend animations]] are combined. 
* [[$jointconstrain]]ts are applied to ragdolls and do not affect animation (?).
* [[$ikchain]]s are used by animation sequences as a kind of collision detection.
* [[$attachment]]s are used by sub-models such as weapons. 
** See [[Creating worldmodels from viewmodels|Rigging a weapon model]] and [[Attachments]] for attaching ''detachable'' sub-models to the Skeleton.
** See [[Bodygroup]]s for attaching additional sub-meshes to the Skeleton.
*** See [[Enveloping]] and [[Weightmap]]ping for attaching a deformable [[Mesh]] to the skeleton.
**** See [[Skinning]] and [[UV map]]ping for attaching a [[Skin]] to the [[Mesh]].

== [[Vertex geometry]] ==
{{todo|probably move this section out to its own page ?}}

An object's '''vertex geometry''' (also known as its ''envelope'' or simply ''geometry'') defines the exact shape of the spatial volume enclosed by its surface.  Vertex Geometry Data always includes 3D ''Vertex coordinates'' (XYZ axes) and sometimes ''[[Vertex normal]] vectors'', ''[[UV map]] coordinates'' and ''[[Weight map]] values''.

* Each '''Vertex coordinate''' (X Y Z) is defined as an ''offset'' from a point ''Origin''. The '''Origin''' is used (1) as this object's center of rotation  and (2) to align different objects (it's relative position). Each type of origin represents a local vertex coordinate system within a ''hierarchy''; ultimately they all refer back to the WorldOrigin.
** '''WorldOrigin''' : Often called the ''map origin'', it is the [[worldspawn]] entity's position in the World (0,0,0). All [[World Brush]]es are part of the [[worldspawn]] entity, so their vertex coordinates are relative to the WorldOrigin. 
** '''EntityOrigin''' : A Point Entity's '''WorldPosition''' is its ''geographical'' offset from the '''WorldOrigin'''. Every [[Point entity]] also has an ''autocentric'' or ''geometric'' origin, which is aligned to its ''WorldPosition''. Some [[Brush entities]] also require a ''geometric'' origin. As a brush is always convex, this is easily, automatically calculated. (see [[Template:Kv_origin]])
** '''ModelOrigin''' : [[Studiomodel]]s also have their own reference Origin, which is aligned to the EntityOrigin. (see [[$origin]]). The model's bones are aligned to its ModelOrigin via its Skeleton.
** '''BoneOrigin''' : Studiomodel vertices and [[attachment]] points are [[enveloped]] to one or more [[Bone]]s in the model's [[Skeleton]]. 

<!-- needs work!
* AutoRotation : By default, each object inherits its '''Orientation''' from it's parent-attachment's Normal, ie the object's local horizon is parallel to the line drawn through the parents Origin and Attachment. No objects rotate about the WorldOrigin. (the World's Normal is the direction of gravity) Each object inherits its default orientation from its parent's attachment point. An Entity may redefine its [[Angles]], a Model may redefine its ...?, and each bone is oriented by its joint angles.
-->
* Each '''Vertex Normal''' ([[vector]])... see [[Vertex smoothing]]
* Each '''Vertex Skin''' ([[UV]])... see [[UV map]]
* Each '''Vertex Weight''' ([[Weightmap|scale]]) ... : see [[Weightmap]]

=== Properties of vertex geometry ===
Objects use vertex geometry to define several spatial properties:
* '''Rendered geometry''' (ie skinned vertex geometry) 
* '''Collision geometry''' (bbox, cbox, hbox, or NotSolid ... cbox/physbox can be collision model or hull)
* '''Skeletal geometry''' ... movement hierarchies ... attachment is offset from object's origin & angles.
* '''Profile geometry''' ... non-collision raytrace tests; ie. Shadows & LOS. Usually derived automatically from Render model at runtime, but can use other geometry for greater efficiency. ([[$shadowlod]], etc?)

=== Non-vertex geometry ===
* Some Entity Properties use non-vertex geometry:
** sphere : eg [[light]] - radius = distance from EntityOrigin (note "falloff")
** cone : eg [[light_spot]] - angles = direction, FOV = cone arc, ? = distance from EntityOrigin (note "falloff")
*** NPC [[viewcone]] (FOV & default distance = 2048 units)
** PVS : potentially visible set (visleafs)
** PAS : potentially audible set (visleafs?)

=== Vertex Editors ===
* Brush Vertices : [[Hammer Vertex Tool]]
* Mesh Vertices : ([[SMD#triangles]]), [[model editor]]
* Skin Vertices : ([[SMD#triangles]]), see [[UV map]]
* Hull Vertices : C++ [[NPC_Hull]], [[Player Hull]]
* Hitbox Vertices : QC [[$hbox]]
* Bounding box Vertices : QC [[$bbox]]