# DH Metarig Documentation

# Requirements
- [Bone Manager Addon](https://fin.gumroad.com/l/STdb)
- [Darklight Blender Addon](https://github.com/DarklightGames/dlg_blender_addon)
- [PSA Import Addon](https://github.com/DarklightGames/io_scene_psk_psa)

# Bone groups/layers

### DEF - Deformation bones
This is the original character rig exported from the game.

Deformation bones have whacky orientation enforced by the game and generally shouldn't be used for animation. Instead, you'll use controllers, which will drive `DEF` bones via various mechanisms.

When exporting animations into `psa`, this is the only bone group that should be exported.

### BUFF - Buffers
Buffer bones are used for attaching 2 bones together with an offset. These are mainly used for attaching `DEF` bones to the rest of the rig.

### MCH - Mechanical bones
Various under-the-hood bones used for driving the rig.

### CTRL - Controllers
Controller bones is what you'll be using for controlling and animating the rig.

Limbs have 2 sets of controllers for IK and FK. You can switch between them using custom properties.

### CTRL_MASTER - Master controllers

These drive other controllers and let us do quick gestures.

Current master controllers:
- `CTRL_MASTER_FINGERS` - Rotates, spreads, clenches, and directs fingers (by using rotation, scale, and moving the controller respectively).
- `CTRL_MASTER_EYE` - Controls both eyes (scale to open/close eyes).

### ATTACH - Attachment points

Used for attaching things to the rig (weapons, cameras, etc.)

# Custom properties

### WEAPON_RHAND
`Parent` - Changes parent using rig's built-in dynamic paranting. Read *Dynamic Parenting* below for more details.

### CTRL_IK_HAND and CTRL_IK_FOOT
`IK/FK` - Switches between IK and FK on the limb (0 - IK, 1 - FK)
`Snap IK to FK` - Makes IK bones follow FK. This is useful for IK/FK snapping and animation import.
`Parent` - Changes parent using rig's built-in dynamic paranting. Read *Dynamic Parenting* below for more details.

### PROPERTIES
`IK/FK` - Overrides `IK/FK` properties on all the limbs. Has no effect when set to `-1`.
`Snap IK to FK` - Overrides this property on all limbs. Has no effect when set to `-1`.
`Weapon Offset` - Rotates the weapon by 90 degrees. This is useful for fixing attachment rotation in some cases.
`Weapon Slot` - Moves weapon attachment between "in the hands" and "on the back" position
`_autoprop` - Defines which properties should be automated during export. No need to edit this.

### PROPERTIES_CONTROL
Custom properties on this bone allow disabling some controllers and letting `DEF` bones move on their own.

The option is there just in case. Normally, this is not something that you'd need to do.

### CTRL_MASTER_EYES
`Enable Eye Constraints` - Toggle the automated control over eyes and eyelids.
`Focus Eyes` - Focus eyes on the center of the controlled.

### CTRL_EYE
`Eyelid Control` - *Forgot what this do*

# Dynamic Parenting

For switching parents, `Child Of` constrains can be used but they can be finicky. The rig provides a rudimentary parent switching feature that lets you switch parents by changing `Parent` property on some of the controllers (hands, weapon, and ammo).

Parent values:
0 - Root bone
1 - CTRL_HIPS
2 - CTRL_TORSO
2 - CTRL_SPINE
4 - CTRL_WEAPON_RHAND
5 - CTRL_WEAPON_AMMO
6 - CTRL_WEAPON_REST (bipod)
7 - CTRL_WEAPON_BOLT

For example, if you want to parent right hand IK controller to the weapon:
1. Select `CTRL_IK_HAND_R`.
2. Go to `Custom properties`.
3. Set the `Parent` property to 4.

If you're planning on using `Child Of` constraints instead, make sure to switch `Parent` values to `0`.

# Versioning

**FOR SEAFILE USERS: Introcuding changes to the metarig can break animations in the files it's linked to. Do not modify the existing versions, make a new one instead!**

For new projects, use the latest version of the rig. Older versions are kept for compatibility.

# Preparation
This part will walk you through setting up a new blend file.
1. Create new blend file
2. Link the rig.
`File -> Link... -> Character.blend -> COLLECTIONS -> CHAR`
3. Select the linked collection, press F3 and type `Make library override`.
4. Link the weapon as in steps 2 and 3.
5. Go to weapon's object constraints and add `Copy Tranform` constraint pointing to `ATTACH_WEAPON_HERE` bone
*If weapon is attached sideways, try switching `Weapon Offset` property on the `PROPERTIES` bone.*
5. Optional: Attach magazine bone on the weapon to the `ATTACH_AMMO_HERE` using a `Copy Constraint`.
*If you're going to use rig's parenting system, this will allow you to parent hands to the ammo controller.*
7. Optional: Attach camera to the `ATTACH_CAMERA_HERE` using `Copy Constraint`.
*This will let you control the camera without switching out of the pose mode. Handy for making pose library thumbnails.*

At this point, you should be able to start animating. To edit existing animations, they need to be imported and baked onto the rig.

# Animation Import and Baking
Our character animations are stored in `DHCharactersGER_anm.ukx` package. To extract them, use `umodel` tool (provided in DH repository).

For this part you'll need the Darklight Blender Addon installed.

### Step 1. Import animations from the .psa file
1. Select the `import_ao` armature.
2. Go to armature data properties.
3. Find the PSA Import section.
4. Select the psa file containing animations.
5. Select desired animations from the list.
6. Hit Import.

### Step 2. Set retarget bones and select source rig
This needs to be done only once.
1. Select the `metarig_ao` armature.
2. Go to pose mode.
3. Select all bones in `RETARGET` bone layer (make sure nothing else is selected).
4. Go to armature data properties.
5. Find the Darklight Animation Baker tab.
6. Press `Add` under the `Target Bones` section.
7. Above, set `import_ao` as `Source`.

### Step 3. Check parenting
The animations will be baked with the current child-parent relations in mind.

For example, for most weapon animations, you might want to have hands parented to the weapon. This should be done before baking.

### Step 4. Bake the anims

1. Select the desired animations in the animation baker.
2. Hit Bake.

This will bake the animations onto the target bones you've selected in step 2, including both IK and FK bones.