C4 Engine
C4 Engine API Documentation


Defined in:  C4World.h
Detects whether a swept sphere collides with world geometry or rigid bodies.

CollisionState QueryCollision(const Point3D& p1, const Point3D& p2, float radius, uint32 kind,

CollisionData *collisionData, const RigidBodyController *excludedBody = nullptrint32 threadIndex = ThreadMgr::kMaxWorkerThreadCount) const;

p1 The beginning of the line segment in world space.
p2 The end of the line segment in world space.
radius The radius of the sphere. This cannot be negative, but it can be zero.
kind The collision kind.
collisionData The returned collision data.
excludedBody A rigid body that will be excluded from the query.
threadIndex The index of the Thread Manager worker thread that is calling this function.
The points specified by the parameters p1 and p2, combined with the radius specified by the radius parameter, define a directed swept sphere. The QueryCollision function detects the first collision between this swept sphere and all Geometry nodes possessing collision information. Unlike the World::DetectCollision function, the QueryCollision function also detects collisions with any RigidBodyController objects. If a collision is detected, then the function returns either kCollisionStateGeometry or kCollisionStateRigidBody, depending on the type of collision; otherwise, it returns kCollisionStateNone.

The kind parameter can be used to invalidate certain types of collisions. When a candidate geometry or rigid body is encountered in the collision detection process, its collision exclusion mask is logically ANDed with the value of the kind parameter. A collision can only occur if the result of this operation is zero. The collision mask associated with a geometry can be set using the GeometryObject::SetCollisionExclusionMask function, and the collision mask for a rigid body can be set using the RigidBodyController::SetCollisionExclusionMask function. The collision kind can be a combination (through logical OR) of the following predefined values and application-defined values.
kCollisionRigidBody Any type of rigid body.
kCollisionCharacter A rigid body that represents a character.
kCollisionProjectile A rigid body that represents a projectile.
kCollisionVehicle A rigid body that represents a vehicle.
kCollisionCamera A type of camera.
kCollisionSightPath When used in an exclusion mask, does not obstruct sight.
kCollisionSoundPath When used in an exclusion mask, does not obstruct sound.
kCollisionBaseKind First application-defined collision kind.
kCollisionExcludeAll When used as a collision exclusion mask, this value prevents collisions with everything.
If a collision occurs, then the CollisionData structure pointed to by the collisionData parameter is filled out with information about the collision. The param field of this data structure represents the fraction of the distance that the sphere traveled from p1 to p2 before the collision occurred.

If the excludedBody parameter is not nullptr, then any potential collisions with the rigid body is specifies are ignored.

The threadIndex parameter specifies the index of the Thread Manager worker thread that has called the QueryCollision function. If the QueryCollision function is called from the main thread, then this parameter should not be specified so that the default value is used. If the QueryCollision function is called from a job, then the threadIndex parameter should be set to the value returned by the Job::GetThreadIndex function. The threadIndex parameter must be set correctly in order for multithreaded collision queries to work properly.
IMPORTANT. If the QueryCollision function is called from inside a Thread Manager worker thread, then the application code must ensure that the scene is not modified while the job is running.
See Also