UDN
Search public documentation:

CollisionTechnicalGuide
日本語訳
中国翻译
한국어

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 Home > Static Meshes > Collision Technical Guide
UE3 Home > Physics > Collision Technical Guide
UE3 Home > Environment Artist > Collision Technical Guide

Collision Technical Guide


Overview


As graphical detail has increased, it is important to ensure that collision within the game remains simple. This is because of two reasons; it is much faster to calculate collision against a few polygons and it is a much smoother experience for the player as then the player does not get snagged on a small piece geometry. Collision response is split up into two distinct parts; Unreal Collision and PhysX. This document focuses on Unreal Collision, click here to read more about PhysX. For information on how to create collision data, see the Collision Reference page.

Unrealscript


Unreal collision dates back to Unreal Engine 1, and the majority of collision responses is handled with Unrealscript. Unrealscript is also responsible for setting up collision properties, so that the Unreal Collision engine knows how to simulate these actors.

Actor Properties

There are a number of Actor properties found under the collision section. These properties control how the Unreal Collision engine handles collision responses and physics simulation of these actors.

  • bCollideComplex - During Actor movement, ignore simplified collision hulls on this actor, and collide per polygon. Simplified collision hulls are generated in Unreal Editor or within a 3D content creation package. Colliding per polygon is useful for non zero extent traces so that bullets will colliding accurately. Colliding per polygon is not recommended for Actor movement as it is expensive to do so.
  • BlockRigidBody - Whether Actors using PhysX should collide against this actor.
  • bNoEncroachCheck - An optimization which turns off the encroachment checking when this Actor is moved. Enabling this speeds up the game, but the actor will not be able to touch triggers, push players, enter or exit volumes.
  • bPathColliding - Whether this Actor can block paths during path building in Unreal Editor.
  • CollisionComponent - Reference to the component used for movement of this Actor. If the Actor is using PHYS_Walking, then the axis aligned bounding box of this component will be collided against the level. If the Actor is using PHYS_RigidBody, then the shape or physics asset of this component is used.
  • CollisionType - This is a method of exposing several collision settings to level designers in a simple way. Changing this value in Unreal Editor will set the low level flags such as CollideActors, BlockActors, BlockNonZeroExtent, BlockZeroExtent and BlockRigidBody on the Actor and its CollisionComponent to match the description of Collision Type.
    • COLLIDE_CustomDefault - Programmer set collison. This restores collision to defaults set in the default properties when selected.
    • COLLIDE_NoCollision - Does not collide at all.
    • COLLIDE_BlockAll - Blocks everything.
    • COLLIDE_BlockWeapons - Only blocks zero extent traces, which are usually weapons.
    • COLLIDE_TouchAll - Touches everything, but does not block.
    • COLLIDE_TouchWeapons - Only touches zero extent traces, which are usually weapons.
    • COLLIDE_BlockAllButWeapons - Blocks everything but zero extent traces, which are usually weapons.
    • COLLIDE_TouchAllButWeapons - Touches everything but zero extent traces, which are usually weapons. This does not block.
    • COLLIDE_BlockWeaponsKickable - Only blocks zero extent traces, which are usually weapon. Also enable flags to allow this Actor to be kicked around by the player.

Collision Flags

There are a number of flags that control how Unreal will perform collision with Actors you place in the level. Sometimes a flag appears in both the Actor properties and the Component properties. In this case the Actor one acts as an override.

  • CollideActors - This must be true for the Actor to be considered at all for Unreal collision detection.
  • BlockActors - This indicates if the Actor should block other Actors from moving. A trigger for example would have CollideActors set to true, but BlockActors set to false. This is because the desired effect is for Unreal to detect when the two Actors touch each other, but for the moving Actor to move through it.
  • BlockZeroExtent - A zero extent trace is a line check, commonly used for weapon that simulate bullets. If this true, then the Actor will block zero extent traces used in Unrealscript.
  • BlockNonZeroExtent - A non zero extent trace is an axis aligned bounding box check, which is commonly used for player movement. If this is true, then the Actor will block non zero extent traces used in Unrealscript.

Unrealscript Events

When collisions occurs in Unreal Engine 3, Unrealscript events are called on the Actors involved. These events are designed so that you can override the event within your sub classed Actors. ALERT! Events and functions are no different in Unrealscript.

HitWall

HitWall is called when the Actor has physically colliding into Wall (in the case of BSP, Wall is set to WorldInfo).
  • HitNormal - Normal that the Actor hit the wall with.
  • Wall - Actor that this Actor colliding into.
  • WallComp - Component that this Actor colliding into. In the case of BSP, WallComp is set to None.

