Blitz3D+ Command Reference

PhysicsBodyTerrain ( body,entity[,sensor] )

Parameters

body - physics-body handle returned by CreatePhysicsBody; the body must be static

entity - terrain entity created with CreateTerrain or LoadTerrain

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

Description

Builds static height-field collision from a terrain entity and returns its shape handle.

The terrain's height grid and current entity scale are sampled into a Box3D height field, so physics bodies land on the same landscape the player sees. Height fields are much cheaper than an equivalent triangle mesh, making them the right choice for large outdoor ground.

Terrain shapes can only be attached to static bodies - anything else raises a runtime error - and contribute no mass. Terrain holes (TerrainHole) become holes in the collision too, so bodies fall through them just like the player would.

The heights are copied when the command runs. If you later edit the terrain with ModifyTerrain or change its holes, call RefreshPhysicsTerrain to rebuild the collision - it is a separate, explicit step because rebuilding a large height field takes noticeable time.

Requires Extended mode.

See also: CreatePhysicsBody, RefreshPhysicsTerrain, PhysicsBodyMesh, CreateTerrain, ModifyTerrain.

Example

; PhysicsBodyTerrain 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

; Bowl-shaped terrain centred under the camera
terrain=CreateTerrain(8)
ScaleEntity terrain,0.75,2,0.75
PositionEntity terrain,-3,-1,-3,True
For z=0 To 8
    For x=0 To 8
        ModifyTerrain terrain,x,z,0.05+((x-4)*(x-4)+(z-4)*(z-4))*0.0125
    Next
Next

; Build a static height field from the terrain and its scale
terrain_body=CreatePhysicsBody(world,terrain,PHYSICS_STATIC)
terrain_shape=PhysicsBodyTerrain(terrain_body,terrain)

; Orange ball dropped off-centre so it rolls around the bowl
ball=CreateSphere()
ScaleEntity ball,0.5,0.5,0.5
PositionEntity ball,1.5,2,0,True
EntityColor ball,255,120,70
ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
ball_shape=PhysicsBodySphere(ball_body,1,1)
PhysicsShapeRestitution ball_shape,0.4

While Not KeyDown(1)

    ; Space bounces the ball up so it lands in a new hollow
    If KeyHit(57) Then PhysicsBodyImpulse ball_body,0,2,0

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

    ; Respawn the ball if it rolls off the terrain edge
    If EntityY(ball)<-6
        FreePhysicsBody ball_body
        PositionEntity ball,1.5,2,0,True
        ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
        ball_shape=PhysicsBodySphere(ball_body,1,1)
        PhysicsShapeRestitution ball_shape,0.4
    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: bounce the ball   Esc: exit"
    Text 0,20,"The ball rolls on a Box3D height field built from the terrain"

    Flip

Wend

FreePhysicsWorld world
FreeEntity ball
FreeEntity terrain
End

Index