Blitz3D+ Command Reference

PhysicsBodyBox ( body,width#,height#,depth#[,density#][,x#][,y#][,z#][,sensor] )

Parameters

body - physics-body handle returned by CreatePhysicsBody

width# - full size of the box along its local X axis, in metres; must be positive

height# - full size along the local Y axis

depth# - full size along the local Z axis

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

x# (optional) - offset of the box 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 box collision shape to a physics body and returns its shape handle.

The workhorse shape for crates, platforms and ground slabs. Sizes are full dimensions, like the visual size of a scaled cube - a CreateCube entity scaled by 0.5,0.5,0.5 matches a 1,1,1 box shape. Collision is independent of the entity's scale: rescaling the mesh later does not change the shape, and a shape's size cannot be edited - free it and attach a new one.

The optional offset moves the box away from the body origin, which lets you build compound bodies: attach several offset boxes (and spheres, capsules or hulls) to one body for a tank hull plus turret, or a table with legs. A dynamic body's mass is recalculated from the volumes and densities of all its shapes whenever one is added or removed.

With sensor set to True the box pushes nothing and stops nothing - it just reports overlap events for triggers and pickup zones, read with CountPhysicsSensorEvents. Use the returned shape handle with PhysicsShapeFriction, PhysicsShapeRestitution, PhysicsShapeFilter and FreePhysicsShape.

Requires Extended mode.

See also: CreatePhysicsBody, PhysicsBodySphere, PhysicsBodyCapsule, PhysicsBodyHull, PhysicsShapeFriction, FreePhysicsShape.

Example

; PhysicsBodyBox 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 - dimensions are full metres
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 tumbling crate with a matching box shape
size#=1
crate=CreateCube()
ScaleEntity crate,size/2,size/2,size/2
PositionEntity crate,0,3,0,True
EntityColor crate,255,120,70
crate_body=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
crate_shape=PhysicsBodyBox(crate_body,size,size,size,1)

While Not KeyDown(1)

    ; Keys 1/2/3 rebuild the box shape with new full dimensions
    new_size#=0
    If KeyHit(2) Then new_size=0.6
    If KeyHit(3) Then new_size=1.0
    If KeyHit(4) Then new_size=1.6
    If new_size>0
        size=new_size
        FreePhysicsShape crate_shape
        crate_shape=PhysicsBodyBox(crate_body,size,size,size,1)
        ; Match the visual cube to the collision size
        ScaleEntity crate,size/2,size/2,size/2
    EndIf

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

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

    ; Respawn the crate if it tumbles off the slab
    If EntityY(crate)<-8
        FreePhysicsBody crate_body
        PositionEntity crate,0,3,0,True
        RotateEntity crate,0,0,0
        crate_body=CreatePhysicsBody(world,crate,PHYSICS_DYNAMIC)
        crate_shape=PhysicsBodyBox(crate_body,size,size,size,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: camera   1/2/3: box size   Space: toss   Esc: exit"
    Text 0,20,"Box shape: "+size+" x "+size+" x "+size+" m   handle: "+crate_shape

    Flip

Wend

FreePhysicsWorld world
FreeEntity crate
FreeEntity ground
End

Index