Blitz3D+ Command Reference

StepPhysics world,time_step#[,sub_steps]

Parameters

world - physics-world handle returned by CreatePhysicsWorld

time_step# - how far to advance the simulation, in seconds; must be positive

sub_steps (optional) - solver sub-steps per call, from 1 to 64; 4 (default)

Description

Advances a physics world by one time step.

This is the heartbeat of the physics system: call it once per frame, or nothing in the world will ever move. A fixed step such as 1.0/60.0 keeps the simulation stable and repeatable - feeding in a varying frame time makes stacks jitter and joints feel spongy. More sub-steps buy solver accuracy for fast bodies and big stacks at a CPU cost; the default of 4 suits most games.

Each call runs in a fixed order. First, kinematic bodies copy their entity's current position and rotation into the simulation - that is how you drive moving platforms with PositionEntity or MoveEntity. Then Box3D simulates the step. Finally, dynamic bodies write their new transforms back onto their entities, ready to render. Static bodies keep the transform they were created with.

The step also captures a fresh snapshot of contact and sensor events, replacing the previous one - read CountPhysicsContacts, CountPhysicsSensorEvents and their getters after stepping and before you step again. StepPhysics is completely independent of UpdateWorld and RenderWorld.

Requires Extended mode.

See also: CreatePhysicsWorld, PhysicsGravity, CreatePhysicsBody, CountPhysicsContacts, PhysicsWorkers.

Example

; StepPhysics 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,-6

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,5,True
EntityColor ground,80,160,255
ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
ground_shape=PhysicsBodyBox(ground_body,8,1,8,0)

; A tumbling crate for the simulation to animate
crate=CreateCube()
ScaleEntity crate,0.5,0.5,0.5
PositionEntity crate,0,4,5,True
EntityColor crate,255,120,70
crate_body=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
crate_shape=PhysicsBodyBox(crate_body,1,1,1,1)
PhysicsShapeRestitution crate_shape,0.5
PhysicsBodyAngularVelocity crate_body,2,1,3

dt#=1.0/60.0
running=1

While Not KeyDown(1)

    ; Space pauses and resumes the explicit stepping
    If KeyHit(57) Then running=1-running

    ; [ and ] halve or double the fixed time step (slow motion or fast)
    If KeyHit(26) Then dt=dt*0.5
    If KeyHit(27) Then dt=dt*2
    If dt<1.0/480 Then dt=1.0/480
    If dt>1.0/30 Then dt=1.0/30

    ; K kicks the crate back into the air with some spin
    If KeyHit(37)
        PhysicsBodyImpulse crate_body,0,5,0
        PhysicsBodyAngularVelocity crate_body,2,1,3
    EndIf

    ; The world only advances while StepPhysics is being called
    If running Then StepPhysics world,dt,4

    ; 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,"Space: pause stepping   [ / ]: time step   K: kick crate   Esc: exit"
    Text 0,20,"StepPhysics world,"+dt+",4   running: "+running
    Text 0,40,"Crate Y: "+EntityY(crate,True)

    Flip

Wend

FreePhysicsWorld world
End

Index