GMCollision and GMCollisionReport Objects
These two objects contain data generated by the GMSprite's Collided function. A GMCollision object is returned as the result of collision detection between two GMSprites, and contains data about the collision, if one occurred.
The GMCollisionReport object has its data set when the Collided function is called to check collisions between a GMSprite and a GMSpriteList. Since multiple collisions may occur with the sprites in the GMSpriteList, the GMCollisionReport may contain several GMCollision objects.
Keep in mind that the Collided function can also be used to test proximity of objects (using the "radar" value), and whether proposed moves would cause a collision (using the x and y parameters). If those values are used, the "collisions" reported by GMCollision and GMCollisionReport should be interpreted as potential collisions instead of actual overlapping of the sprites.
GMCollision Functions
Integer value of GMCollision |
x,y |
Angle |
Distance
GMCollisionReport Properties and Functions
Constructor |
Integer value of GMCollisionReport
CollisionCount |
Sprite pointer array |
Collision array
Sample Programs
Two Sprites Colliding |
with Bells and Whistles
BehaviorCycleOnce: handy for explosions
Many Sprites Colliding |
with Bells and Whistles
(the above samples require the files in collisions.zip)
GMCollision
You can directly test the value of a GMCollision object. It evaluates as an integer, and is "True" (non-zero) if there was a collision and "False" (zero) if there was no collision.
These give distance/direction from this sprite's center to other sprite's center. x() returns the difference in x locations. If the other sprite is to the left, x() will be negative. y() returns the difference in y locations. If the other sprite is above this sprite (toward the top of the screen), y() will be negative.
This function uses the x and y values above to compute the angle from this GMSprite's center to the other sprite's center. The angle returned is in radian measure (radians are used by all the standard C math library functions). Because of the orientation of the y-axis, 0 is to the right, and positive is CLOCKWISE! (This is opposite from the typical Cartesian coordinate system.) If you want your angle in degrees instead of radians, multiply the result of this function by 180/PI (57.3) to convert.
This function returns distance between the centers of the two
sprites. Since GMSprites are rectangular, not
circular, this measurement is somewhat ambiguous. Repeated
calls to this function this may be useful to tell if two
GMSprites are getting closer or farther apart.
GMCollisionReport
Constructor
GMCollisionReport[(int MaximumCollisions)];
A GMCollisionReport contains two fixed-size arrays (the sizes are static for speed issues). Therefore there is a limit to the number of simultaneous collisions that can be reported by this object. The constructor initializes report arrays to 16 collisions maximum. If the GMSprite's Collided function detects 16 collisions, it stops looking through the GMSpriteList for any more, and only those first 16 collisions are reported back.
When creating the GMCollisionReport object that you will send to the Collided function you can specify a larger or smaller number of maximum collisions if you'd prefer not to use the default of 16.
GMCollisionReport evaluates as an integer and returns the number of collisions that were detected. If there were no collisions, GMCollisionReport evaluates to 0 (or False!). This is the same value that is returned by the CollisionCount function.
This is an alternate and more explicit way to check how many collisions were detected between the GMSprite and GMSpriteList.
This is an array of GMSprite pointers. If collisions were detected, a pointer to each GMSprite from the GMSpriteList that collided will be put in this array. Array elements are only valid from 0 to CollisionCount()-1. If you use a value from this array without first checking CollisionCount, you are on your own (your program may crash!).
This is an array of GMCollision objects. If collisions were detected, a GMCollision object is stored in this array for each of those collisions. Array elements are only valid from 0 to CollisionCount()-1. Don't use values from this array without first checking CollisionCount!
The Sprite and Collision arrays have corresponding parallel data. Sprite[0] is the pointer to the GMSprite for which the collision data is stored in Collision[0], and so on.