Blitz3D+ Command Reference

PhysicsShapeFilter shape,category_bits,mask_bits[,group]

Parameters

shape - physics-shape handle returned by a shape command such as PhysicsBodyBox

category_bits - bit flags saying what this shape is; must not be zero

mask_bits - bit flags saying which categories this shape collides with

group (optional) - collision group override; 0 (default) means no group

Description

Sets a shape's collision category, mask and group.

Filters decide who collides with whom. Two shapes collide only when each one's mask accepts the other's category. Give players category 1, enemies category 2 and player bullets category 4, then leave bit 4 out of the player's mask, and players can never be hit by their own bullets. New shapes have every bit set, so everything collides until you say otherwise. Blitz integers give you 32 usable bits.

The group is a shortcut that overrides the bit test: shapes sharing the same positive group always collide, and shapes sharing the same negative group never collide. The classic trick is giving all the pieces of one ragdoll a unique negative group so it cannot tangle with itself.

Changes apply immediately, including to contacts that already exist, and filters govern sensor overlaps as well. They do not hide shapes from PhysicsRayCast or PhysicsSphereCast, which query everything.

Requires Extended mode.

See also: PhysicsShapeFriction, PhysicsShapeRestitution, PhysicsBodyBox, CountPhysicsContacts.

Example

; PhysicsShapeFilter Example
; --------------------------
; Requires Extended mode.

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

Const PHYSICS_STATIC=0
Const PHYSICS_DYNAMIC=2
Const GROUND_CATEGORY=1
Const BALL_CATEGORY=2

camera=CreateCamera()
PositionEntity camera,0,3,-6

light=CreateLight()
RotateEntity light,45,-30,0
AmbientLight 50,50,50

world=CreatePhysicsWorld()
PhysicsGravity world,0,-9.81,0

; Static ground slab in collision category 1
ground=CreateCube()
ScaleEntity ground,4,0.5,4
PositionEntity ground,0,-0.5,5,True
EntityColor ground,80,160,255
ground_body=CreatePhysicsBody(world,ground,PHYSICS_STATIC)
ground_shape=PhysicsBodyBox(ground_body,8,1,8,0)
PhysicsShapeFilter ground_shape,GROUND_CATEGORY,-1,0

; A bouncy ball in collision category 2
ball=CreateSphere(16)
ScaleEntity ball,0.5,0.5,0.5
PositionEntity ball,0,4,5,True
EntityColor ball,255,120,70
ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
ball_shape=PhysicsBodySphere(ball_body,1,1)
PhysicsShapeRestitution ball_shape,0.7

mask=-1

While Not KeyDown(1)

    ; Space toggles the mask: -1 collides with everything, 2 ignores the ground
    If KeyHit(57)
        If mask=-1 Then mask=BALL_CATEGORY Else mask=-1
    EndIf

    ; Apply the current category and mask to the ball's shape
    PhysicsShapeFilter ball_shape,BALL_CATEGORY,mask,0

    StepPhysics world,1.0/60.0,4

    ; Re-drop the ball after it falls through the ground
    If EntityY(ball,True)<-6
        FreePhysicsBody ball_body
        PositionEntity ball,0,4,5,True
        ball_body=CreatePhysicsBody(world,ball,PHYSICS_DYNAMIC)
        ball_shape=PhysicsBodySphere(ball_body,1,1)
        PhysicsShapeRestitution ball_shape,0.7
    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,"Space: toggle the ball's collision mask   Arrows: camera   Esc: exit"
    Text 0,20,"PhysicsShapeFilter ball_shape,"+BALL_CATEGORY+","+mask+",0"
    Text 0,40,"Mask -1 bounces on the ground; mask 2 falls straight through it"

    Flip

Wend

FreePhysicsWorld world
End

Index