Actor.uc
event HitWall(Vector HitNormal, Actor Wall, PrimitiveComponent WallComp)

It is important to note that Pawns may change how this event is called. If bDirectHitWall is set true, then always call pawn's HitWall event directly.

Pawn.uc
var bool bDirectHitWall;

It is important to note that a Pawn's Controller may change how HitWall is called.

NotifyHitWall is called when our pawn has collided with a blocking piece of world geometry, return true to prevent HitWall() notification on the pawn.

  • HitNormal - Normal that the Actor hit the wall with.
  • Wall - Actor that this Actor colliding into.

Controller.uc
event bool NotifyHitWall(vector HitNormal, actor Wall);

NotifyFallingHitWall is called when our pawn has collided with a blocking piece of world geometry while falling, only called if bNotifyFallingHitWall inside Controller is true.

  • HitNormal - Normal that the Actor hit the wall with.
  • Wall - Actor that this Actor colliding into.

Controller.uc
event NotifyFallingHitWall(vector HitNormal, actor Wall);

Landed

Landed is called when the Actor has physically landed onto FloorActor (in the case of BSP, FloorActor is set to WorldInfo).
  • HitNormal - Normal of the landing.
  • FloorActor - Actor that this Actor landed on.

Actor.uc
event Landed(vector HitNormal, Actor FloorActor);

It is important to note that a Pawn's Controller may change how Landed is called.

NotifyLanded is called when our pawn has landed from a fall, return true to prevent Landed() notification on the pawn.

  • HitNormal - Normal of the landing.
  • FloorActor - Actor that this Actor landed on.

Controller.uc
event bool NotifyLanded(vector HitNormal, Actor FloorActor);

PhysicsVolumeChange

This event is triggered when the PhysicsVolume variable is changed.
  • NewVolume - Volume that PhysicsVolume was set to.

Actor.uc
event PhysicsVolumeChange(PhysicsVolume NewVolume);

Touch

Touch is called on both Actor and Other when they are touching each other. Both Actor and Other must be collidable, and either Actor or Other must use non blocking collision.
  • Other - Actor that touched this Actor.
  • OtherComp - Component that touched this Actor.
  • HitLocation - World location where the touch occurred.
  • HitNormal - Normal of the touch that occurred.

Actor.uc
event Touch(Actor Other, PrimitiveComponent OtherComp, vector HitLocation, vector HitNormal);

PostTouch

PostTouch is called on the PendingTouch Actor after physics has completed. A Pending Touch Actor is an actor that is touched during a move event, which wants to add an effect after the movement completes. Both Actors must be collidable, and one of the Actors must use non blocking collision.
  • Other - PendingTouch Actor.

Actor.uc
event PostTouch(Actor Other);

UnTouch

UnTouch is called on Actor that untouches Other. For example, if player's pawn initially touches a trigger both the player's pawn and trigger will receive the Touch event. When the player's pawn moves away from the trigger so that their collisions are no longer touching, the player's pawn will call UnTouch with the Other parameter set as the Trigger. Both Actor and Other must be collidable, and either Actor or Other must use non blocking collision.
  • Other - Untouched actor.

Actor.uc
event UnTouch(Actor Other);

Bump

Bump is called on both Actor and Other when they are bumping into each other. Both Actor and Other must be collidable, and both Actor and Other must use blocking collision.
  • Other - Actor that bumped into this Actor.
  • OtherComp - Component that bumped into this Actor.
  • HitNormal - Normal of the bump that occurred.

Actor.uc
event Bump(Actor Other, PrimitiveComponent OtherComp, Vector HitNormal);

It is important to note that a Pawn's Controller may change how Bump is called.

NotifyBump is called when our pawn has collided with a blocking player, return true to prevent Bump() notification on the pawn.

Controller.uc
event bool NotifyBump(Actor Other, Vector HitNormal);

BaseChange

BaseChange is called when the Actor's Base variable has changed. This also includes when Base is set to None; this happens when the Actor is floating in space. The Base variable is an Actor reference pointing to what the Actor is currently standing on.

Actor.uc
event BaseChange();

CollisionChanged

CollisionChanged is called when any of the Actor's collision properties have been changed.

Actor.uc
event CollisionChanged();

EncroachingOn

EncroachingOn is called when this Actor is encroaching on Other and we couldn't find an appropriate place to push Other to.
  • Other - Actor that this Actor is encroaching on.
  • Return - Return true if you wish to abort the move, or false to allow it to move. ALERT! Do not abort moves of PHYS_RigidBody Actors as that will cause the Unreal location and physics engine location to mismatch.

