1. Epic GamesDeveloper
  3. UClusterUnionComponent

UClusterUnionComponent

This does the bulk of the work exposing a physics cluster union to the game thread.

API > API/Runtime > API/Runtime/Engine

This does the bulk of the work exposing a physics cluster union to the game thread. This component needs to be a primitive component primarily because of how physics proxies need to be registered with the solver with an association with a primitive component. This component can be used as part of AClusterUnionActor or on its own as its list of clustered components/actors can be specified dynamically at runtime and/or statically on asset creation.

The cluster union component needs to not only maintain a game thread representation of what's happening on the physics thread but it also needs to make sure this data gets replicated to every client. A general model of how the data flow happens is as follows:

[Server GT Command] -> [Server PT Command] -> [Server Modifies PT Data] -> [Server Sync PT Data back to GT Data].

This enables GT control over what happens to the cluster union BUT ALSO maintains a physics-first approach to the cluster union where a physics event can possibly cause the cluster union to break.

The GT data is replicated from the server to the clients either via the FClusterUnionReplicatedData on the cluster union component or per-child component data is replicated via the UClusterUnionReplicatedProxyComponent. Generally, the same flow is replicated on the client. The only exception is for replicating the X/R/V/W properties on the cluster union particle which does a GT -> PT data sync. There's no particula reason this happens...it just mirrors the single particle physics proxy here.

   
Name UClusterUnionComponent
Type class
Header File /Engine/Source/Runtime/Engine/Classes/PhysicsEngine/ClusterUnionComponent.h
Include Path #include "PhysicsEngine/ClusterUnionComponent.h"

Syntax

UCLASS (MinimalAPI)  
class UClusterUnionComponent : public UPrimitiveComponent

Inheritance Hierarchy

Implements Interfaces

Derived Classes

Constructors

Name Remarks Include Path Unreal Specifiers

UClusterUnionComponent ( const FObjectInitializer& ObjectInitializer
)

   PhysicsEngine/ClusterUnionComponent.h  

Structs

Name Remarks
FMappedBoneData  
FMappedComponentKey Structure that stores an object key and its raw ptr, so it can be accessed without going trough the global uobjects array (so it could be garbage, therefore it has to be used withing the same frame)

Typedefs

Name Type Remarks Include Path
FLocalBonesToTransformMap TSortedMap< int32, FMappedBoneData, TInlineAllocator< 1 > > There are several instances where we have 1 single elements. The inline allocator should help in these cases without a huge impact when we go over. PhysicsEngine/ClusterUnionComponent.h
FSpatialAcceleration Chaos::ISpatialAcceleration< FExternalSpatialAccelerationPayload, Chaos::FReal, 3 >   PhysicsEngine/ClusterUnionComponent.h

Variables

Public

Name Type Remarks Include Path Unreal Specifiers
bEnableDamageFromCollision bool Whether or not collisions against this geometry collection will apply strain which could cause the geometry collection to fracture. PhysicsEngine/ClusterUnionComponent.h
  • EditAnywhere
  • BlueprintReadWrite
  • BlueprintSetter=SetEnableDamageFromCollision
  • Category="Cluster Union"
OnClusterUnionPostSyncBodiesEvent FOnClusterUnionPostSyncBodies   PhysicsEngine/ClusterUnionComponent.h  
OnComponentAddedEvent FOnClusterUnionAddedComponent   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintAssignable
  • Category="Events"
OnComponentAddedNativeEvent FOnClusterUnionAddedComponentNative Native (fast, low overhead) versions PhysicsEngine/ClusterUnionComponent.h  
OnComponentBoundsChangedEvent FOnClusterUnionBoundsChanged   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintAssignable
  • Category="Events"
OnComponentRemovedEvent FOnClusterUnionRemovedComponent   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintAssignable
  • Category="Events"
OnComponentRemovedNativeEvent FOnClusterUnionRemovedComponentNative   PhysicsEngine/ClusterUnionComponent.h  

Protected

Name Type Remarks Include Path Unreal Specifiers
AccelerationStructure TUniquePtr< FSpatialAcceleration > An acceleration structure of all children components managed by the cluster union itself. PhysicsEngine/ClusterUnionComponent.h  
ActorToComponents TMap< TObjectKey< AActor >, FClusteredActorData > Also keep track of which actors we are clustering and their components. PhysicsEngine/ClusterUnionComponent.h  
bHasCachedLocalBounds bool Cached local bounds from the physics particle. PhysicsEngine/ClusterUnionComponent.h  
bPhysicsPredictionEnabled bool If Physics Prediction is enabled. PhysicsEngine/ClusterUnionComponent.h  
CachedLocalBounds FBoxSphereBounds   PhysicsEngine/ClusterUnionComponent.h  
ClusteredComponentsReferences TArray< FComponentReference > These are the statically clustered components. PhysicsEngine/ClusterUnionComponent.h
  • EditAnywhere
  • Category="Cluster Union"
