Third Person Item Pullback

Export

Third Person Item Pullback keeps an aimed shootable item from clipping through nearby geometry. Use it when the character should leave the aimed pose and stop shooting or reloading while a wall or other obstruction occupies the space in front of the weapon.

Third-person character's rifle intersecting a wall without pullback protection

The ability uses one or more capsule or sphere probes around the character. It starts automatically when a probe overlaps an allowed obstruction and stops automatically after every probe is clear.

Before you begin

Third Person Item Pullback requires the Third Person Controller code and a character with Ultimate Character Locomotion. The relevant held item should use a Shootable Action when its Use input needs to be blocked.

The ability has no Slot ID, Action ID, or Item Category setting. One active pullback row affects every Reload ability and every Use ability that targets a Shootable Action, regardless of slot, action ID, or Item Set group. Use carefully when the character can operate independent primary and secondary equipment close to geometry.

Configure Third Person Item Pullback

  1. Select the character and expand Item Abilities on Ultimate Character Locomotion.
  2. Select the plus button and add Third Person Item Pullback.
  3. Confirm the editor creates an ItemPullbackCollider object and assigns its Collider to the ability’s Colliders array. When the character has Animator Monitor models, the drawer creates one probe for each monitor; otherwise it creates one under the character.
  4. Select each ItemPullbackCollider in the Scene view and place its capsule or sphere over the volume that the aimed weapon must keep clear.
  5. Leave the generated Collider component disabled. The ability reads the shape and performs its own non-allocating overlap query; the probe does not need to participate in normal Rigidbody collision.
  6. Set Collision Layers to the world geometry that should cause pullback. The starting mask excludes Ignore Raycast, TransparentFX, SubCharacter, Overlay, VisualEffect, and Water.
  7. Keep Max Collision Count 5 for a simple probe area. Increase it when the volume can overlap more than five colliders at once.
  8. Enter Play Mode and adjust the probe position, capsule height, and radius until it activates before the visible item reaches a wall without triggering during ordinary open-space movement.

Capsule-shaped ItemPullbackCollider positioned in front of a third-person character

The generated capsule starts at local position (0, 1.5, 0.65) with Radius 0.25 and Height 1. Treat those values as a starting point, not a universal weapon size. Long rifles, short pistols, crouched poses, and non-humanoid models need their own measured volume.

The custom drawer also provides Add Colliders and Remove Colliders controls. Use them when the assigned probe objects were removed or the character’s model setup changed, then recheck the complete Colliders array.

Choose the obstruction volume

Use only capsule or sphere colliders

Third Person Item Pullback supports Capsule Collider and Sphere Collider shapes. Other Collider types log an error and are not initialized for the overlap calculation.

Every assigned probe must have a radius greater than zero. A zero-radius probe causes the collision check to return clear immediately, so an earlier invalid entry can prevent later probes from being evaluated.

The ability calculates each probe in world space using its Transform, rotation, and scale. Moving or scaling the ItemPullbackCollider therefore changes the tested region even though its Collider component stays disabled.

Match Collision Layers to real obstructions

The query uses Collision Layers and ignores trigger colliders. Colliders on the character or its children are also ignored, as are GameObjects with a Projectile component. This keeps the character’s own body, held objects, and projectiles from activating pullback.

Include walls, cover, doors, and other solid level geometry. Exclude pickups, detection triggers, effects, and any helper layer that should not change the weapon pose.

Max Collision Count sizes the reusable results buffer. If more colliders overlap than the buffer can hold, later results are not inspected. Increase the value in crowded modular environments, especially when several ignored child or projectile colliders can occupy the probe alongside a real wall.

Adapt the probe with States

The generated object includes an Item Pullback Collider State Behavior. Its Local Position Offset and Radius Offset both start at zero and can be changed by State presets.

Use those offsets when one probe should move or resize for crouching, a different weapon family, or another character state. The offsets are applied relative to the position and radius recorded when the component awakens. Use separate probe objects when the required shape or placement differs substantially.

How it interacts with item abilities

Aim stays active but yields its output

Third Person Item Pullback does not stop the Aim ability itself. When pullback activates, Aim suppresses its item substate and sends its aim signal as inactive; when the obstruction clears, Aim sends the signal as active again. This allows held aim input to resume without another button press.

Item Pullback has no Item State Index of its own; its starting value remains -1. It does not select a dedicated pullback animation. The visible result comes from removing the aimed output and stopping incompatible Use or Reload states. Add a separate State or custom animation workflow if the design needs a distinct weapon-compressed pose.

Shootable Use is stopped and blocked

When pullback starts, it force-stops active Use abilities whose targeted Item Action is a Shootable Action. While the obstruction remains, it blocks those Shootable Use abilities from starting again.

Use abilities for non-shootable actions are not blocked by this check. A melee or throwable action can continue unless its own modules or another ability prevent it.

Every Reload is stopped and blocked

When pullback starts, it force-stops every active Reload ability. While active, it blocks any Reload row from starting, without checking Slot ID or Action ID. This global rule prevents a reload animation from pushing a shootable item back into the obstruction, but it also affects an independent off-hand reload.

First-person views disable the ability

Third Person Item Pullback listens for perspective changes. It disables itself before a first-person view becomes active and enables itself for third-person views. The probe therefore does not interfere with first-person item positioning or animation.