Actor.uc
event bool EncroachingOn(Actor Other);

EncroachedBy

Actor.uc
event EncroachedBy(Actor Other);

RanInto

RanInto is called for encroaching actors which successfully moved the other Actor out of the way.
  • Other - Actor that was moved out of the way.

Actor.uc
event RanInto(Actor Other);

Performing collision checks

Trace

Perform a trace to detect if the line collides with anything within the world.
  • HitLocation - Where in the world the line collided.
  • HitNormal - Surface normal of where the line collided.
  • TraceEnd - A point in the world where the trace ends.
  • TraceStart - A point in the world where the trace starts.
  • bTraceActors - Whether the trace against actors or not.
  • Extent - If this vector is equal to zero (Vect[0.f, 0.f, 0.f]) then the trace performed will be considered as zero extent. If the vector is not zero, then a non zero extent trace is performed.
  • HitInfo - This struct contains information about the trace results. This may be invalid if the trace did not collide with anything.
    • Material - Material that the trace hit.
    • PhysMaterial - Physical material that the trace hit.
    • Item - Extra information about the thing that the trace hit.
    • LevelIndex - Level index if the trace hit BSP.
    • BoneName - Name of the bone if the trace hit a skeletal mesh component.
    • HitComponent - Component that the trace hit.
  • ExtraTraceFlags - Extra trace flags that provides hints to how the trace should be performed.
    • TRACEFLAG_Bullet - Trace will always ignore simple collision on static meshes and always do per polygon collision detection.
    • TRACEFLAG_PhysicsVolumes - Trace will check for collisions against physics volumes.
    • TRACEFLAG_SkipMovers - Trace will ignore InterpActors.
    • TRACEFLAG_Blocking - If set, then trace will collide against actors that can block the checking actor (the actor where Trace was called from) and all colliding. All colliding includes level geometry, pawns, interpolated actors, any other kind of actor, terrain and volumes.
  • Returned Actor - Trace returns an Actor reference. If the return is None, then the trace did not hit anything. If the trace hit BSP, then the returned Actor is WorldInfo. Otherwise, the trace will return whatever Actor it hit.

Actor.uc
function Actor Trace(out Vector   HitLocation, out Vector HitNormal, Vector TraceEnd, optional Vector TraceStart, optional bool bTraceActors, optional Vector Extent, optional out TraceHitInfo HitInfo, optional int ExtraTraceFlags);

TraceComponent

Perform a trace against InComponent only. Returns true if the trace hit. This is useful when more accuracy is required in determining if an Actor was hit or not.
  • HitLocation - Where in the world the line collided.
  • HitNormal - Surface normal of where the line collided.
  • InComponent - Component to run the trace against.
  • TraceEnd - A point in the world where the trace ends.
  • TraceStart - A point in the world where the trace starts.
  • Extent - If this vector is equal to zero (Vect[0.f, 0.f, 0.f]) then the trace performed will be considered as zero extent. If the vector is not zero, then a non zero extent trace is performed.
  • HitInfo - This struct contains information about the trace results. This may be invalid if the trace did not collide with anything.
    • Material - Material that the trace hit.
    • PhysMaterial - Physical material that the trace hit.
    • Item - Extra information about the thing that the trace hit.
    • LevelIndex - Level index if the trace hit BSP.
    • BoneName - Name of the bone if the trace hit a skeletal mesh component.
    • HitComponent - Component that the trace hit.
  • bComplexCollision - Set true if you wish to use per polygon collision.

Actor.uc
function bool TraceComponent(out Vector HitLocation, out Vector HitNormal, PrimitiveComponent InComponent, Vector TraceEnd, optional Vector TraceStart, optional Vector Extent, optional out TraceHitInfo HitInfo, optional bool bComplexCollision)

FastTrace

Performs a trace within the world, and returns true if it did not collide with anything. This is useful for quickly checking if an Actor has line of sight of another Actor.
  • TraceEnd - A point in the world where the trace ends.
  • TraceStart - A point in the world where the trace starts.
  • BoxExtent - If this vector is equal to zero (Vect[0.f, 0.f, 0.f]) then the trace performed will be considered as zero extent. If the vector is not zero, then a non extent trace is performed.
  • bTraceBullet - Set true if you want the trace to act like a bullet.

Actor.uc
function bool FastTrace(Vector TraceEnd, optional Vector TraceStart, optional Vector BoxExtent, optional bool bTraceBullet);

