physics collision documentation update

Physics
#1

hi,

* in collision documentation (https://docs.coronalabs.com/api/event/collision/index.html) it is written:

[lua]-- Local collision handling
local function onLocalCollision( self, event )[/lua]

which does not work but:

[lua]-- Local collision handling
local function onLocalCollision( event )[/lua]

works.

EDITED: 

I was wrong. There are function and object listener and both work. Just different syntax.

* function listener:

local function onLocalCollision_1 ( event )

object:addEventListener( “collision”, onLocalCollision_1 )

* object listener:

local function onLocalCollision_2 ( self, event )

object.collision = onLocalCollision_2

object:addEventListener( “collision”, object)

* second is that mapping (from same documentation) is not correct:

[lua]local physics = require(“physics”)

physics.start()

physics.setGravity(0, 0)

local wall = display.newRect( 100, 200, 300, 10 )

physics.addBody(wall, “static”, {density = 1.0, friction = 0, bounce = 0, isSensor = false})

– create a ball and set it in motion

ball = display.newCircle( 80, 130, 15 )

physics.addBody(ball, “dynamic”, {density = 1.0, friction = 0.0, bounce = 0.5, isSensor = false, radius = 15} )

ball.name = “my ball”

ball.isBullet = true

ball:setLinearVelocity( 0, 50 )

– Local collision handling

local function onLocalCollision( event )

    print( “LC” )

    print( event.target.name )        --the first object in the collision              >>  prints: "my ball"

    print( event.other.name )         --the second object in the collision             >>  prints: nil

end

ball:addEventListener( “collision”, onLocalCollision )

– Global collision handling

local function onGlobalCollision( event )

    print( “GC” )

    print( event.object1.name )       --the first object in the collision              >>  prints: nil

    print( event.object2.name )       --the second object in the collision             >>  prints: "my ball"

end

Runtime:addEventListener( “collision”, onGlobalCollision )

[/lua]

so mapping is done: target <–> object 2 ,  other <–> object 1

What is happening here ? (doc. error or …)

#2

Hi @rajkocalic,

I’m 99.99% sure the documentation is correct. I’ve tested it – and used it as written – hundreds of times. :slight_smile:

The line that’s missing in the above example should be between lines 22 and 23:

[lua]

ball.collision = onLocalCollision

[/lua]

Brent

#3

Hi @rajkocalic,

Well, generally you wouldn’t need to use both types of collision handling (“global” and “local” combined). Have you read about what scenarios are best suited toward either type and how to choose which one to use?

Brent

#4

Hi Brent,

ty for reply. I made changes to code (my build is 2015.2779):

[lua]local physics = require(“physics”)

physics.start()

physics.setGravity(0, 0)

local wall = display.newRect( 100, 200, 300, 10 )

physics.addBody(wall, “static”, {density = 1.0, friction = 0, bounce = 0, isSensor = false})

– create a ball and set it in motion

ball = display.newCircle( 80, 130, 15 )

physics.addBody(ball, “dynamic”, {density = 1.0, friction = 0.0, bounce = 0.5, isSensor = false, radius = 15} )

ball.name = “my ball”

ball.isBullet = true

ball:setLinearVelocity( 0, 50 )

– Local collision handling

local function onLocalCollision( self, event )

    print( “LC” )

    print( event.target.name )        --the first object in the collision

    print( event.other.name )         --the second object in the collision

end

ball.collision = onLocalCollision

ball:addEventListener( “collision”, ball )

– Global collision handling

local function onGlobalCollision( event )

    print( “GC” )

    print( event.object1.name )       --the first object in the collision

    print( event.object2.name )       --the second object in the collision

end

Runtime:addEventListener( “collision”, onGlobalCollision )

[/lua]

Simulator output (copy->paste):

LC

my ball

nil

GC

nil

my ball

LC

my ball

nil

GC

nil

my ball

  1. code changed to

[lua]local physics = require(“physics”)

physics.start()

physics.setGravity(0, 0)

local wall = display.newRect( 100, 200, 300, 10 )

physics.addBody(wall, “static”, {density = 1.0, friction = 0, bounce = 0, isSensor = false})

– create a ball and set it in motion

ball = display.newCircle( 80, 130, 15 )

physics.addBody(ball, “dynamic”, {density = 1.0, friction = 0.0, bounce = 0.5, isSensor = false, radius = 15} )

ball.name = “my ball”

ball.isBullet = true

ball:setLinearVelocity( 0, 50 )

– Local collision handling

local function onLocalCollision( event )

    print( “LC” )

    print( event.target.name )        --the first object in the collision

    print( event.other.name )         --the second object in the collision

end

ball.collision = onLocalCollision

ball:addEventListener( “collision”, onLocalCollision )

– Global collision handling

local function onGlobalCollision( event )

    print( “GC” )

    print( event.object1.name )       --the first object in the collision

    print( event.object2.name )       --the second object in the collision

end

Runtime:addEventListener( “collision”, onGlobalCollision )

[/lua]

Simulator output (copy->paste):

LC

my ball

nil

GC

nil

my ball

LC

my ball

nil

GC

nil

my ball

so both still have same result … kind of confusing :slight_smile: ???

PS i wont use both usually. But since i need to address issue with low speed sticky bounces.(ill use global for that since it is plug and play). And local for rest of composer scenes which use Box2D engine.  

#5

the two different forms of the function are ok - just depends whether you add the listener as an object or function.

in a local listener event.target is the object that you attached the listener to, event.other is the other

in a global listener there is no guarantee what order the two objects will be passed

hth

#6

So documentation is wrong when it maps:

target <-> object1

other <-> object2

?

if you look at:

https://docs.coronalabs.com/api/event/collision/object1.html

“For local collision handling, this property is represented as event.target.”

#7

i think they’re just trying to tell you that in local listener you get target/other, and in global you get object1/object2 – just to point out difference in property names, not that there is a direct correspondence in their order.  (you could read the box2d source and figure out that the first added body is likely to be the first reported in a global listener – but the api doesn’t guarantee it, so could break on revision, so best to treat as unordered)

#8

ty davebollinger,

I did not read Box2D source or documentation (did not think it was necessary).

Man, I dont assume things, because then programs crash. This assuming can go on and we can say that target and other are not guarantied then and so on. And all of sudden you have 2-3-4 nested if-s and whole thing gets crazy.

I think that is quite important thing to mention(if you cant guarantee something) in documentation.

Object1 documentation said (quote) : "For local collision handling, this property is represented as event.target."

So i want to help and fix this for future people that will come to this point. And i need to know how to approach this. It is very important for me. Can cause crash in program easy.

This then further raises question if documentation can be trusted.

#9

Hi @Rajko,

Yes, as @davebollinger says, the documentation is correct and we’re just making it clear how the object(s) are referenced between “local” vs. “global” collision handlers. Although I didn’t write all of the current documentation, I am currently responsible for maintaining it and checking that it’s correct. Also, physics is of particular interest to me, but I don’t see that the documentation on this point is incorrect or misleading (otherwise I would have fixed it before now).

That being said, why is your program crashing when you use one method instead of the other?

Best regards,

Brent

#10

Sry man i am not here to chit-chat. I wanted to help fix misleading issues (possible bugs) and dont want to play this broken phone thing any more.

You can mark this as you want… solved or anything…

have nice day.

#11

Hi @rajkocalic,

I’m 99.99% sure the documentation is correct. I’ve tested it – and used it as written – hundreds of times. :slight_smile:

The line that’s missing in the above example should be between lines 22 and 23:

[lua]

ball.collision = onLocalCollision

[/lua]

Brent

#12

Hi @rajkocalic,

Well, generally you wouldn’t need to use both types of collision handling (“global” and “local” combined). Have you read about what scenarios are best suited toward either type and how to choose which one to use?

Brent

#13

Hi Brent,

ty for reply. I made changes to code (my build is 2015.2779):

[lua]local physics = require(“physics”)

physics.start()

physics.setGravity(0, 0)

local wall = display.newRect( 100, 200, 300, 10 )

physics.addBody(wall, “static”, {density = 1.0, friction = 0, bounce = 0, isSensor = false})

– create a ball and set it in motion

ball = display.newCircle( 80, 130, 15 )

physics.addBody(ball, “dynamic”, {density = 1.0, friction = 0.0, bounce = 0.5, isSensor = false, radius = 15} )

ball.name = “my ball”

ball.isBullet = true

ball:setLinearVelocity( 0, 50 )

– Local collision handling

local function onLocalCollision( self, event )

    print( “LC” )

    print( event.target.name )        --the first object in the collision

    print( event.other.name )         --the second object in the collision

end

ball.collision = onLocalCollision

ball:addEventListener( “collision”, ball )

– Global collision handling

local function onGlobalCollision( event )

    print( “GC” )

    print( event.object1.name )       --the first object in the collision

    print( event.object2.name )       --the second object in the collision

end

Runtime:addEventListener( “collision”, onGlobalCollision )

[/lua]

Simulator output (copy->paste):

LC

my ball

nil

GC

nil

my ball

LC

my ball

nil

GC

nil

my ball

  1. code changed to

[lua]local physics = require(“physics”)

physics.start()

physics.setGravity(0, 0)

local wall = display.newRect( 100, 200, 300, 10 )

physics.addBody(wall, “static”, {density = 1.0, friction = 0, bounce = 0, isSensor = false})

– create a ball and set it in motion

ball = display.newCircle( 80, 130, 15 )

physics.addBody(ball, “dynamic”, {density = 1.0, friction = 0.0, bounce = 0.5, isSensor = false, radius = 15} )

ball.name = “my ball”

ball.isBullet = true

ball:setLinearVelocity( 0, 50 )

– Local collision handling

local function onLocalCollision( event )

    print( “LC” )

    print( event.target.name )        --the first object in the collision

    print( event.other.name )         --the second object in the collision

end

ball.collision = onLocalCollision

ball:addEventListener( “collision”, onLocalCollision )

– Global collision handling

local function onGlobalCollision( event )

    print( “GC” )

    print( event.object1.name )       --the first object in the collision

    print( event.object2.name )       --the second object in the collision

end

Runtime:addEventListener( “collision”, onGlobalCollision )

[/lua]

Simulator output (copy->paste):

LC

my ball

nil

GC

nil

my ball

LC

my ball

nil

GC

nil

my ball

so both still have same result … kind of confusing :slight_smile: ???

PS i wont use both usually. But since i need to address issue with low speed sticky bounces.(ill use global for that since it is plug and play). And local for rest of composer scenes which use Box2D engine.  

#14

the two different forms of the function are ok - just depends whether you add the listener as an object or function.

in a local listener event.target is the object that you attached the listener to, event.other is the other

in a global listener there is no guarantee what order the two objects will be passed

hth

#15

So documentation is wrong when it maps:

target <-> object1

other <-> object2

?

if you look at:

https://docs.coronalabs.com/api/event/collision/object1.html

“For local collision handling, this property is represented as event.target.”

#16

i think they’re just trying to tell you that in local listener you get target/other, and in global you get object1/object2 – just to point out difference in property names, not that there is a direct correspondence in their order.  (you could read the box2d source and figure out that the first added body is likely to be the first reported in a global listener – but the api doesn’t guarantee it, so could break on revision, so best to treat as unordered)

#17

ty davebollinger,

I did not read Box2D source or documentation (did not think it was necessary).

Man, I dont assume things, because then programs crash. This assuming can go on and we can say that target and other are not guarantied then and so on. And all of sudden you have 2-3-4 nested if-s and whole thing gets crazy.

I think that is quite important thing to mention(if you cant guarantee something) in documentation.

Object1 documentation said (quote) : "For local collision handling, this property is represented as event.target."

So i want to help and fix this for future people that will come to this point. And i need to know how to approach this. It is very important for me. Can cause crash in program easy.

This then further raises question if documentation can be trusted.

#18

Hi @Rajko,

Yes, as @davebollinger says, the documentation is correct and we’re just making it clear how the object(s) are referenced between “local” vs. “global” collision handlers. Although I didn’t write all of the current documentation, I am currently responsible for maintaining it and checking that it’s correct. Also, physics is of particular interest to me, but I don’t see that the documentation on this point is incorrect or misleading (otherwise I would have fixed it before now).

That being said, why is your program crashing when you use one method instead of the other?

Best regards,

Brent

#19

Sry man i am not here to chit-chat. I wanted to help fix misleading issues (possible bugs) and dont want to play this broken phone thing any more.

You can mark this as you want… solved or anything…

have nice day.