How it runs

  1. The automatic ability evaluates each active assigned probe using an overlap capsule or overlap sphere query.
  2. It ignores triggers, character-child colliders, projectiles, and layers outside Collision Layers.
  3. The first accepted obstruction allows Item Pullback to start. Active Shootable Use and all active Reload abilities are force-stopped.
  4. Aim remains active but clears its aiming output, so the item returns to its non-aim presentation instead of clipping farther into the obstruction.
  5. While any accepted overlap remains, Item Pullback blocks new Shootable Use and Reload starts.
  6. Its Stop Type Automatic repeatedly checks the probes. After every probe is clear, the ability stops and Aim restores its output when it is still active.

Start Type uses the inherited Automatic default, and the ability has no input name. Do not map a player button; size and layer the probe so collision alone controls the lifecycle.

Verify in Play Mode

  1. Equip a Character Item with a Shootable Action and hold Aim in third person while standing in open space. Confirm Third Person Item Pullback is inactive and the weapon uses its normal aimed pose.
  2. Walk toward a wall slowly. Confirm Third Person Item Pullback (Active) appears before the visible weapon intersects the wall and Aim’s visible output yields.
  3. Hold the Use input while moving into the probe. Confirm the active Shootable Use stops and cannot restart while the wall remains inside the volume.
  4. Begin Reload in open space, then move the probe into the wall. Confirm Reload stops. Try Reload again while obstructed and confirm it cannot start.
  5. Back away from the wall. Confirm Item Pullback stops automatically and held Aim resumes without another press.
  6. Walk through a trigger volume, past the character’s own colliders, and near a projectile. Confirm none of those activate pullback.
  7. Test the left and right edges, crouched height, every equipped weapon length, and each third-person model. Adjust or add probes until the visual clearance is consistent.
  8. Switch to first person near the wall. Confirm Item Pullback disables, then switch back to third person and confirm collision control returns.

Troubleshoot Third Person Item Pullback

  • The ability is disabled immediately: check that Colliders is assigned. A null array disables the ability during initialization.
  • An error says only capsule and sphere colliders are supported: replace every Box, Mesh, or other unsupported entry with a Capsule Collider or Sphere Collider, then rebuild the probe assignment before Play Mode.
  • The probe never detects a wall: confirm its GameObject is active, its radius is greater than zero, the wall’s layer is included in Collision Layers, and the wall uses a non-trigger Collider.
  • Only the first model works: inspect the Colliders array and active model hierarchy. Each Animator Monitor model normally receives its own ItemPullbackCollider, and inactive model probes are skipped.
  • Detection works only from some directions: inspect the probe’s Transform, rotation, scale, capsule height, and center in Scene view. The overlap uses the actual world-space shape rather than the visible weapon mesh.
  • Pullback misses walls in crowded spaces: increase Max Collision Count. A full non-allocating buffer can omit an accepted wall after ignored results occupy the available entries.
  • Pullback activates near harmless objects: remove their layers from Collision Layers. Trigger colliders are already ignored, but solid pickup or effect colliders still count when their layers are included.
  • Aim remains listed as active: this is expected. Item Pullback suppresses Aim’s output rather than stopping the Aim ability, which lets held aim resume when the probe clears.
  • A melee action is still usable: only Use abilities targeting Shootable Action are blocked. Add a separate rule when melee or throwable actions also need obstruction handling.
  • An off-hand reload is blocked by the primary weapon’s wall probe: Reload blocking is global and has no Slot ID filter. Use a customized ability when independent per-slot obstruction behavior is required.
  • No distinct pullback animation plays: Item Pullback supplies Item State Index -1. Its built-in result is the non-aim pose; use a State or custom Animator workflow for a dedicated compressed-weapon pose.
  • The probe physically pushes other objects: leave its Collider component disabled. The ability queries its geometry directly and does not require normal collision participation.
  • Aim explains the aiming state that yields while Item Pullback is active.
  • Use explains Slot ID, Action ID, and Shootable Action selection.
  • Reload explains the reload workflow that Item Pullback stops and blocks.
  • Shootable Action covers the action type checked by the Use restriction.
  • Item Abilities explains concurrency and Animator list order.
  • State System explains presets that can drive Item Pullback Collider offsets.
  • Layer Manager describes the standard layers excluded from the starting collision mask.
  • Third Person Perspective Item covers the visible held item whose clearance the probe protects.

Developer reference

Item Pullback exposes the Colliders array and CollisionLayers mask. Max Collision Count is serialized with a starting value of 5, but has no public property. ItemPullbackCollider exposes LocalPositionOffset and RadiusOffset for State-driven geometry changes.

Configure the Colliders array before Awake. Item Pullback caches the probe Transforms and allocates its hit buffer only during initialization; assigning a different array at runtime does not rebuild those caches.

The ability listens for OnCameraWillChangePerspectives (bool firstPersonPerspective) to enable or disable its third-person-only behavior. Normal OnCharacterItemAbilityActive (ItemAbility, bool) notifications report its start and stop; Aim uses those notifications to clear and restore its aim output.

Item Pullback emits no unique gameplay event. Query the ability’s IsActive state or listen to the standard item-ability lifecycle when another system needs to react to an obstruction.