Blitz3D+ Command Reference

QueryPhysicsBodyContacts ( query,body )

Parameters

query - owned query handle

body - body handle

Description

Copies a body's current contact manifolds and returns their count.

Copies current contact manifolds for the supplied body in the query world and returns their count. An object with no touching contacts returns zero; a sensor shape has no contact manifolds. Captures native touching contact manifolds, including resting/sleeping contacts and speculative points whose separation can be positive. One mesh/terrain pair may yield several manifolds. Manifolds keep native A/B sides, are ordered by A/B shape handles, and retain native order within a pair. One-based manifold/point indices are local to this snapshot, not persistent contact handles. Contact capture sets query kind 8 and replaces any earlier spatial/proximity payload; CountPhysicsQueryHits becomes zero. Use CountPhysicsQueryManifolds and the PhysicsQueryContact accessors.

This is direct simulation-state inspection: query search filters/targets do not hide supplied objects or native contacts. Native collision filters, sensor/event settings and the most recently processed simulation state still determine the data. It does not force a new narrowphase pass after edits.

PhysicsQueryLimit counts manifolds for contact captures and visitors for occupancy; it accepts 1–65536, default 1024. A native contact-pair/visitor capacity above 65536 also raises an explicit error. Hit, manifold and temporary native-data buffers share the 64 MiB query budget. Overflow or allocation failure preserves the previous snapshot; nothing is silently truncated.

Query results are copied and survive stepping, other queries and deletion until this query runs successfully again or is freed. Generation-checked identity getters return zero for deleted objects; copied tags and numerical fields survive. Failed runs retain the complete previous payload. Freeing the owning world frees its queries.

Invalid/stale/wrong-kind handles, invalid indices or unavailable payload fields raise runtime errors.

Requires Extended mode.

See also: QueryPhysicsShapeContacts, QueryPhysicsSensor, CountPhysicsQueryManifolds, PhysicsBodyEvents.

Example

; QueryPhysicsBodyContacts Example
; --------------------------------
; Requires Extended mode.

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

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

camera=CreateCamera()
PositionEntity camera,0,3,-7
RotateEntity camera,20,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)

; An orange crate on the floor, with a green crate resting on top
crate=CreateCube()
ScaleEntity crate,0.6,0.6,0.6
EntityColor crate,255,120,70
crate_body=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
crate_shape=PhysicsBodyBox(crate_body,1.2,1.2,1.2)
top=CreateCube()
ScaleEntity top,0.4,0.4,0.4
EntityColor top,120,200,140
top_body=CreatePhysicsBody(world,top,PHYSICS_DYNAMIC)
top_shape=PhysicsBodyBox(top_body,0.8,0.8,0.8)
ResetPhysicsBody crate_body,0,0.6,0,0,0,0
ResetPhysicsBody top_body,0,1.6,0,0,0,0

; A query object keeps a copy of the contacts it finds
query=CreatePhysicsQuery(world)

While Not KeyDown(1)

    ; Space shoves the orange crate along the floor, R stacks the crates again
    If KeyHit(57) Then PhysicsBodyImpulse crate_body,4,0,0
    If KeyHit(19)
        ResetPhysicsBody crate_body,0,0.6,0,0,0,0
        ResetPhysicsBody top_body,0,1.6,0,0,0,0
    EndIf

    StepPhysics world,1.0/60.0,4

    ; Copy the orange crate's contacts: one manifold for each shape it touches
    manifolds=QueryPhysicsBodyContacts(query,crate_body)

    ; 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

    ; Ring every contact point
    For m=1 To manifolds
        For p=1 To PhysicsQueryContactPoints(query,m)
            CameraProject camera,PhysicsQueryContactX(query,m,p),PhysicsQueryContactY(query,m,p),PhysicsQueryContactZ(query,m,p)
            Oval ProjectedX()-3,ProjectedY()-3,7,7,False
        Next
    Next

    Text 0,0,"Arrow keys: move camera   Space: shove   R: reset   Esc: exit"
    Text 0,20,"QueryPhysicsBodyContacts(query,crate_body) = "+manifolds
    Text 0,40,"(the floor below it and the green crate on top)"

    Flip

Wend

FreePhysicsWorld world
End

Index