# Adding Grips

There are **two types of grips** available in the Reality ModKit:

* **Procedural Grips** – quick to set up, automatically adapt to any shape, but offer limited fine-tuning.
* **Animated Grips** – allow for precise, hand-animated interactions such as weapon grips, triggers, or special poses.

***

## Procedural Grips

**Procedural grips** adapt dynamically to the shape of the object using its collision. They’re ideal for general props or objects where precise finger placement isn’t required.

* Very easy to set up
* Works on any shape
* No fine-tuning or animation control

{% hint style="info" %}
Even without setting up procedural gripping, the physics system may still let you “pick up” items loosely (e.g., wrapping fingers around a gun grip). However, to have the item properly attached to the hand, you must enable procedural gripping. Internally, this uses `AttachComponentToComponent`.
{% endhint %}

### Registering a Procedural Grip

You do **not** need to add a `RealityGripComponent` or set up any special collision volume to register a procedural grip.

To register a procedural grip:

{% stepper %}
{% step %}

### Open the owning blueprint

Open the actor or component blueprint that owns the grip.
{% endstep %}

{% step %}

### Class Defaults

Go to **Class Defaults**.
{% endstep %}

{% step %}

### Locate the Grip section

In the **Details Panel**, locate the **Grip** section.
{% endstep %}

{% step %}

### Add a new procedural grip entry

Next to **Procedural Grip Settings**, click the **Plus (+)** button to add a new procedural grip entry.
{% endstep %}

{% step %}

### Set the Static Mesh

In the newly added grip entry, set the **Static Mesh** you want to be grippable.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}

* The `RegisterGripProcedural` function is **deprecated** and should not be used.
* Procedural grips can only be registered **in the editor**, not at runtime.
  {% endhint %}

***

## Animated Grips

**Animated grips** are used for precise hand interactions — for example, a pistol grip where the **trigger finger** moves independently when firing.

They rely on playing animations on a **special skeletal mesh hand**, allowing exact control over finger poses and transitions through **Blendspaces**.

### Requirements

* You must use the provided skeletal mesh: `SKM_HandUE5`\
  (This is already the default value for the hand field.)
* You need to create an **animation** for the hand.
* You need to create a **Blendspace** that includes the relevant hand animations to allow smooth finger transitions (e.g., pressing the trigger).

### Setting Up an Animated Grip

{% stepper %}
{% step %}

### Add a RealityGripComponent

Add a `RealityGripComponent` to your object.
{% endstep %}

{% step %}

### Preview the hand side

In the **Details Panel**, set the preview to the **left** or **right** hand.
{% endstep %}

{% step %}

### Assign Blendspaces per hand

For each hand, assign the corresponding **Blendspace**.\
For a given grip, left and right hands will likely need different positions — verify and align the hand mesh for both previews.
{% endstep %}

{% step %}

### Create a collision volume

Create a **collision volume** for this grip and set the collision preset to `InteractiveComponent`.\
The grip will only activate when the user’s hand overlaps this volume and they pull the grip trigger on their controller.
{% endstep %}
{% endstepper %}

Each `RealityGripComponent` represents **one grip**. You can add **multiple** animated grips (e.g., main grip, charging handle grip). Register each one with its own collision volume.

### Registering an Animated Grip

To register an animated grip:

{% stepper %}
{% step %}

### Open the owning blueprint

Open the actor or component blueprint that owns the grip.
{% endstep %}

{% step %}

### Class Defaults

Go to **Class Defaults**.
{% endstep %}

{% step %}

### Locate the Grip section

In the **Details Panel**, locate the **Grip** section.
{% endstep %}

{% step %}

### Add an animated grip entry

Next to **Animated Grip Settings**, click the **Plus (+)** button to add a new animated grip entry.
{% endstep %}

{% step %}

### Select Collision Volume

For the new grip entry, select the **Collision Volume** from the dropdown.\
This collision is used **only** to detect overlap and activate the grip.
{% endstep %}

{% step %}

### Add Grip Component Settings

Under **Grip Component Settings**, add a new array item and assign the corresponding **RealityGripComponent**.
{% endstep %}

{% step %}

### Mark main grip (optional)

If this grip represents the primary grip (e.g. a main weapon grip), enable the **Main Grip** checkbox.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}

* The `RegisterGripAnimation` function is **deprecated** and should not be used.
* Animated grips can only be registered **in the editor**, not at runtime.
  {% endhint %}

