user: How do I use Creating a new Meta-rig in Blender? Include parameters, examples, warnings and best practices.

assistant: ### Add a new Armature Object

Building your own meta-rig from scratch requires an armature object to work with.
Just add a single bone from the *Add* menu.

### Editing the Armature

Now that there is an armature object to work – with the armature selected – enter armature Edit Mode.
Building a meta-rig from scratch in Edit Mode can be done in two ways:

1. Adding rig samples.
2. Creating bone chains.

#### Adding Samples (Basic)

Adding pre-defined samples in Edit Mode is a good way to start building a meta-rig.
This way you can become familiar with the available building blocks and how they are meant to be used.
To add a rig sample:

1. Go in the armature tab.
2. Scroll down to Rigify panel.
3. Select a sample from the list.
4. Click on the *Add sample* button.
5. Edit the bone positions to match your character.

For the list of available samples, see the [Rig Types](rig_types/index.xhtml) page.

#### Using Rig Types (Advanced)

[image reference removed]

For full control, you can use the Rigify Type panel of bone properties in Pose Mode to assign
any Rigify sub-rig type to any bone, as well as change its options.

For the list of available sub-rig types and their options, see the
[Rig Types](rig_types/index.xhtml) page.

At the top of the panel you can find a field specifying the rig type for the active bone. The drop-down list
can be optionally filtered by the [Feature Set](feature_sets.xhtml) it belongs to.

Below that you can change options relevant to the selected rig type, if it has any.

##### Bone Collection References

Some rig types that generate many control bones have options that reference
[Bone Collections](#bpy-types-bonecollection-rigify-ui-row). These reference lists have a standard UI with
the following features:

- A checkbox controlling whether the reference should be used.
- A button to copy the reference list contents from the active to all selected bones.
- A plus button to add a new reference to the list.
- A list of references, each entry with a field to specify the target collection,
  and a button to remove the entry from the list.

#### Preserved Bone Properties

Certain properties of the metarig bones are often copied to the generated rig control, deform and mechanism bones.

The exact set depends on the sub-rig and the specific generated bone, and the sub-rig may override some properties
even when it preserves others from the same subset, but there are certain common patterns:

Parenting Settings
:   This subset consists of the parent ORG bone, Use Connect, Use Inherit Rotation, Use Local Location, and Inherit
    Scale.

    It is usually copied to deform bones, FK controls, and in other cases where the sub-rig doesn’t have a reason
    to completely override them.

Bendy Bone Settings (Edit Mode)
:   Consist of the segment count, Vertex Mapping Mode, Ease In/Out, Roll In/Out, Curve In/Out and Scale In/Out.

    The segment count is often overridden via a sub-rig option, but other settings are usually copied to deform
    bones as is.

Transformation Settings
:   Consist of the rotation mode, pose mode rotation values, and channel locks.

    These settings are usually copied to FK controls.

Custom Properties
:   Usually copied to one of the controls generated based on the metarig bone (mainly FK). Intra-armature drivers
    that access the property are retargeted to the copied instance.

Custom Widget
:   Usually copied to one of the controls generated based on the metarig bone (mainly FK), and suppresses automatic
    generation of a widget for the bone if specified.

#### Custom Root Bone

If the meta-rig contains a bone called `root`, it is used as the root control bone instead of creating a new one.
This allows changing the rest position of the root bone, assigning a custom widget,
or adding custom properties to the bone.

The custom root bone must have no parent, and use the [basic.raw_copy](rig_types/basic.xhtml#rigify-rigs-basic-raw-copy) sub-rig
type or none.