Blitz3D+ Command Reference

PhysicsBodyIsAwake ( body )

Parameters

body - physics-body handle returned by CreatePhysicsBody

Description

Returns True while a body is awake and actively simulating.

To save CPU, Box3D puts dynamic bodies to sleep once they have been nearly still (below roughly 0.05 metres per second) for a little while. Sleeping bodies cost almost nothing and wake automatically when something touches them or when you apply a force, an impulse or a new velocity.

This query lets you piggyback on that logic: skip per-body game logic for props that are asleep, wait for a tower of crates to settle before scoring the throw, or tint debug visuals by sleep state to see what the simulation is really spending time on.

Requires Extended mode.

See also: StepPhysics, PhysicsBodyVelocity, PhysicsBodyForce, PhysicsBodyImpulse.

Example

; PhysicsBodyIsAwake 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,-9

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

; Independent Box3D world with Earth-like gravity
world=CreatePhysicsWorld()
PhysicsGravity world,0,-9.81,0

; Blue 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)

; Ball dropped from above - it settles, then falls asleep
ball=CreateSphere()
ScaleEntity ball,0.5,0.5,0.5
PositionEntity ball,0,3,0,True
EntityColor ball,255,120,70
ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
ball_shape=PhysicsBodySphere(ball_body,1,1)
PhysicsShapeRestitution ball_shape,0.3

While Not KeyDown(1)

    ; Space kicks the ball, which also wakes a sleeping body
    If KeyHit(57) Then PhysicsBodyImpulse ball_body,0,2,0

    ; Advance the Box3D simulation by one 60 Hz step
    StepPhysics world,1.0/60.0,4

    ; Poll the sleep state and colour the ball to match
    awake=PhysicsBodyIsAwake(ball_body)
    If awake Then EntityColor ball,255,120,70 Else EntityColor ball,150,150,150

    ; 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   Space: wake the ball   Esc: exit"
    If awake
        Text 0,20,"PhysicsBodyIsAwake = "+awake+"   (orange = simulating)"
    Else
        Text 0,20,"PhysicsBodyIsAwake = "+awake+"   (grey = asleep, let it settle)"
    EndIf

    Flip

Wend

FreePhysicsWorld world
FreeEntity ball
FreeEntity ground
End

Index