### Animated Grip Behavior

* When gripping, the **root bone of the hand snaps** to the defined grip location.
* All finger and hand positioning is driven by the **Blendspace**, not physics.
* When the controller releases the grip, the **animated grip deactivates**.

***

## Creating Custom Hand Poses (for Animated Grips)

This section walks through making a **custom hand pose animation** for `SKM_HandUE5` and setting it up with a **Blendspace**.

{% stepper %}
{% step %}

### Duplicate a base hand animation

In `/All/EngineData/Plugins/Reality/Core/Interactable/Grip`, locate the default `A_HandUE5` animation sequence.\
Duplicate it into **your mod folder** (important for packaging; only assets inside your mod folder can be referenced by your mod).
{% endstep %}

{% step %}

### Editor constraints while posing

Open the duplicated hand animation and follow these constraints:

* Do NOT move/rotate/scale: the `root`, the `hand_r`, and any `Metacarpal` bones.
* Only rotate finger bones to pose the hand. Avoid translating or scaling finger bones to maintain realism.
  {% endstep %}

{% step %}

### Preview your object in the hand animation

To pose the hand around your object:

1. Right-click the **Root**, then select `Add Socket`. Right-click the **socket**, then select `Add Preview Asset`.
2. Temporarily move/rotate the socket and (temporarily) the `hand_r` bone so the preview object sits correctly in the hand while posing. Keyframe (click **+Key**) to capture these temporary transforms so the hand and object line up while you pose fingers.
   {% endstep %}

{% step %}

### Pose the fingers

Rotate finger bones as needed to pose the hand. (Reminder: do not use metacarpals.)\
Click **+Key** again to key the finger bone rotations once your pose is set.
{% endstep %}

{% step %}

### Clean up the temporary keys

* Delete the `hand_r` track. Keeping transforms there will cause issues at runtime.
* Remove the preview mesh.
* Delete the temporary socket.

Now you have a clean hand pose animation containing only the finger rotations.
{% endstep %}

{% step %}

### (Optional) Bake the pose

Use **Create Asset → Create Animation → Current Pose** to bake the pose so it contains no keys.
{% endstep %}

{% step %}

### Create a Blendspace & add the pose(s)

* Create a **1D Blendspace** for `SKM_HandUE5`.
* Drag in your pose animation. For a single static pose, the position in the Blendspace doesn’t matter. For grips that need stateful finger behavior, drag in the other animations you want to use in the Blendspace.
* You can also author **2D Blendspaces** if you need a second input dimension.
  {% endstep %}

{% step %}

### Assign the Blendspace to the grip

In your `RealityGripComponent`, assign the Blendspace per-hand (right/left).
{% endstep %}
{% endstepper %}

***

## Grip Settings (Procedural & Animated)

When calling the **Register** nodes, fill the **Grip Settings / Hand Grip Info** struct:

* **Grip Name**: Required string used for later reference. Do not leave empty.
* **Can Rotate With Two Hands**:
  * True: If gripped with two hands, rotation is influenced by both hands.
  * False: Rotation follows the first hand that grabbed.
* **Grip Priority**:
  * When multiple grips are eligible, the one with higher priority is chosen.
  * If priorities are equal and one grip is Animated and the other Procedural, the system prioritizes the Animated grip.
  * If priorities are equal and types equal, the first encountered is chosen.
* **Allow Multiple Hand Grips**:
  * For Procedural grips on long props (e.g., poles), you may want multiple hands to grip the same procedural target.
  * For Animated grips like a main weapon grip, you typically disable this so you don’t get two right hands, or left/right hands clipping into the same slot.
* **Custom Sounds**: Optional Grip and Release sounds can be assigned and will play on events.

***

## Runtime & Performance Notes

* The `RealityGripComponent` used for Animated grips is destroyed after registration. Its data is retained. Do **not** reference the component at runtime.
* Procedural grips do **not** require a `RealityGripComponent` and do **not** require their own collision volume.

***

## Examples

To see how grips are set up on different firearms and interactable objects, search for `RealityFirearm` or `RealityInteractable` in the Content Browser.

If no results appear, open the Content Browser Settings and enable “Show Engine Content” to make these examples visible.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://beyond-sandbox.gitbook.io/realitysdk/documentation/interactable/adding-grips.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.