GravityGroupIndexOverride int32 If set to a value not equal to -1, will manually set the cluster union's gravity group instead of automatically inheriting it from its children particles. PhysicsEngine/ClusterUnionComponent.h
  • EditAnywhere
  • Category="Cluster Union"
PendingComponentsToAdd TMap< TObjectKey< UPrimitiveComponent >, FClusterUnionPendingAddData > Sometimes we might be in the process of waiting for a component to create it physics state before adding to the cluster. PhysicsEngine/ClusterUnionComponent.h  
PendingComponentSync TMap< TObjectKey< UPrimitiveComponent >, FClusterUnionPendingAddData > After we add to a cluster union, we need to wait for the sync from the PT back to the GT before removing the component from PendingComponentSync. PhysicsEngine/ClusterUnionComponent.h  
PerShapeComponentBone TArray< FSafePhysicsObjectHandle > At every physics sync, we keep track of which shape index matches which child primitive component and bone. PhysicsEngine/ClusterUnionComponent.h  
PhysicsProxy Chaos::FClusterUnionPhysicsProxy *   PhysicsEngine/ClusterUnionComponent.h  
PhysicsUserData FChaosUserData User data to be able to tie the cluster particle back to this component. PhysicsEngine/ClusterUnionComponent.h  
ReplicatedRigidState FClusterUnionReplicatedData Data that can be changed at runtime to keep state about the cluster union consistent between the server and client. PhysicsEngine/ClusterUnionComponent.h
  • ReplicatedUsing=OnRep_RigidState

Functions

Public

Name Remarks Include Path Unreal Specifiers

void AddComponentToCluster ( UPrimitiveComponent* InComponent,
const TArray< int32 >& BoneIds,
bool bRebuildGeometry
)

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"

void ChangeIfComponentBonesAreMainParticle ( UPrimitiveComponent* Component,
const TArray< int32 >& BoneIds,
bool bIsMain
)

   PhysicsEngine/ClusterUnionComponent.h  

Chaos::FPhysicsObjectHandle FindChildPhysicsObjectByShapeIndex ( int32 Index
) const

 This function will return information from the latest physics sync. PhysicsEngine/ClusterUnionComponent.h  
Force a rebuild of the GT geometry. PhysicsEngine/ClusterUnionComponent.h  

void ForceSetChildToParent ( UPrimitiveComponent* InComponent,
const TArray< int32 >& BoneIds,
const TArray< FTransform >& ChildToParent
)

 This should only be called on the client when replication happens. PhysicsEngine/ClusterUnionComponent.h  

TArray< AActor * > GetActors()

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"

TArray< int32 > GetAddedBoneIdsForComponent ( UPrimitiveComponent* Component
) const

   PhysicsEngine/ClusterUnionComponent.h  

TArray< UPrimitiveComponent * > GetPrimitiveComponents()

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"

const FSpatialAcceleration * GetSpatialAcceleration()

   PhysicsEngine/ClusterUnionComponent.h  

bool IsAnchored()

   PhysicsEngine/ClusterUnionComponent.h  

bool IsComponentAdded ( UPrimitiveComponent* Component
)

   PhysicsEngine/ClusterUnionComponent.h  

bool LineTraceComponent ( TArray< FHitResult >& OutHit,
const FVector Start,
const FVector End,
ECollisionChannel TraceChannel,
const FCollisionQueryParams& Params,
const FCollisionResponseParams& ResponseParams,
const FCollisionObjectQueryParams& ObjectParams
)

 Multi-trace/sweep functions that only make sense in the context of a cluster union. PhysicsEngine/ClusterUnionComponent.h  

int32 NumChildClusterComponents()

   PhysicsEngine/ClusterUnionComponent.h  

virtual void OnChildToParentUpdated ( UPrimitiveComponent* ChangedComponent,
const FLocalBonesToTransformMap& PerBoneChildToParent,
const FTransform& NewTransform,
TArray< TTuple< UPrimitiveComponent*, FTransform > >* OutNewComponents
)

   PhysicsEngine/ClusterUnionComponent.h  

void RemoveComponentBonesFromCluster ( UPrimitiveComponent* InComponent,
const TArray< int32 >& BoneIds
)

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"

void RemoveComponentFromCluster ( UPrimitiveComponent* InComponent
)

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"

void SetEnableDamageFromCollision ( bool bValue
)

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"

virtual void SetIsAnchored ( bool bIsAnchored
)

   PhysicsEngine/ClusterUnionComponent.h
  • BlueprintCallable
  • Category="Cluster Union"
  • Meta=(DeprecatedFunction, DeprecationMessage="SetIsAnchored is deprecated, Use SetSimulatePhysics instead")

