Skip to content

Physics Handle: Grab / Set Target / Release

At a glance

Lives on: a Physics Handle Component that you add to an Actor - Grabs: one Primitive Component physics body (optionally a named skeletal body) - Returns: Grab, Set Target, and Release return no success value; Get Grabbed Component returns Primitive Component or None - Can fail quietly? yes; confirm the grabbed reference instead of trusting the exec wire - Official docs: Physics Components, Grab Component at Location, and UPhysicsHandleComponent

A Physics Handle lets one Actor pull a simulated body toward a moving target without turning that body into an ordinary attached child. It is the usual first-project tool for a gravity gun, physics pickup, or drag interaction.

The one-minute version

  • Add one Physics Handle Component to the Character, Pawn, Controller-owned helper, or other Actor that owns the carry interaction. The handle owns the temporary constraint; the grabbed crate does not.
  • Trace for a target and pass the trace's Hit Component, not merely its Hit Actor. The component must own a usable, simulating physics body.
  • Grab Component at Location constrains position but lets the body rotate around the grabbed point. Grab Component at Location with Rotation also drives an orientation.
  • The grab location, target location, and target rotation are world-space values. A camera or carry anchor usually recomputes the target every frame while holding.
  • Get Grabbed Component returns the actual Primitive Component being held, or None when the handle holds nothing. For a new request, compare it with the requested component; use it afterward as the ongoing validity check.
  • Set Target Location moves the invisible handle target; it does not teleport the body. Stiffness, damping, interpolation, mass, collision, and constraints decide how closely the body follows.
  • Release Component ends the handle constraint. It does not disable physics, zero velocity, attach the object, restore collision, or move it to a safe drop point.
  • In multiplayer, run authoritative grab/target/release behavior on the server for shared physics objects. The handle's local constraint state is not a replicated inventory system.

What a Physics Handle actually owns

The handle is an Actor Component that manages a temporary physics constraint between an internal moving target and one body:

BP_PlayerCharacter
|-- Camera / carry anchor
`-- Physics Handle Component
    `-- temporary driven constraint ------> Crate Static Mesh body

Set Target Location each update
    moves the internal target
    physics pulls the crate toward it

The grabbed object stays a simulated rigid body. That is why it can swing, collide with a doorway, lag behind a fast camera turn, or push back on other bodies. If the design needs exact transform parenting with no physical lag, attachment is a better model.

Conceptually, the lifecycle is:

pseudocode of the engine behavior - not engine source

Grab(Handle, PrimitiveComponent, BoneName, WorldPoint, constrainRotation):
    find the requested physics body on PrimitiveComponent
    if no usable body can be constrained:
        do not create the requested constraint; return no failure result
    create/configure the handle constraint at WorldPoint
    remember PrimitiveComponent and BoneName

SetTarget(Handle, WorldLocation, optional WorldRotation):
    update the constraint's kinematic target
    the physics solver drives the grabbed body toward it over time

Release(Handle):
    end the temporary constraint
    clear the remembered grabbed body
    leave the body's ordinary physics state to continue

The target is not a scene component you can attach to or see in the Components panel. It is state internal to the Physics Handle Component.

The complete Blueprint carry loop

A stable carry interaction has three distinct phases: acquire once, update while held, and release once.

1. Acquire the exact component/body

Grab input Started
-> require Carry state is Idle and Get Grabbed Component is None
-> Line Trace by Channel from the owning player's view
-> Branch(Return Value)
-> Break Hit Result
-> Hit Component
-> Is Valid
-> Is Simulating Physics(Hit Bone Name)
-> validate distance, allowed class/tag/interface, and optional mass limit
-> Grab Component at Location
     Component     = Hit Component
     In Bone Name  = Hit Bone Name (or None for a simple Static Mesh body)
     Grab Location = Impact Point or a designed body point
-> Get Grabbed Component
-> Equal (Object) Hit Component
   true: store the requested component and enter Holding state
   false: reject/diagnose the grab

Use the hit component because an Actor can have several primitives: a root collision shape, a visible mesh, trigger volumes, and child parts. Passing the Actor's root just because it is easy can constrain the wrong body or no body. Requiring an empty handle before acquisition also prevents an older valid grab from being mistaken for success when a new void-returning Grab call fails.

The acquisition trace and the physics constraint have different collision needs. Query and Physics lets a body appear in traces and participate in rigid-body simulation. Physics Only can simulate but cannot be found by an ordinary query trace; Query Only can be traced but cannot supply a simulated constraint body.

2. Update the carry target while held

Event Tick (only while Holding)
-> Get Grabbed Component
-> Is Valid
   false: Release Component, clear Holding state
   true:
       CarryTarget = ViewLocation + ViewForward * HoldDistance
       Set Target Location(CarryTarget)

For a rotation-constrained grab:

Set Target Location and Rotation
    Location = CarryTarget
    Rotation = designed held orientation

