Blitz3D+ Command Reference

PhysicsBodySphere ( body,diameter#[,density#][,x#][,y#][,z#][,sensor] )

Parameters

body - physics-body handle returned by CreatePhysicsBody

diameter# - full diameter of the sphere in metres (not the radius); must be positive

density# (optional) - mass per cubic metre used to work out the body's mass; 1 (default)

x# (optional) - offset of the sphere centre from the body origin, local X; 0 (default)

y# (optional) - offset along local Y; 0 (default)

z# (optional) - offset along local Z; 0 (default)

sensor (optional) - True makes a non-solid sensor that only reports overlaps; False (default)

Description

Adds a sphere collision shape to a physics body and returns its shape handle.

Spheres are the cheapest and most stable shape - perfect for balls, grenades, boulders and pickups. The size is a full diameter to match visual sizes: a default CreateSphere is 2 units across, so scale it by 0.5 and it lines up with a diameter of 1.

Spheres roll, and keep rolling: on low-friction ground a sphere barely slows down, so give it some PhysicsBodyDamping or raise PhysicsShapeFriction if it should settle. The optional offset places the sphere away from the body origin for compound bodies, and a dynamic body's mass is recalculated from all its shapes' volumes and densities.

With sensor set to True the sphere becomes a non-solid trigger volume reporting overlaps through CountPhysicsSensorEvents. Use the returned handle with PhysicsShapeFriction, PhysicsShapeRestitution, PhysicsShapeFilter and FreePhysicsShape.

Requires Extended mode.

See also: CreatePhysicsBody, PhysicsBodyBox, PhysicsBodyCapsule, PhysicsShapeRestitution, FreePhysicsShape.

Example

; PhysicsBodySphere 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 bouncing ball - diameter is the full visual-style size
diameter#=1
ball=CreateSphere()
ScaleEntity ball,diameter/2,diameter/2,diameter/2
PositionEntity ball,0,3,0,True
EntityColor ball,255,120,70
ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
ball_shape=PhysicsBodySphere(ball_body,diameter,1)
PhysicsShapeRestitution ball_shape,0.7

While Not KeyDown(1)

    ; Keys 1/2/3 rebuild the sphere shape with a new diameter
    new_diameter#=0
    If KeyHit(2) Then new_diameter=0.6
    If KeyHit(3) Then new_diameter=1.0
    If KeyHit(4) Then new_diameter=1.6
    If new_diameter>0
        diameter=new_diameter
        FreePhysicsShape ball_shape
        ball_shape=PhysicsBodySphere(ball_body,diameter,1)
        PhysicsShapeRestitution ball_shape,0.7
        ; Match the visual sphere to the collision diameter
        ScaleEntity ball,diameter/2,diameter/2,diameter/2
    EndIf

    ; Space tosses the ball back up
    If KeyHit(57) Then PhysicsBodyVelocity ball_body,0,6,0

    ; 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: camera   1/2/3: diameter   Space: toss   Esc: exit"
    Text 0,20,"Sphere diameter: "+diameter+" m   handle: "+ball_shape

    Flip

Wend

FreePhysicsWorld world
FreeEntity ball
FreeEntity ground
End

Index