Scene Collision Query

Overview

The Scene Collision Query (Collision Detection) feature is used to detect the surface information of physics objects and object colliders in the physics scene.

Collision Detection Types

Detection Method	Description
Raycast	Raycast Collision Detection. Shoot a ray from the start position to the target position in the scene, and check whether there are other scene objects on this path.
Overlap	Overlap Collision Detection. Use a Collider (Sphere, Capsule, or Box) to detect whether there are other scene objects within the shape of the collider at a specified location in the scene.
Sweep	Sweep Collision Detection. Similar to Raycast Collision Detection, except that rays are replaced by Colliders (Sphere, Capsule, or Box). Move the collider from the start position to the target position in the scene, and detect whether the collider collides with other scene objects on its swept path.

Collider Types

Collider	Description
Sphere	Sphere is described by a radius parameter. The origin of the sphere is at its center.
Box	Box is described by three parameters: length, width, and height. The origin of the box is at its center.
Capsule	Capsule is described by two sets of parameters: radius and half height. The direction of the capsule extends along the X-axis direction with its origin at its center.

Collision Response Types

Collision Response	Description
Block	Raycast and Sweep Detections will return the closest collision result with the collision response as Block, and then terminate the Collision Detection. Overlap Detection will return all the collision results with the collision response as Block.
Overlap	Raycast and Sweep Detections will return all the collision results with the collision response as Overlap between the detection start point and the closest object whose collision response is Block. Overlap Detection will return all the collision results with the collision response as Overlap.
Ignore	Raycast, Overlap, and Sweep Detections will ignore the collision results with the collision response as Ignore.

Collision Query Methods

Query Method	Description
Test	Only returns information about whether a collision occurred, and does not return information of the object collided with.
Single	Return the collision information of the Block object closest to the start point.
Multi	Raycast and Sweep Detections will return the collision information of object that is closest to the start point with collision response as Block, and the collision information of the object in the path from the start point to the closest collided object with the collision response as Overlap. Overlap Detection will return all objects with collision responses as Block and Overlap within the range of the collider.

Query Method	Description
ByChannel	Query by Channel (Object Type) and collision response parameters. Each component in the scene comes with a set of collision parameters (Channel + collision response parameters). ByChannel uses the collision parameters passed in through the interface to make collision judgments with the components in the scene. Components whose collision result is Block or Overlap (the query method must be Multi) will be returned. For the description of the Channel and collision response parameters, as well as the description of the collision judgment rules, please refer to the section Collision in the documentation Common Physics Properties.
ByObjectType	Query by Object Type. ByObjectType makes collision judgments with the components in the scene by inputting the Object Type to be queried. Components matching the Object Type will be returned.
ByProfile	Query by Collision Preset Type. The Collision Preset Configuration passed in by the ByProfile interface is used for collision judgments with the components in the scene. Components whose collision result is Block or Overlap (the query method must be Multi) will be returned.
ByComponent	Query by Component. ByComponent uses the component's own collider settings and collision parameter settings to make collision judgments with other components in the scene. Components whose collision result is Block or Overlap (the query method must be Multi) will be returned.

Major Parameter Descriptions

Collision Channel Types (enum COLLISION_CHANNEL)

Related header file path: \source\fx_component\physics\physics_define.h

enum class COLLISION_CHANNEL : unsigned char
{
    WorldStatic = CollisionChannel::eStatic,
    WorldDynamic = CollisionChannel::eDynamic,
    Pawn = CollisionChannel::ePawn,
    Vehicle = CollisionChannel::eVehicle,
    Destructible = CollisionChannel::eDestructible,
    Visibility = CollisionChannel::eVisibility,
    Camera = CollisionChannel::eCamera,
    Trigger = CollisionChannel::eTrigger,
    EngineTraceChannel1 = CollisionChannel::eEngineChannel8,
    EngineTraceChannel2 = CollisionChannel::eEngineChannel9,
    EngineTraceChannel3 = CollisionChannel::eEngineChannel10,
    EngineTraceChannel4 = CollisionChannel::eEngineChannel11,
    EngineTraceChannel5 = CollisionChannel::eEngineChannel12,
    EngineTraceChannel6 = CollisionChannel::eEngineChannel13,

