Blitz3D+ Command Reference

CollisionSurface ( entity,collision_index )

Parameters

entity - entity handle
collision_index - index of the collision, from 1 to CountCollisions( entity )

Description

Returns a handle to the surface hit in one of an entity's collisions.

Surface information exists only for ellipsoid-to-polygon collisions (method 2 of the Collisions command), and the surface always belongs to the mesh on the polygon side of the pair - whichever of the two entities that is. Ellipsoid-to-ellipsoid and ellipsoid-to-box collisions have no surface to report and return 0.

The handle works with the usual surface commands: count its triangles with CountTriangles, or pair it with CollisionTriangle and TriangleVertex to inspect the exact polygon touched. Since each surface has one brush, the surface can stand in for a material - gravel here, metal there - when picking footstep sounds.

In debug mode an index outside 1...CountCollisions( entity ) is a runtime error.

See also: CollisionTriangle, CollisionEntity, CountCollisions, GetSurface, Collisions.

Example

; CollisionSurface Example
; ------------------------

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

; Collision type ids
type_player=1
type_scenery=2

; NOTE: fixed overhead camera - the arrow keys steer the PLAYER, not the camera
camera=CreateCamera()
PositionEntity camera,0,13,-13
RotateEntity camera,45,0,0

light=CreateLight()
RotateEntity light,60,30,0

floor=CreatePlane()
EntityColor floor,70,110,70

; The player ball is the collision SOURCE, so it needs an ellipsoid radius
player=CreateSphere()
EntityColor player,220,60,60
PositionEntity player,0,1,0
EntityRadius player,1
EntityType player,type_player

; Two walls meeting in a corner, plus a crate
wall1=CreateCube()
ScaleEntity wall1,7,1.5,0.5
PositionEntity wall1,0,1.5,7
EntityColor wall1,150,150,160
EntityType wall1,type_scenery

wall2=CreateCube()
ScaleEntity wall2,0.5,1.5,7
PositionEntity wall2,7,1.5,0
EntityColor wall2,150,150,160
EntityType wall2,type_scenery

crate=CreateCube()
ScaleEntity crate,1.2,1.2,1.2
PositionEntity crate,-4,1.2,3
EntityColor crate,200,160,60
EntityType crate,type_scenery

; Ellipsoid-to-polygon collisions with a sliding response
Collisions type_player,type_scenery,2,2

While Not KeyDown(1)

    ; Arrow keys steer the player ball
    If KeyDown(200) Then MoveEntity player,0,0,0.1
    If KeyDown(208) Then MoveEntity player,0,0,-0.1
    If KeyDown(203) Then MoveEntity player,-0.1,0,0
    If KeyDown(205) Then MoveEntity player,0.1,0,0

    ; UpdateWorld performs the collision checks and the slide response
    UpdateWorld

    RenderWorld

    Text 0,0,"Arrow keys: drive the ball into the walls and crate   Esc: exit"
    ; CollisionSurface returns the surface of the entity that was struck -
    ; compare the handle with each mesh's surface to name it
    If CountCollisions(player)>0
        surf=CollisionSurface(player,1)
        name$="?"
        If surf=GetSurface(wall1,1) Then name$="the back wall's surface"
        If surf=GetSurface(wall2,1) Then name$="the side wall's surface"
        If surf=GetSurface(crate,1) Then name$="the crate's surface"
        Text 0,20,"CollisionSurface(player,1) = "+surf+" ("+name$+")"
    Else
        Text 0,20,"CollisionSurface: no collisions this frame - push against something"
    EndIf

    Flip

Wend

End

Index