Blitz3D+ Command Reference

QueryPhysicsShapeClosestPoint ( query,shape,x#,y#,z# )

Parameters

query - owned query handle

shape - shape handle

x# - finite world-space target coordinate in metres
y# - finite world-space target coordinate in metres
z# - finite world-space target coordinate in metres

Description

Finds the point on the solid convex shape closest to a finite world-space target, in metres.

Returns 1 and stores a kind-5 snapshot containing the nearest shape's identity/tags and world point at hit index 1. PhysicsQueryDistance returns the non-negative surface distance, including sphere/capsule radii. An interior target has distance zero and is returned as the closest point. A positive-distance result also has a unit normal from the shape toward the target; at zero distance PhysicsQueryHasNormal is false. Fraction/material/triangle/child fields are unavailable (triangle/child are -1).

These are direct measurements of explicitly supplied geometry, so PhysicsQueryFilter and PhysicsQueryTarget settings, sensors, collision rules and disabled-body broadphase membership do not exclude the requested objects. All supplied objects must belong to the query world. Geometry uses the current native body pose and authored local offsets; visual mesh edits do not recook it. Supported proximity geometry is sphere, capsule and convex hull/box. Mesh, terrain and compound shapes are rejected before native proxy construction; body queries reject a body containing any unsupported shape.

Results are copied and survive StepPhysics, other queries and deletion of referenced objects until this query runs successfully again or is freed. Live identity getters return zero for deleted objects while tags, available geometry and distance remain readable. A failed operation preserves the entire previous snapshot. Freeing the world frees its queries. Invalid handles, indices or unavailable fields raise runtime errors.

Requires Extended mode.

See also: CreatePhysicsQuery, QueryPhysicsBodyClosestPoint, QueryPhysicsShapeDistance, PhysicsQueryDistance, PhysicsQueryHasPoint.

Example

; QueryPhysicsShapeClosestPoint Example
; -------------------------------------
; Requires Extended mode.

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

camera=CreateCamera()
PositionEntity camera,0,7,-8
RotateEntity camera,40,0,0

light=CreateLight()
RotateEntity light,45,-30,0
AmbientLight 60,60,60

; An independent Box3D world with standard gravity
world=CreatePhysicsWorld()

; Blue static floor
ground=CreateCube()
ScaleEntity ground,6,0.5,6
PositionEntity ground,0,-0.5,0
EntityColor ground,80,160,255
ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
ground_shape=PhysicsBodyBox(ground_body,12,1,12)

; Crates scattered over the floor
Dim crates(9)
Dim crate_bodies(9)
For i=0 To 9
    crates(i)=CreateCube()
    ScaleEntity crates(i),0.4,0.4,0.4
    PositionEntity crates(i),Rnd(-4,4),0.4,Rnd(-4,4)
    crate_bodies(i)=CreatePhysicsBody(world,crates(i),PHYSICS_DYNAMIC)
    crate_shape=PhysicsBodyBox(crate_bodies(i),0.8,0.8,0.8)
Next

; A query object runs searches and keeps a copy of their results
; It ignores the floor body, so only crates are found
query=CreatePhysicsQuery(world)
PhysicsQueryFilter query,-1,-1,ground_body

; A see-through yellow probe shows the search volume
; A small probe point, and the nearest crate is crate 0
probe=CreateSphere(8)
ScaleEntity probe,0.15,0.15,0.15
PositionEntity probe,0,0.5,0
EntityColor probe,255,230,60
EntityAlpha probe,0.4

While Not KeyDown(1)

    ; A, D, W and S move the probe over the floor
    If KeyDown(30) Then MoveEntity probe,-0.05,0,0
    If KeyDown(32) Then MoveEntity probe,0.05,0,0
    If KeyDown(17) Then MoveEntity probe,0,0,0.05
    If KeyDown(31) Then MoveEntity probe,0,0,-0.05
    px#=EntityX(probe)
    pz#=EntityZ(probe)

    StepPhysics world,1.0/60.0,4

    ; Find the point on crate 0's shape closest to the probe
    hits=QueryPhysicsShapeClosestPoint(query,PhysicsBodyShape(crate_bodies(0),1),px,0.5,pz)

    ; Crates found by the search turn yellow
    For i=0 To 9
        EntityColor crates(i),255,120,70
    Next
    For h=1 To hits
        found=PhysicsQueryEntity(query,h)
        If found<>ground Then EntityColor found,255,230,60
    Next

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    ; Draw a line from the probe to the closest point
    If hits>0
        CameraProject camera,px,0.5,pz
        probe_x=ProjectedX()
        probe_y=ProjectedY()
        CameraProject camera,PhysicsQueryX(query,1),PhysicsQueryY(query,1),PhysicsQueryZ(query,1)
        Line probe_x,probe_y,ProjectedX(),ProjectedY()
    EndIf

    Text 0,0,"Arrow keys: move camera   A / D / W / S: move the probe   Esc: exit"
    Text 0,20,"Distance to crate 0's shape: "+PhysicsQueryDistance(query)+" m"

    Flip

Wend

FreePhysicsWorld world
End

Index