Blitz3D+ Command Reference

PhysicsWorkers world,count

Parameters

world - standalone world from CreatePhysicsWorld, or a borrowed scene world from GetWorldPhysics

count - native worker-context count for the world, from 1 to 32

Description

Sets the native worker count and its per-worker simulation storage.

The current runtime creates worlds with serial scheduling. Changing this setting does not install a scheduler or enable parallel execution across CPU cores. A larger value reserves more worker storage; leave it at 1 unless your application needs a different native worker-count setting.

Change it between steps, typically once at startup after measuring the machine. A count outside 1 to 32 raises a runtime error. Read the current value back with PhysicsWorkerCount.

For a borrowed scene world, replacement storage is prepared before changing the count. Allocation failure preserves the previous count, worker storage, body state and event snapshots. The setting survives scene reconciliation and does not synchronize pending entity edits. Repeating the current count makes no allocation.

Requires Extended mode.

See also: PhysicsWorkerCount, StepPhysics, CreatePhysicsWorld, ValidatePhysicsRecording.

Example

; PhysicsWorkers Example
; ----------------------
; Requires Extended mode.

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

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2
Const CRATE_COUNT=24

SeedRnd MilliSecs()

camera=CreateCamera()
PositionEntity camera,0,6,-6
RotateEntity camera,20,0,0

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

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

; Request two solver workers; the engine clamps to its supported range
PhysicsWorkers world,2
workers=2

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

; A busy pile of dynamic crates keeps the workers occupied
Dim crate_ent(CRATE_COUNT)
Dim crate_body(CRATE_COUNT)
For i=1 To CRATE_COUNT
    crate_ent(i)=CreateCube()
    ScaleEntity crate_ent(i),0.4,0.4,0.4
    PositionEntity crate_ent(i),Rnd(-3,3),Rnd(2,8),Rnd(2,8),True
    EntityColor crate_ent(i),Rand(80,255),Rand(80,255),Rand(80,255)
    crate_body(i)=CreatePhysicsBody(world,crate_ent(i),PHYSICS_DYNAMIC)
    crate_shape=PhysicsBodyBox(crate_body(i),0.8,0.8,0.8,1)
Next

While Not KeyDown(1)

    ; [ and ] request fewer or more solver workers
    If KeyHit(26) And workers>1 Then workers=workers-1
    If KeyHit(27) And workers<8 Then workers=workers+1
    PhysicsWorkers world,workers

    ; Space tosses every crate back into the air
    If KeyHit(57)
        For i=1 To CRATE_COUNT
            PhysicsBodyImpulse crate_body(i),Rnd(-0.5,0.5),Rnd(2,4),Rnd(-0.5,0.5)
        Next
    EndIf

    StepPhysics world,1.0/60.0,4

    ; Respawn any crate that tumbled off the slab
    For i=1 To CRATE_COUNT
        If EntityY(crate_ent(i),True)<-6
            FreePhysicsBody crate_body(i)
            PositionEntity crate_ent(i),Rnd(-3,3),8,Rnd(2,8),True
            crate_body(i)=CreatePhysicsBody(world,crate_ent(i),PHYSICS_DYNAMIC)
            crate_shape=PhysicsBodyBox(crate_body(i),0.8,0.8,0.8,1)
        EndIf
    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,"[ / ]: request workers   Space: toss the crates   Arrow keys: camera   Esc: exit"
    Text 0,20,"PhysicsWorkers world,"+workers+"   PhysicsWorkerCount(world) = "+PhysicsWorkerCount(world)
    Text 0,40,"More workers can speed up busy worlds; the count changes between steps."

    Flip

Wend

FreePhysicsWorld world
End

Index