Blitz3D+ Command Reference

FreePhysicsJoint joint

Parameters

joint - physics-joint handle from a joint creation command

Description

Destroys a physics joint, releasing the two bodies from each other.

The moment the joint goes, the bodies fly free with whatever motion they had - which is exactly what you want for cutting a rope bridge, snapping a chain link or breaking a welded structure apart under fire.

The handle becomes invalid and using it again raises a runtime error. Joints are also cleaned up automatically when either connected body is freed (FreePhysicsBody, or FreeEntity on its entity) and when the world is freed, so explicit calls are only needed for deliberate mid-game breaks.

Requires Extended mode.

See also: CreatePhysicsBallJoint, CreatePhysicsHingeJoint, CreatePhysicsSliderJoint, CreatePhysicsDistanceJoint, CreatePhysicsFixedJoint, FreePhysicsBody.

Example

; FreePhysicsJoint 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,-8

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 for the cut arm to land on
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)

; Blue static anchor block near the top of the scene
anchor=CreateCube()
ScaleEntity anchor,0.25,0.25,0.25
PositionEntity anchor,0,4,0,True
EntityColor anchor,80,160,255
anchor_body=CreatePhysicsBody(world,anchor,PHYSICS_STATIC)
anchor_shape=PhysicsBodyBox(anchor_body,0.5,0.5,0.5,0)

; Orange pendulum arm hinged to the anchor
arm=CreateCube()
ScaleEntity arm,0.25,1,0.25
PositionEntity arm,0,2.75,0,True
EntityColor arm,255,120,70
arm_body=CreatePhysicsBody(world,arm,PHYSICS_DYNAMIC)
arm_shape=PhysicsBodyBox(arm_body,0.5,2,0.5,1)
hinge=CreatePhysicsHingeJoint(anchor_body,arm_body,0,3.75,0,0,0,1)

; Start the pendulum swinging
PhysicsBodyImpulse arm_body,1.5,0,0

While Not KeyDown(1)

    ; Space cuts the joint, or rebuilds the pendulum after a cut
    If KeyHit(57)
        If hinge<>0
            ; Free the joint - the arm drops away from the anchor
            FreePhysicsJoint hinge
            hinge=0
        Else
            ; Rebuild the arm body and re-hinge it to the anchor
            FreePhysicsBody arm_body
            PositionEntity arm,0,2.75,0,True
            RotateEntity arm,0,0,0
            arm_body=CreatePhysicsBody(world,arm,PHYSICS_DYNAMIC)
            arm_shape=PhysicsBodyBox(arm_body,0.5,2,0.5,1)
            hinge=CreatePhysicsHingeJoint(anchor_body,arm_body,0,3.75,0,0,0,1)
            PhysicsBodyImpulse arm_body,1.5,0,0
        EndIf
    EndIf

    ; Advance the Box3D simulation by one 60 Hz step
    StepPhysics world,1.0/60.0,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,"Arrow keys: move camera   Space: cut / rebuild joint   Esc: exit"
    If hinge<>0
        Text 0,20,"Hinge joint handle: "+hinge+"   (swinging)"
    Else
        Text 0,20,"Joint freed - the arm falls under gravity"
    EndIf

    Flip

Wend

FreePhysicsWorld world
FreeEntity arm
FreeEntity anchor
FreeEntity ground
End

Index