Blitz3D+ Command Reference

QueryPhysicsBox ( query,x#,y#,z#,width#,height#,depth#[,pitch#][,yaw#][,roll#] )

Parameters

query - query handle

x# - world-space centre/origin X, in metres
y# - world-space centre/origin Y, in metres
z# - world-space centre/origin Z, in metres

width# - positive box X dimension in metres

height# - positive box Y dimension in metres

depth# - positive box Z dimension in metres

pitch# (optional) - Blitz pitch in radians, default 0 (optional; 0) (default)

yaw# (optional) - Blitz yaw in radians, default 0 (optional; 0) (default)

roll# (optional) - Blitz roll in radians, default 0 (optional; 0) (default)

Description

Finds the shapes that overlap a box.

Tests exact narrowphase overlap of a box at the supplied world-space centre, with positive finite width, height and depth in metres. Optional pitch/yaw/roll are Blitz rotations in radians (default zero). Initial intersections are included.

Returns one hit per overlapping owning shape, sorted by wrapper shape handle. These results contain identities and copied tags, without invented contact points, normals, fractions or per-triangle material data. Use PhysicsQueryHasPoint/HasNormal before accessing geometry. Mesh/terrain overlap means intersection with triangle surfaces, not containment inside a closed mesh.

Queries use two-sided category/mask filtering in the existing 32-bit domain, plus optional ignored-body, sensor and target rules. Collision groups and joints do not override query masks. Disabled bodies are absent from world queries. Existing shape filters default to all category bits; assign explicit shape categories when separating groups.

Results are copied. They survive StepPhysics and other queries until this query runs successfully again or is freed. Failed runs preserve the previous results. Freeing the owning world frees its queries. Invalid/stale/wrong-kind handles and invalid hit indices raise runtime errors.

Requires Extended mode.

See also: CreatePhysicsQuery, PhysicsQueryFilter, PhysicsQueryTarget, QueryPhysicsRay, QueryPhysicsSphere, PhysicsQueryLimit.

Example

; QueryPhysicsBox 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
probe=CreateCube()
ScaleEntity probe,1,0.5,0.5
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 every shape inside a 2 x 1 x 1 box at the probe
    hits=QueryPhysicsBox(query,px,0.5,pz,2,1,1)

    ; 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

    Text 0,0,"Arrow keys: move camera   A / D / W / S: move the probe   Esc: exit"
    Text 0,20,"QueryPhysicsBox(query,x,0.5,z,2,1,1) = "+hits

    Flip

Wend

FreePhysicsWorld world
End

Index