collision

Overview

Used in conjunction with the physics library. Physics engine collision events are exposed through the Corona event listener model with the event name of "collision". In addition to standard collision events, Corona offers preCollision and postCollision events.

Object References

Depending on whether collisions are detected locally or globally, references to the objects involved will vary. For more information about these two collision handling methods, see the Collision Detection guide.

Please compare these two example functions for reference variations:

-- Local collision handling
local function onLocalCollision( self, event )
    print( event.target )        --the first object in the collision
    print( event.other )         --the second object in the collision
    print( event.selfElement )   --the element (number) of the first object which was hit in the collision
    print( event.otherElement )  --the element (number) of the second object which was hit in the collision
end
object.collision = onLocalCollision
object:addEventListener( "collision" )

-- Global collision handling
local function onGlobalCollision( event )
    print( event.object1 )       --the first object in the collision
    print( event.object2 )       --the second object in the collision
    print( event.element1 )      --the element (number) of the first object which was hit in the collision
    print( event.element2 )      --the element (number) of the second object which was hit in the collision
end
Runtime:addEventListener( "collision", onGlobalCollision )

Gotchas

• During the "ended" phase, the event.x and event.y positions are always zero. This is a Box2D limitation.

• When a collision involves a circle and the collision result is returned in local space (see physics.setReportCollisionsInContentCoordinates()), the local space position of the collision is always 0,0. This is a Box2D limitation.

• Currently, the Box2D physics engine is liable to crash during a collision if Corona code attempts to modify objects still involved in the collision. This is because Box2D is still working out the iterated mathematics on these objects. Please see the Collision Detection guide for a list of functions and properties that are subject to this rule.

Properties