Blitz3D+ Command Reference

PhysicsDebugDraw world,camera[,flags]

Parameters

world - physics-world handle returned by CreatePhysicsWorld

camera - camera entity used to project the debug lines onto the screen

flags (optional) - bit mask choosing what to draw; 7 (default) draws everything:
1: joints
2: contact points and normals
4: body bounds boxes

Description

Draws a physics world's diagnostics as lines through a camera.

The quickest way to see what the simulation thinks is happening. Joints, contact points with their normals, and each body's bounds box are projected through the camera and drawn as coloured 2D lines over the frame - so an invisible misplaced shape, a joint anchored in the wrong spot or a contact that should not exist shows up immediately.

Call it after RenderWorld (so the lines land on top of the scene) and before Flip. Add the flag values together to pick layers: 6 draws contacts and bounds but no joints. Drawing leaves the 2D Color set to white.

This is a debug tool - with many bodies the line drawing is slow, so switch it off (or gate it behind a debug key) in release builds.

Requires Extended mode.

See also: StepPhysics, CreatePhysicsWorld, CountPhysicsContacts, PhysicsRayCast.

Example

; PhysicsDebugDraw Example
; ------------------------
; Requires Extended mode.

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

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

camera=CreateCamera()
PositionEntity camera,0,6,-7
RotateEntity camera,30,0,0

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

world=CreatePhysicsWorld()
PhysicsGravity world,0,-9.81,0

; Static ground slab
ground=CreateCube()
ScaleEntity ground,4,0.5,4
PositionEntity ground,0,-0.5,0,True
EntityColor ground,80,160,255
ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
ground_shape=PhysicsBodyBox(ground_body,8,1,8,0)

; A static pivot post in the middle of the arena
pivot=CreateCylinder()
ScaleEntity pivot,0.2,0.75,0.2
PositionEntity pivot,0,0.75,0,True
EntityColor pivot,200,200,200
pivot_body=CreatePhysicsBody(world,pivot,PHYSICS_STATIC)
pivot_shape=PhysicsBodyCapsule(pivot_body,0.4,1.5,0)

; A motorised paddle arm hinged to the pivot
arm=CreateCube()
ScaleEntity arm,1.5,0.2,0.2
PositionEntity arm,1.8,0.6,0,True
EntityColor arm,255,120,70
arm_body=CreatePhysicsBody(world,arm,PHYSICS_DYNAMIC)
arm_shape=PhysicsBodyBox(arm_body,3,0.4,0.4,1)
hinge=CreatePhysicsHingeJoint(pivot_body,arm_body,0,0.6,0,0,1,0)
PhysicsJointMotor hinge,1,2,50

; A ball for the paddle to knock about
ball=CreateSphere(16)
ScaleEntity ball,0.5,0.5,0.5
PositionEntity ball,2.2,0.5,2.2,True
EntityColor ball,90,220,120
ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
ball_shape=PhysicsBodySphere(ball_body,1,1)

show=1
flags=7

While Not KeyDown(1)

    ; Space toggles the overlay; 1 / 2 / 3 toggle the joint, contact and bounds layers
    If KeyHit(57) Then show=1-show
    If KeyHit(2) Then flags=flags Xor 1
    If KeyHit(3) Then flags=flags Xor 2
    If KeyHit(4) Then flags=flags Xor 4

    StepPhysics world,1.0/60.0,4

    ; Respawn the ball if the paddle knocks it off the slab
    If EntityY(ball,True)<-4
        FreePhysicsBody ball_body
        PositionEntity ball,2.2,0.5,2.2,True
        ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
        ball_shape=PhysicsBodySphere(ball_body,1,1)
    EndIf

    ; 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

    ; Debug drawing happens after RenderWorld and before Flip
    If show Then PhysicsDebugDraw world,camera,flags

    Text 0,0,"Space: toggle overlay   1/2/3: joint/contact/bounds   Arrows: camera   Esc: exit"
    Text 0,20,"PhysicsDebugDraw world,camera,"+flags+"   overlay on: "+show

    Flip

Wend

FreePhysicsWorld world
End

Index