Raycaster QML Type

Casts a ray into the physics scene on every physics frame. More...

• List of all members, including inherited members

Properties

• direction : vector3d
• enabled : bool
• excludeParentBody : bool
• excludedBodies : list<PhysicsNode>
• hit : locationHit
• includeDynamic : bool
• includeStatic : bool
• isColliding : bool
• maxDistance : real

Signals

• bodyEntered(PhysicsNode body)
• bodyExited(PhysicsNode body)

Detailed Description

Raycaster casts a ray from its scene position in direction and reports the closest physics body it intersects. The hit property is updated once per physics frame, after the bodies have been synchronized with the scene and before PhysicsWorld::frameDone, so a frameDone handler reads the result of the frame it is reporting on.

Raycaster {
    direction: Qt.vector3d(0, -1, 0)
    maxDistance: 50
    includeDynamic: false
    onBodyEntered: (body) => console.log("Hit", body)
}

The ray is a scene query, so it sees the same bodies as PhysicsWorld.singleRaycastQuery and is bound by the same rules: filterGroup and filterIgnoreGroups have no effect on it, and a TriggerBody never appears in the result. Use includeStatic and includeDynamic to narrow that by kind, and excludeParentBody and excludedBodies to leave out particular bodies. Those two matter more here than for a query method, since the ray reports only its closest hit and there is nothing left to filter afterwards.

See also PhysicsWorld, locationHit, Qt Quick 3D Physics Scene Queries, and Qt Quick 3D Physics - Raycaster Example.

Property Documentation

direction : vector3d

The ray direction in local coordinates. It is transformed to scene coordinates and normalized before the ray is cast. A zero vector produces no hit. Non-finite values are ignored.

The default value is Qt.vector3d(0, 0, -1).

enabled : bool

Controls whether the ray is cast on each physics frame. Disabling the ray clears hit and sets isColliding to false.

The default value is true.

excludeParentBody : bool

When true, every PhysicsNode ancestor of the ray is excluded from the query, not only the nearest one. A ray mounted on a body starts inside that body's own shapes, and a raycast does report the shape it starts inside, so without this the ray reports the body carrying it at a distance of zero and never sees anything beyond.

The default value is true.

See also excludedBodies.

excludedBodies : list<PhysicsNode>

Bodies the ray never reports, whether or not they are ancestors of it. Use this for a body the ray has to ignore but is not mounted on, such as the character carrying the weapon a ray is fired from, where the two are siblings rather than one inside the other.

Because the ray reports only its closest hit, there is no way to filter its result afterwards the way the PhysicsWorld query methods allow, so anything that has to be left out has to be named here or covered by excludeParentBody.

The list is empty by default. A body destroyed after it was added stops being excluded and reads back as null, rather than being removed from the list.

See also excludeParentBody.

hit : locationHit [read-only]

The closest intersection reported by the ray. The value contains the intersected body and collision shape, along with the scene-space position and normal and the distance from the ray origin. It is a default-constructed locationHit when isColliding is false.

includeDynamic : bool

Whether dynamic physics bodies are included in the query.

The default value is true.

When both includeStatic and includeDynamic are false, the ray produces no hit.

includeStatic : bool

Whether static physics bodies are included in the query.

The default value is true.

isColliding : bool [read-only]

Whether the ray currently intersects a physics body.

maxDistance : real

The maximum distance of the ray in scene units. A value of zero produces no hit. Negative and non-finite values are ignored.

The default value is 100.

Signal Documentation

bodyEntered(PhysicsNode body)

Emitted when the ray starts intersecting body. When the intersected body changes, bodyExited is emitted for the old body before this signal is emitted for the new body.

bodyExited(PhysicsNode body)

Emitted when the ray stops intersecting body.