Blitz3D+ Command Reference

CollisionZ# ( entity,collision_index )

Parameters

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

Description

Returns the world z coordinate of one of an entity's collisions.

Each UpdateWorld records every collision an entity was involved in during that step; CollisionX, CollisionY and CollisionZ give the exact contact point of collision number collision_index. That is the spot to spawn a dust puff, scrape spark or impact sound so the effect appears right where things actually touched.

The list is rebuilt by every UpdateWorld, so read it after UpdateWorld and before the next one. In debug mode an index outside 1...CountCollisions( entity ) is a runtime error.

See also: CollisionX, CollisionY, CollisionNZ, CountCollisions, CollisionEntity.

Example

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

; A small marker shows the most recent contact point
marker=CreateSphere()
ScaleEntity marker,0.2,0.2,0.2
EntityColor marker,255,255,0
HideEntity marker

; 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

    ; Park the marker on the first contact point
    If CountCollisions(player)>0
        ShowEntity marker
        PositionEntity marker,CollisionX(player,1),CollisionY(player,1),CollisionZ(player,1)
    Else
        HideEntity marker
    EndIf

    RenderWorld

    Text 0,0,"Arrow keys: drive the ball into the walls and crate   Esc: exit"
    ; CollisionZ is the world z coordinate of the contact point (the yellow marker)
    If CountCollisions(player)>0
        Text 0,20,"CollisionZ(player,1) = "+CollisionZ(player,1)
        Text 0,40,"(CollisionX: "+CollisionX(player,1)+"   CollisionY: "+CollisionY(player,1)+")"
        Text 0,60,"Rub along the side wall and watch CollisionZ follow the ball"
    Else
        Text 0,20,"CollisionZ: no collisions this frame - push against something"
    EndIf

    Flip

Wend

End

Index