FreePhysicsWorld world

Parameters

world - physics-world handle returned by CreatePhysicsWorld

Description

Destroys a physics world and everything it owns.

Every body, shape and joint created in the world is destroyed with it, so you do not need to free them one by one - freeing the world at level shutdown is enough. All of those handles become invalid at the same moment, and using any of them afterwards raises a runtime error.

The Blitz entities that were attached to physics bodies are not touched. They stay exactly where the simulation left them and can still be moved, rendered or freed normally, so you can keep the visuals while throwing the simulation away.

If the world is still recording (StartPhysicsRecording), the recording is discarded.

Requires Extended mode.

See also: CreatePhysicsWorld, FreePhysicsBody, FreePhysicsShape, FreePhysicsJoint.

Example

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

; Orange crate bouncing under physics control
crate=CreateCube()
ScaleEntity crate,0.5,0.5,0.5
PositionEntity crate,0,3,0,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

While Not KeyDown(1)

    ; Space frees the whole world, or rebuilds it from scratch
    If KeyHit(57)
        If world<>0
            ; Free the world - every body and shape dies with it
            FreePhysicsWorld world
            world=0
            ground_body=0
            ground_shape=0
            crate_body=0
            crate_shape=0
            EntityColor crate,80,220,120
        Else
            ; Build a fresh world and new bodies for the surviving entities
            world=CreatePhysicsWorld()
            PhysicsGravity world,0,-9.81,0
            ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
            ground_shape=PhysicsBodyBox(ground_body,8,1,8,0)
            PositionEntity crate,0,3,0,True
            RotateEntity crate,0,0,0
            crate_body=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
            crate_shape=PhysicsBodyBox(crate_body,1,1,1,1)
            PhysicsShapeRestitution crate_shape,0.5
            EntityColor crate,255,120,70
        EndIf
    EndIf

    ; Only step the simulation while the world exists
    If world<>0 Then StepPhysics world,1.0/60.0,4

    ; The entities survive the freed world - spin the crate to prove it
    If world=0 Then TurnEntity crate,0,2,0

    ; 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: free / rebuild world   Esc: exit"
    If world<>0
        Text 0,20,"World handle: "+world+"   (simulating)"
    Else
        Text 0,20,"World freed - the green entity remains alive"
    EndIf

    Flip

Wend

If world<>0 Then FreePhysicsWorld world
FreeEntity crate
FreeEntity ground
End

Index

Blitz3D+ Command Reference

FreePhysicsWorld world

Parameters

Description

Example