    GameTraceChannel1,
    GameTraceChannel2,
    GameTraceChannel3,
    GameTraceChannel4,
    GameTraceChannel5,
    GameTraceChannel6,
    GameTraceChannel7,
    GameTraceChannel8,
    GameTraceChannel9,
    GameTraceChannel10,
    GameTraceChannel11,
    GameTraceChannel12,
    GameTraceChannel13,
    GameTraceChannel14,
    GameTraceChannel15,
    GameTraceChannel16,
    GameTraceChannel17,
    GameTraceChannel18,

    MAX,
}FX_ENUM();

Channel Type	Description
WorldStatic	Represent the static object whose position in the scene does not change such as buildings and trees.
WorldDynamic	Represent the dynamic object whose position in the scene may change such as tables and chairs, cans and so on.
Pawn	Represent the character controlled by the Player or AI.
Vehicle	Represent the vehicle in the scene.
Destructible	Represent the destructible object in the scene.
Visibility	Mostly used for visibility collision detection.
Camera	Mostly used for camera objects in the scene, and camera collision detection.
Trigger	Mostly used for trigger objects in the scene, and collision detection triggered by trigger events.
EngineTraceChannel(1-6)	Engine's reserved collision channel type.
GameTraceChannel(1-18)	Collision channel types reserved for users' customization. For the method of adding a custom collision channel in the Editor, please refer to the documentation Collision Preset Editor.

Note: There are 32 types of collision channels (objects) in total, 18 of which are provided for users to customize.

Querying Parameters by Object Types (struct collision_object_query_params_t)

Interface	Description
`AddObjectTypesToQuery`	Add the object (channel) type of this query.

Collision Response Parameters (struct collision_response_params_t)

Header file path: \source\fx_component\physics\physics_define.h

struct COMPONENT_API collision_response_params_t
{
    collision_response_container_t CollisionResponse;
    collision_response_params_t(COLLISION_RESPONSE DefaultResponse = COLLISION_RESPONSE::Block)
    {
        CollisionResponse.SetAllChannels(DefaultResponse);
    }

    collision_response_params_t(const collision_response_container_t& ResponseContainer)
    {
        CollisionResponse = ResponseContainer;
    }
    
    static collision_response_params_t DefaultResponseParam;
};

Parameter	Description
`collision_response_container_t CollisionResponse`	Collision response parameter container which contains collision response settings for 32 collision channels. For the description of the Channel and collision response parameters, as well as the description of the collision judgment rules, please refer to the section Collision in the documentation Common Physics Properties.

Collision Query Parameters (class CCollisionQueryParams)

Parameter	Description
`bool bFindInitialOverlaps`	When the start position of the Raycast or Sweep Collision Detection is inside other scene objects, the collision detection will end and prompt the collision result that the start position is penetrated into other objects. If bFindInitialOverlaps is true, the collision detection will ignore the collision of the object at the start position and continue detecting.
`bool bIgnoreBlocks`	Ignore all the results of the collision response as Block in this collision detection.
`bool bIgnoreTouches`	Ignore all the results of the collision response as Overlap in this collision detection.
`QueryMobilityType::Enum eMobilityType`	Only dynamic/static colliders are queried during collision detection. QueryMobilityType::eStatic Only static colliders are queried in this collision detection. QueryMobilityType::eDynamic Only dynamic colliders are queried in this collision detection. QueryMobilityType::eAny Both dynamic and static colliders are queried in this collision detection.
`bool bPickBothSides`	Enable both sides detection. It only takes effect during the Raycast Collision Detection. If the ray penetrates the object when bPickBothSides is true, the collision information on the back of the object can be picked up.

Ignoring Collisions with Specified Objects

It will not be able to meet the logical requirement to ignore certain object collision detection only through collision detection and Collision Response parameter settings on each component. At this point, you can ignore the collision of some specific objects in collision detection by adding Ignore objects.

Interface	Description
`AddIgnoredGameObject`	Ignore collisions with the specified game object.
`AddIgnoredComponent`	Ignore collisions with the specified component object.

Writing Custom Collision Filtering Logic

Interface	Description
SetLogicExt	Add a logic extension to filter all objects whose collision response is Block, and decide whether to retain the collision result with this object in this collision detection.

