Blitz3D+ Command Reference

PhysicsBodyHull ( body,entity[,density#][,sensor] )

Parameters

body - physics-body handle returned by CreatePhysicsBody

entity - mesh entity whose vertices are wrapped; needs at least four vertices

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

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

Description

Builds a convex hull collision shape from a mesh entity and returns its shape handle.

Think shrink-wrap: the mesh's vertices, with the entity's current scale applied, are wrapped in the tightest convex shell. That gives dynamic props - rocks, crates, vehicles, furniture - collision that matches their silhouette far better than a plain box, and unlike triangle meshes a hull works on any body type.

Convex means no dents: hollows, handles and archways are filled in. For truly concave level geometry use PhysicsBodyMesh on a static body, or approximate a concave prop by attaching several hulls (or boxes and spheres) to one body. The hull is simplified to at most 64 vertices, so extremely detailed meshes lose a little fidelity.

The geometry is copied when the command runs - editing the mesh or rescaling the entity later does not change the shape. Use the returned handle with PhysicsShapeFriction, PhysicsShapeRestitution, PhysicsShapeFilter and FreePhysicsShape.

Requires Extended mode.

See also: CreatePhysicsBody, PhysicsBodyMesh, PhysicsBodyBox, PhysicsBodyTerrain, FreePhysicsShape.

Example

; PhysicsBodyHull Example
; -----------------------
; Requires Extended mode.

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

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2

SeedRnd MilliSecs()

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 cone dropped at a tilt - no primitive shape matches it
cone=CreateCone(8,True)
ScaleEntity cone,0.8,1.2,0.8
PositionEntity cone,0,3,0,True
RotateEntity cone,0,0,35
EntityColor cone,255,120,70
cone_body=CreatePhysicsBody(world,cone,PHYSICS_DYNAMIC)

; Build a convex hull from the cone mesh's scaled vertices
cone_shape=PhysicsBodyHull(cone_body,cone,1)

While Not KeyDown(1)

    ; Space tosses the cone up with a random tumble
    If KeyHit(57)
        PhysicsBodyVelocity cone_body,0,6,0
        PhysicsBodyAngularVelocity cone_body,Rnd(-3,3),0,Rnd(-3,3)
    EndIf

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

    ; Respawn the cone if it tumbles off the slab
    If EntityY(cone)<-8
        FreePhysicsBody cone_body
        PositionEntity cone,0,3,0,True
        RotateEntity cone,0,0,35
        cone_body=CreatePhysicsBody(world,cone,PHYSICS_DYNAMIC)
        cone_shape=PhysicsBodyHull(cone_body,cone,1)
    EndIf

    ; 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: toss the cone   Esc: exit"
    Text 0,20,"The cone lands on its point or side thanks to its hull shape"

    Flip

Wend

FreePhysicsWorld world
FreeEntity cone
FreeEntity ground
End

Index