TraceAllPhysicsAssetInteractions

Performs a trace within the world against a skeletal mesh component's physics asset, and returns all of the hits.
  • SkelMeshComp - Skeletal mesh component to test the trace against.
  • EndTrace - A point in the world where the trace ends.
  • StartTrace - A point in the world where the trace starts.
  • out_Hits - Outputs an array containing information about the trace's results.
    • HitActor - The actor that was hit.
    • HitLocation - World location of the trace hit location.
    • HitNormal - Hit normal of the trace hit.
    • RayDir - Direction of the trace.
    • StartTrace - World location of where the trace started.
    • HitInfo - This struct contains information about the trace results. This may be invalid if the trace did not collide with anything.
      • Material - Material that the trace hit.
      • PhysMaterial - Physical material that the trace hit.
      • Item - Extra information about the thing that the trace hit.
      • LevelIndex - Level index if the trace hit BSP.
      • BoneName - Name of the bone if the trace hit a skeletal mesh component.
      • HitComponent - Component that the trace hit.
  • Extent - If this vector is equal to zero (Vect[0.f, 0.f, 0.f]) then the trace performed will be considered as zero extent. If the vector is not zero, then a non extent trace is performed.
  • Returns true if any hits were detected.

Actor.uc
function bool TraceAllPhysicsAssetInteractions(SkeletalMeshComponent SkelMeshComp, Vector EndTrace, Vector StartTrace, out Array<ImpactInfo> out_Hits, optional Vector Extent);

IsOverlapping

Returns true if this Actor is overlapping A.
  • A - The other actor to test overlapping conditions against.

Actor.uc
function bool IsOverlapping(Actor A);

GetBoundingCylinder

Returns the bounding cylinder radius and height, if possible.
  • CollisionRadius - Collision radius.
  • CollisionHeight - Collision height.

Actor.uc
function GetBoundingCylinder(out float CollisionRadius, out float CollisionHeight) const;

IsBlockedBy

Returns true if this Actor is blocked by Other.
  • Other - The other actor to test if it is blocking this Actor.

Actor.uc
function bool IsBlockedBy(const Actor Other) const;

TouchingActors

An iterator function which returns all of the Actors that are touching this Actor.
  • BaseClass - Class of Actors to return.
  • Actor - Actor that the line collided with.

Actor.uc
iterator function TouchingActors(class<Actor> BaseClass, out Actor Actor);

TraceActors

An iterator function returns all of the Actors, TraceHitInfos between two points in the world. This is useful for performing line checks which can exclude or include certain types of actors, or other conditions.
  • BaseClass - Class of Actors to return.
  • Actor - Actor that the line collided with.
  • HitLoc - Where in the world the line collided.
  • HitNorm - Surface normal of where the line collided.
  • End - A point in the world where the trace ends.
  • Start - A point in the world where the trace starts.
  • Extent - If this vector is equal to zero (Vect[0.f, 0.f, 0.f]) then the trace performed will be considered as zero extent. If the vector is not zero, then a non zero extent trace is performed.
  • HitInfo - This struct contains information about the trace results. This may be invalid if the trace did not collide with anything.
    • Material - Material that the trace hit.
    • PhysMaterial - Physical material that the trace hit.
    • Item - Extra information about the thing that the trace hit.
    • LevelIndex - Level index if the trace hit BSP.
    • BoneName - Name of the bone if the trace hit a skeletal mesh component.
    • HitComponent - Component that the trace hit.
  • ExtraTraceFlags - Extra trace flags that provides hints to how the trace should be calculated.
    • TRACEFLAG_Bullet - Trace is acting like a bullet.

Actor.uc
iterator function TraceActors(class<Actor> BaseClass, out Actor Actor, out Vector HitLoc, out Vector HitNorm, Vector End, optional Vector Start, optional Vector Extent, optional out TraceHitInfo HitInfo, optional int ExtraTraceFlags);

VisibleCollidingActors

