Blitz3D+ Command Reference

FreePhysicsBody body

Parameters

body - physics-body handle returned by CreatePhysicsBody

Description

Destroys a physics body along with its shapes and joints.

Every shape attached to the body and every joint connected to it is destroyed too, and all of those handles become invalid - using one afterwards raises a runtime error.

The Blitz entity is left alone: it stays where the simulation last put it and can carry on being moved, rendered or freed like any other entity. The entity is free to receive a new body later with CreatePhysicsBody, which is the usual way to respawn a prop.

You rarely need to call this at shutdown - FreePhysicsWorld destroys all bodies in one go, and FreeEntity on an entity that owns a body (or a parent of it) frees the body automatically.

Requires Extended mode.

See also: CreatePhysicsBody, FreePhysicsShape, FreePhysicsJoint, FreePhysicsWorld, FreeEntity.

Example

; FreePhysicsBody 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 body, or gives the entity a new one
    If KeyHit(57)
        If crate_body<>0
            ; Free the body - the entity detaches from physics mid-motion
            FreePhysicsBody crate_body
            crate_body=0
            crate_shape=0
            EntityColor crate,80,220,120
        Else
            ; Give the entity a fresh body to resume simulation
            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

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

    ; The freed entity is still alive - spin it by hand to prove it
    If crate_body=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 / recreate body   Esc: exit"
    If crate_body<>0
        Text 0,20,"Body handle: "+crate_body+"   (orange = simulated by Box3D)"
    Else
        Text 0,20,"Body freed - the green entity is program-controlled again"
    EndIf

    Flip

Wend

FreePhysicsWorld world
FreeEntity crate
FreeEntity ground
End

Index