Update from one clear owner. Calling Set Target from the Character Tick, a weapon Tick, and a UI interaction manager at once creates a tug-of-war in your own gameplay code.

The graph does not have to perform expensive target selection every frame. Trace once on grab, keep the grabbed component reference, then update only the carry target until release or invalidation.

3. Release and restore owned policy

Grab input Completed / cancel / death / distance break
-> Release Component
-> clear Holding state and stored gameplay reference
-> restore any collision response changed for carrying
-> optionally apply an intentional throw impulse

If the object still overlaps the holder, restoring Block Pawn immediately can cause a violent separation. Either choose a collision setup that is safe throughout the hold or wait until the body is clear before restoring that response. The handle does not own that policy.

Location-only versus rotation-constrained grabs

Grab node Position Rotation Use when
Grab Component at Location Driven toward the target point. Free to pivot/spin around the grabbed point. Loose crates, dangling props, objects that should react naturally.
Grab Component at Location with Rotation Driven toward the target point. Driven toward the target rotation too. Tools, puzzle pieces, or props that should keep a designed orientation.

With a location-only grab, Set Target Location is the important update. A rotation target does not turn that grab into a rotation-constrained one after the fact; choose the correct grab variant when creating the constraint.

Rotation-constrained does not mean perfectly welded. Angular stiffness, damping, mass/inertia, contacts, solver settings, and frame rate can still produce lag or motion. It means the handle has an angular goal in addition to the position goal.

Bone Name and the grabbed return value

For a one-body Static Mesh Component, use None for Bone Name. For a Skeletal Mesh Component, the name chooses the body represented by a bone in its Physics Asset. The Bone Name from a suitable Hit Result is often the correct value; verify it rather than inventing a display name.

Get Grabbed Component returns the whole Primitive Component reference, not a separate Blueprint object for the selected skeletal body. The handle also tracks the grabbed bone internally. If later gameplay needs body-specific velocity or impulses, keep the body name in your own carry state too.

Declared and runtime type follow the normal Unreal class rule: the output pin is Primitive Component, but the object can really be a Static Mesh Component, Skeletal Mesh Component, or another subclass. Cast only when you need subclass-specific data; common physics functions already live on Primitive Component.

Tuning: mass, stiffness, damping, and interpolation

The handle drives rather than teleports. Its settings describe how that drive approaches the target:

  • Linear Stiffness - how strongly position error is corrected.
  • Linear Damping - how strongly linear oscillation is resisted.
  • Angular Stiffness / Angular Damping - the rotation equivalents for a rotation-constrained grab.
  • Interpolate Target / Interpolation Speed - whether and how quickly the handle's current target catches up to the target transform you set.

More stiffness is not automatically better. An extremely strong drive on a heavy object jammed into collision can jitter, inject energy, or feel unstable. Too little damping can oscillate; too much can feel slow and heavy. Tune with representative masses and collision situations, not an empty test room.

A beginner-friendly design often enforces a maximum grabbable mass and a maximum hold distance. Those are gameplay rules you check before grabbing; the handle does not decide that every physics body is portable.

Collision and target placement

Keeping physics active is the point of a handle, so the carried object can hit the world. It can also:

  • collide with the player capsule and push/jitter against the holder;
  • snag on door frames;
  • lag when the target jumps through a wall;
  • press other simulating bodies; and
  • carry velocity into release.

Common policy choices are:

  • ignore only the holder's Pawn collision channel while carried, then restore it safely;
  • keep world collision so the object cannot pass through walls;
  • clamp or cancel the hold when the object exceeds a break distance;
  • move the target to the last safe point instead of through blocking geometry;
  • use a shorter hold distance for large objects.

Do not switch the grabbed component to No Collision or Query Only without understanding that the handle needs a physics body/constraint representation. If the design wants a collisionless exact held visual, turn off simulation and attach it instead.

When grab or target update fails

The grab and target setters return no success value. Diagnose through Get Grabbed Component, the component's simulation state, and the Output Log.

Common failure shapes:

  1. The Physics Handle reference is None. Calling a function on it is an Accessed None problem; add/store the component on the interaction owner.
  2. The passed Component is None or the wrong primitive. The exec wire continues, but no useful body is constrained.
  3. Simulate Physics is off. A query-only mesh can be hit by the trace yet cannot behave as the intended loose simulated object.
  4. Bone Name does not select a Physics Asset body. The visible skeletal mesh and its simulated body hierarchy are not interchangeable names.
  5. The acquisition trace cannot see the object. Physics Only excludes it from query traces even though it can simulate.
  6. Set Target runs while nothing is grabbed. There is no constrained body to move and no failure result to tell you that.
  7. Release runs while nothing is grabbed. It has no body to change and no status output; your own Carry state should already say the handle is empty.
  8. The grabbed component is destroyed or unregistered. Treat an invalid grabbed reference as an ended carry, release/clear your gameplay state, and do not keep dereferencing a stale component.
  9. The body is constrained, too massive for the tuning, or blocked by collision. A valid grab can still visibly lag or stop short.
  10. A client-only constraint fights server correction. The authoritative physics object snaps away or diverges across machines.