Refer to the implementation of class CollisionQueryFilter in \source\fx_component\fx_physics\collision_query_filter.h. Implement your own collision filtering logic by deriving a new type from CollisionQueryFilter. The implementation of the class CollisionQueryFilter is as follows:

#include "collision_query_filter.h"
#include "rigid_instance.h"
#include "ragdoll_instance.h"
#include "../primitive_component.h"
#include "../game_object.h"
#include "../physics/physx_user_data.h"
#include "flexi/physics/i_physics_rigid.h"
#include "flexi/utils/array_utils.h"
#include "flexi/object/casts.h"

CollisionQueryFilter::CollisionQueryFilter(const CCollisionQueryParams& QueryParams)
    : m_IgnoreComponents(QueryParams.GetIgnoredComponents())
    , m_IgnoreGameObjects(QueryParams.GetIgnoredGameObjects())
{
    
}

bool CollisionQueryFilter::OnKeepHit(const PERSISTID& phy_obj, unsigned int shape_key,
    const wchar_t* debug_tag, const wchar_t* owner_tag)
{
    FxPhysicsBase* pPhysicsObj = (FxPhysicsBase*)g_pCore->GetEntity(phy_obj);
    if (NULL == pPhysicsObj)
    {
        return false;
    }

    LPrimitiveComponent* pOwnerComponent = NULL;

    PhysicsProxy* pPhysicsProxy =
        physx_user_data_t::Get<PhysicsProxy>(pPhysicsObj->GetUserData());

    if (pPhysicsProxy != NULL)
    {
        pOwnerComponent = Cast<LPrimitiveComponent>(pPhysicsProxy->GetOwnerComponent());
    }
    
    if (NULL == pOwnerComponent)
    {
        return false;
    }

    LGameObject* pOwner = pOwnerComponent->GetGameObjectOwner();
    if (NULL == pOwner)
    {
        Assert(0);
        return false;
    }

    if (ArrayContains(m_IgnoreGameObjects, pOwner->GetID()))
    {
        return false;
    }

    if (ArrayContains(m_IgnoreComponents, pOwnerComponent->GetID()))
    {
        return false;
    }

    return true;
}

If the OnKeepHit function returns true, the collision result will be kept, otherwise the collision result will be ignored.

Collider Parameters (class CCollisionShape)

Interface	Description
`SetCapsule`	Set the appearance of the Capsule.
`SetBox`	Set the appearance of the Box.
`SetSphere`	Set the appearance of the Sphere.

Collision Detection Result Parameters (struct hit_result_t)

Parameter	Description
`PERSISTID GameObjectID`	The game object that collided with.
`PERSISTID ComponentID`	The component object that collided with.
`STRINGID BoneName`	When the collision detects the ragdoll bone rigidbody, BoneName indicates the name of the ragdoll bone that collided with.
`float fTime`	fTime = fDistance / length(f3QueryEnd - f3QueryStart)
`bool bBlockingHit`	If bBlockingHit is true, the collision response type of the current collision result will be Block. If it is false, the collision response type will be Overlap.
`PERSISTID ActorID`	The rigidbody/destructible object that collided with.
`int nShapeIndex`	When the ActorID is a rigidbody object, nShapeIndex represents the collider index of the rigidbody. When the ActorID is a destructible object, nShapeIndex indicates the index of the destructible Chunk collided with, and -1 means an invalid destructible Chunk.
`PERSISTID MateiralID`	The physics material object on the surface of the collider detected by the collision. For details about physics materials, see the documentation Creating and Using Physics Materials.
`FFLOAT3 f3QueryStart`	Collision detection start position.
`FFLOAT3 f3QueryEnd`	Collision detection end position.
`bool bStartPenetrating`	Whether the start position penetrates into other objects.
`float fPenetrationDepth`	Penetration depth.
`FFLOAT3 f3Location`	The position of the collider when the collision occurred.
`FFLOAT3 f3ImpactPoint`	The position of the collision point.
`FFLOAT3 f3Normal`	When the collider type of Sweep Collision Detection is Sphere or Capsule, this value is a vector pointing to the origin of the collider from the collision point.
`FFLOAT3 f3ImpactNormal`	The surface normal on which the collision point lies.
`float fDistance`	The distance at which the collision occurred.
`unsigned int nFaceIndex`	Collision triangle index.

Interface Descriptions

Line Trace (Raycast) Detection