An iterator function which returns all colliding (bCollideActors is set true) actors within a certain radius for which a trace from Location (which defaults to caller's Location) to that actor's Location does not hit the world.
  • BaseClass - Class of Actors to return.
  • Actor - Actor that the line collided with.
  • Radius - Radius of the box.
  • Loc - World location where the center of the box or sphere is.
  • bIgnoreHidden - Ignored hidden actors.
  • Extent - If this vector is equal to zero (Vect[0.f, 0.f, 0.f]) then the trace performed will be considered as zero extent. If the vector is not zero, then a non zero extent trace is performed.
  • bTraceActors - Performs a line of sight check to make sure that actors are visible to the caller.
  • InterfaceClass - Exclude actors that do not implement this interface. If this is None, then this is ignored.
  • HitInfo - This struct contains information about the trace results. This may be invalid if the trace did not collide with anything.
    • Material - Material that the trace hit.
    • PhysMaterial - Physical material that the trace hit.
    • Item - Extra information about the thing that the trace hit.
    • LevelIndex - Level index if the trace hit BSP.
    • BoneName - Name of the bone if the trace hit a skeletal mesh component.
    • HitComponent - Component that the trace hit.

Actor.uc
iterator function VisibleCollidingActors(class<Actor> BaseClass, out Actor Actor, float Radius, optional Vector Loc, optional bool bIgnoreHidden, optional Vector Extent, optional bool bTraceActors, optional class<Interface> InterfaceClass, optional out TraceHitInfo HitInfo);

CollidingActors

An iterator function which returns colliding (bCollideActors is set true) actors within a certain radius. bUseOverlapCheck uses a sphere vs. box check instead of checking to see if the center of an object lies within a sphere.
  • BaseClass - Class of Actors to return.
  • Actor - Actor that the line collided with.
  • Radius - Radius of the box, or sphere depending on bUseOverlapCheck.
  • Loc - World location where the center of the box or sphere is.
  • bUseOverlapCheck - Uses a sphere verses a box check instead of checking to see if the center of an object lies within a sphere.
  • InterfaceClass - Exclude actors that do not implement this interface. If this is None, then this is ignored.
  • HitInfo - This struct contains information about the trace results. This may be invalid if the trace did not collide with anything.
    • Material - Material that the trace hit.
    • PhysMaterial - Physical material that the trace hit.
    • Item - Extra information about the thing that the trace hit.
    • LevelIndex - Level index if the trace hit BSP.
    • BoneName - Name of the bone if the trace hit a skeletal mesh component.
    • HitComponent - Component that the trace hit.

Actor.uc
iterator function CollidingActors(class<Actor> BaseClass, out Actor Actor, float Radius, optional Vector Loc, optional bool bUseOverlapCheck, optional class<Interface> InterfaceClass, optional out TraceHitInfo HitInfo);

OverlappingActors

An iterator function which returns colliding (bCollideActors is set true) actors which overlap a Sphere from location Loc and Radius radius.
  • BaseClass - Class of Actors to return.
  • out_Actor - Returned Actor at each iteration.
  • Radius - Radius of sphere for overlapping check.
  • Loc - Center of sphere for overlapping check. (Optional, caller's location is used otherwise).
  • bIgnoreHidden - If true, ignore bHidden actors.

Actor.uc
iterator function OverlappingActors(class<Actor> BaseClass, out Actor out_Actor, float Radius, optional Vector Loc, optional bool bIgnoreHidden);

Collision Types


There are a few collision types that you can use within your game. Majority of methods use closed meshes as collision hulls.

Skeletal mesh collision hulls

Please see PhAT User Guide on how to create collision hulls used by Skeletal Meshes.

Static mesh collision hulls

Static mesh collision hulls are stored as part of a static mesh. Static mesh collision hulls are also instanced in the same way as static meshes, so are more efficient memory wise than blocking volumes.

In the static mesh browser you can change a few properties of how the collision hulls are used:

  • UseSimpleRigidBodyCollision - This is set true by default. If this is true and a collision hull is present, then the collision hull will be turned into a set of convex hulls and used for calculating the collision of physics objects (e.g. vehicles or ragdolls) against this static mesh. If UseSimpleRigidBodyCollision is true, and there is no collision hull, rigid bodies will not collide with this static mesh. If you set UseSimpleRigidBodyCollision to false, then the physics engine will collide per polygon of the static mesh; only use this option if the static mesh polygons are fairly large.
  • UseSimpleBoxCollision - This is set true by default. If this is true, then the collision hull, if present, will be used for non zero extent line checks. This includes things like player movement, but not weapon fire. No per polygon collision will be used if this is true and there is a collision hull. If you set UseSimpleBoxCollision to false, per polygon collision will be used based on the material. There will be no collision if you set UseSimpleBoxCollision to true when you do not have a collision hull.
  • UseSimpleLineCollision - This is set true by default. If this is true, then the collision hull, if present, will be used for zero extent line checks. This includes most weapon fire, lens flare traces, etc. If you set UseSimpleLineCollision to true when you do not have a collision hull or if you set UseSimpleLineCollision to false, then per polygon collision will be used based on the material settings.