Before grabbing a new object, deliberately release the old one. Do not depend on undocumented replacement behavior to decide what happens to the first constraint.

Throwing and dropped-object velocity

Release ends the handle constraint; it does not promise a zero linear or angular velocity. The solver may have given the body meaningful velocity while it chased the moving target.

Choose the design:

  • Natural drop: release and keep the body's current motion.
  • Consistent toss: release, then apply an explicit impulse.
  • Quiet placement: slow/stop the body intentionally at a valid placement point before release; do not assume release performs that cleanup.

Avoid applying a large throw impulse before release while the handle is still driving the opposite target. End one motion owner before starting the next.

Multiplayer boundary

A Physics Handle Component and its temporary constraint live in the local physics scene. Executing Grab on one client does not tell the server or other clients which object was selected, which body was grabbed, or where the target should be.

For an authoritative shared pickup:

owning client presses Grab
-> Server RPC with candidate Actor plus a stable part/body identifier
-> server retraces or validates distance, permission, body, and ownership
-> server-owned Physics Handle grabs the authoritative body
-> server updates the carry target while held
-> replicated physics/gameplay state presents the result to clients
-> server releases on input, invalidation, death, or range break

Do not send a reliable RPC every rendered frame just to mirror a camera point. Derive a server carry target from authoritative/replicated aim state, or use a deliberately rate-limited input/state design. Replicate a compact state such as HeldBy / CarryState when clients need UI, pose, or cleanup behavior.

Built-in replicated physics is clearest when the grabbed object's simulating mesh is the replicated Actor's root and Replicate Movement is configured. Non-root body motion and arbitrary handle state need explicit design. A local cosmetic physics interaction can remain client-only only when it has no shared gameplay consequence.

See Replication basics, Reliable vs Unreliable RPCs, and Replicate Movement vs replicated variables.

C++ twin

Original example code:

bool ACarryPawn::TryGrab(const FHitResult& Hit)
{
    UPrimitiveComponent* HitComponent = Hit.GetComponent();
    if (!IsValid(PhysicsHandle) || !IsValid(HitComponent) ||
        IsValid(PhysicsHandle->GetGrabbedComponent()) ||
        !HitComponent->IsSimulatingPhysics(Hit.BoneName))
    {
        return false;
    }

    PhysicsHandle->GrabComponentAtLocation(
        HitComponent,
        Hit.BoneName,
        Hit.ImpactPoint);

    return PhysicsHandle->GetGrabbedComponent() == HitComponent;
}

void ACarryPawn::UpdateCarryTarget(const FVector& WorldTarget)
{
    if (IsValid(PhysicsHandle) &&
        IsValid(PhysicsHandle->GetGrabbedComponent()))
    {
        PhysicsHandle->SetTargetLocation(WorldTarget);
    }
}

void ACarryPawn::ReleaseCarry()
{
    if (IsValid(PhysicsHandle))
    {
        PhysicsHandle->ReleaseComponent();
    }
}

What a Physics Handle does not do

It does not:

  • perform the trace or choose an allowed target;
  • turn on Simulate Physics or create a missing body;
  • return a success Boolean from Grab, Set Target, or Release;
  • attach the object to the player or make it an inventory item;
  • guarantee exact position/rotation despite mass and collision;
  • automatically update its target from the camera;
  • disable collision with the holder or prevent wall snagging;
  • impose mass, distance, permission, or ownership rules;
  • zero velocity or restore collision on release;
  • keep a destroyed component valid; or
  • replicate the selected object, constraint, target, or gameplay carry state.

Lookalikes - which one do I want?

Tool Use when Watch out
Physics Handle One owner temporarily carries/drags one simulating body toward a moving target. Soft physical following; update and release lifecycle are yours.
Attach Actor/Component The held object should follow a socket exactly and no longer behave as a loose body. Turn off simulation first for the ordinary held-item pattern.
Physics Constraint Component Two physical bodies need a persistent joint with explicit angular/linear limits. More setup; not a camera-target pickup shortcut.
Set Physics Linear Velocity / Add Impulse A body needs a direct velocity or one-time shove. No ongoing carry relationship.
Inventory data + hidden/destroyed world pickup Carrying means ownership/data, not a live crate colliding in front of the camera. Spawn/equip/drop presentation becomes an inventory responsibility.
Motion Controller attachment/grip system Virtual-reality interaction needs hand poses and controller-specific behavior. Choose physical handle vs exact grip per object.

Rule of thumb: use a Physics Handle only when remaining a simulated object while held is a feature. Use attachment for exact socket following and an inventory abstraction when the world body should stop existing as the carried item.

Going deeper