bool SweepComponent ( TArray< FHitResult >& OutHit,
const FVector Start,
const FVector End,
const FQuat& ShapeWorldRotation,
const FPhysicsGeometry& Geometry,
ECollisionChannel TraceChannel,
const FCollisionQueryParams& Params,
const FCollisionResponseParams& ResponseParams,
const FCollisionObjectQueryParams& ObjectParams
)

   PhysicsEngine/ClusterUnionComponent.h  

void SyncClusterUnionFromProxy ( const FTransform& NewTransform,
TArray< TTuple< UPrimitiveComponent*, FTransform > >* OutNewComponents
)

 SyncClusterUnionFromProxy will examine the make up of the cluster union (particles, child to parent, etc.) and do whatever is needed on the GT in terms of bookkeeping. PhysicsEngine/ClusterUnionComponent.h  

void VisitAllCurrentActors ( const TFunction< bool(AActor*)>& Lambda
) const

   PhysicsEngine/ClusterUnionComponent.h  

void VisitAllCurrentChildComponents ( const TFunction< bool(UPrimitiveComponent*)>& Lambda
) const

 Lambda returns whether or not iteration should continue;. PhysicsEngine/ClusterUnionComponent.h  

Overridden from UPrimitiveComponent

Name Remarks Include Path Unreal Specifiers

virtual bool CanEditSimulatePhysics()

 Determines whether or not the simulate physics setting can be edited interactively on this component PhysicsEngine/ClusterUnionComponent.h  

virtual bool ComponentOverlapComponentWithResultImpl ( const UPrimitiveComponent*const PrimComp,
const FVector& Pos,
const FQuat& Rot,
const FCollisionQueryParams& Params,
TArray< FOverlapResult >& OutOverlap
) const

   PhysicsEngine/ClusterUnionComponent.h  

virtual FBodyInstance * GetBodyInstance ( FName BoneName,
bool bGetWelded,
int32 Index
) const

 Returns BodyInstance of the component. PhysicsEngine/ClusterUnionComponent.h  

virtual bool IsAnyRigidBodyAwake()

 Returns if any body in this component is currently awake and simulating. PhysicsEngine/ClusterUnionComponent.h  

virtual bool LineTraceComponent ( FHitResult& OutHit,
const FVector Start,
const FVector End,
ECollisionChannel TraceChannel,
const FCollisionQueryParams& Params,
const FCollisionResponseParams& ResponseParams,
const FCollisionObjectQueryParams& ObjectParams
)

 Trace a ray against just this component. PhysicsEngine/ClusterUnionComponent.h  

virtual bool LineTraceComponent ( FHitResult& OutHit,
const FVector Start,
const FVector End,
const FCollisionQueryParams& Params
)

 Trace a ray against just this component. PhysicsEngine/ClusterUnionComponent.h  

virtual bool OverlapComponentWithResult ( const FVector& Pos,
const FQuat& Rot,
const FCollisionShape& CollisionShape,
TArray< FOverlapResult >& OutOverlap
) const

 Test the collision of the supplied shape at the supplied location, and determine if it overlaps this component. PhysicsEngine/ClusterUnionComponent.h  

virtual bool OverlapComponentWithResult ( const FVector& Pos,
const FQuat& Rot,
const FPhysicsGeometry& Geometry,
ECollisionChannel TraceChannel,
const FCollisionQueryParams& Params,
const FCollisionResponseParams& ResponseParams,
const FCollisionObjectQueryParams& ObjectParams,
TArray< FOverlapResult >& OutOverlap
) const

 Test the collision of the supplied shape at the supplied location, and determine if it overlaps this component. PhysicsEngine/ClusterUnionComponent.h  

virtual void SetMassOverrideInKg ( FName BoneName,
float MassInKg,
bool bOverrideMass
)

 Set the cluster union total mass. PhysicsEngine/ClusterUnionComponent.h  

virtual void SetSimulatePhysics ( bool bSimulate
)

 When this component is a simple/single body, this will enable or disable simulation on that body. PhysicsEngine/ClusterUnionComponent.h  

virtual bool ShouldDispatchWakeEvents ( FName BoneName
) const

 Whether or not the primitive component should dispatch sleep/wake events. PhysicsEngine/ClusterUnionComponent.h  

virtual bool SweepComponent ( FHitResult& OutHit,
const FVector Start,
const FVector End,
const FQuat& ShapeWorldRotation,
const FCollisionShape& CollisionShape,
bool bTraceComplex
)

 Trace a shape against just this component. PhysicsEngine/ClusterUnionComponent.h  

virtual bool SweepComponent ( FHitResult& OutHit,
const FVector Start,
const FVector End,
const FQuat& ShapeWorldRotation,
const FPhysicsGeometry& Geometry,
ECollisionChannel TraceChannel,
const FCollisionQueryParams& Params,
const FCollisionResponseParams& ResponseParams,
const FCollisionObjectQueryParams& ObjectParams
)

 Trace a shape against just this component. PhysicsEngine/ClusterUnionComponent.h  

virtual void WakeAllRigidBodies()

 Ensure simulation is running for all bodies in this component. PhysicsEngine/ClusterUnionComponent.h  

Overridden from USceneComponent

Name Remarks Include Path Unreal Specifiers

virtual FBoxSphereBounds CalcBounds ( const FTransform& LocalToWorld
) const

 Calculate the bounds of the component. Default behavior is a bounding box/sphere of zero size. PhysicsEngine/ClusterUnionComponent.h  

virtual FVector GetComponentVelocity()

 Get velocity of the component: either ComponentVelocity, or the velocity of the physics body if simulating physics. PhysicsEngine/ClusterUnionComponent.h  

virtual void OnReceiveReplicatedState ( const FVector X,
const FQuat R,
const FVector V,
const FVector W
)

 Called when client receive replication data, before replication is performed. PhysicsEngine/ClusterUnionComponent.h  

virtual void OnUpdateTransform ( EUpdateTransformFlags UpdateTransformFlags,
ETeleportType Teleport
)

 Native callback when this component is moved PhysicsEngine/ClusterUnionComponent.h  

Overridden from UActorComponent

Name Remarks Include Path Unreal Specifiers

virtual bool HasValidPhysicsState()

 Used to check that DestroyPhysicsState() is working correctly PhysicsEngine/ClusterUnionComponent.h  

virtual void OnCreatePhysicsState()

 Used to create any physics engine information for this component PhysicsEngine/ClusterUnionComponent.h  

virtual void OnDestroyPhysicsState()

 Used to shut down and physics engine structure for this component PhysicsEngine/ClusterUnionComponent.h  

virtual bool ShouldCreatePhysicsState ()

 Return true if CreatePhysicsState() should be called. PhysicsEngine/ClusterUnionComponent.h  

Overridden from UObject

Name Remarks Include Path Unreal Specifiers

virtual void GetLifetimeReplicatedProps ( TArray< FLifetimeProperty >& OutLifetimeProps
) const

   PhysicsEngine/ClusterUnionComponent.h  

Overridden from INavRelevantInterface

Name Remarks Include Path Unreal Specifiers

virtual bool DoCustomNavigableGeometryExport ( FNavigableGeometryExport& GeomExport
) const

 Collects custom navigable geometry of component. PhysicsEngine/ClusterUnionComponent.h  

Overridden from IPhysicsComponent

Name Remarks Include Path Unreal Specifiers

virtual TArray< Chaos::FPhysicsObject * > GetAllPhysicsObjects()

   PhysicsEngine/ClusterUnionComponent.h  

virtual Chaos::FPhysicsObjectId GetIdFromGTParticle ( Chaos::FGeometryParticle* Particle
) const

   PhysicsEngine/ClusterUnionComponent.h  

virtual Chaos::FPhysicsObject * GetPhysicsObjectById ( Chaos::FPhysicsObjectId Id
) const

   PhysicsEngine/ClusterUnionComponent.h  

virtual Chaos::FPhysicsObject * GetPhysicsObjectByName ( const FName& Name
) const

   PhysicsEngine/ClusterUnionComponent.h  

Protected

Name Remarks Include Path Unreal Specifiers

void BroadcastComponentAddedEvents ( UPrimitiveComponent* ChangedComponent,
const TArray< FClusterUnionBoneData >& BoneIds,
bool bIsNew,
const TArray< FClusterUnionBoneData >& RemovedBoneIDs
)

   PhysicsEngine/ClusterUnionComponent.h  

void BroadcastComponentRemovedEvents ( UPrimitiveComponent* ChangedComponent,
const TArray< FClusterUnionBoneData >& InRemovedBonesData
)

   PhysicsEngine/ClusterUnionComponent.h  
  PhysicsEngine/ClusterUnionComponent.h  
  PhysicsEngine/ClusterUnionComponent.h  

const FClusterUnionReplicatedData & GetReplicatedRigidState()

   PhysicsEngine/ClusterUnionComponent.h  

bool IsAuthority()

 Whether or not this code is running on the server. PhysicsEngine/ClusterUnionComponent.h  

virtual void OnRep_RigidState ()

 Handles changes to ReplicatedRigidState. PhysicsEngine/ClusterUnionComponent.h  

virtual void SetRigidState ( Chaos::EObjectStateType ObjectState
)

   PhysicsEngine/ClusterUnionComponent.h  

Static

Name Remarks Include Path Unreal Specifiers

static void AddReferencedObjects ( UObject* InThis,
FReferenceCollector& Collector
)

   PhysicsEngine/ClusterUnionComponent.h  

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page