| MovieClip.hitTest( ) Method | Flash 5 |
| check if a point or another clip intercept a given clip |
The horizontal coordinate of the point to test.
The vertical coordinate of the point to test.
An optional Boolean value indicating whether the function should test for intersection of the point (x, y) against the bounding box of mc (false) or against the actual pixels of mc (true). Defaults to false if not supplied. Note that shapeFlag can be used only with the x and y argument syntax, not with the target argument. It is meaningful only when mc has an irregular contour or a hole like a doughnut; it has no impact if mc is a solid rectangular object.
A string indicating the path to the movie clip to test for collision with mc. Because movie clip references are converted to paths when used in a string context, target can also be a movie clip object reference, as in mc.hitTest(ball) versus mc.hitTest("ball").
A Boolean indicating the result of the collision-detection test. The result is true under any of the following circumstances:
The point (x,y) on the main Stage intersects with any occupied pixel of mc. An occupied pixel is one that contains a visual element, such as a shape or text.
The shapeFlag property is false and the point (x,y) on the main Stage intersects with any pixel in the bounding box of mc. The bounding box of mc is the smallest rectangle that can encompass every occupied pixel of mc (as returned by MovieClip.getBounds( )).
Any pixel in the bounding box of target intersects any pixel in the bounding box of mc.
The result is false under any of the following circumstances:
The shapeFlag property is true and the point (x,y) on the main Stage does not intersect with any occupied pixel of mc. An occupied pixel is one that contains a visual element, such as a shape or text.
The point (x,y) on the main Stage does not intersect with any pixel in the bounding box of mc. The bounding box of mc is the smallest rectangle that can encompass every occupied pixel of mc.
No pixels in the bounding box of target intersect with any pixel in the bounding box of mc.
The hitTest( ) method is used to determine whether a movie clip or specific point intersects with (i.e., "hits") mc.
When checking to see if a point intersects mc, we provide hitTest( ) with the x and y coordinates of the point to check (relative to the main Stage). We can also provide the optional shapeFlag argument, which indicates whether the collision test should use the actual pixels of mc or just mc's bounding box (the smallest rectangle that can encompass every occupied pixel of mc). Checking the actual pixels of mc allows us to determine whether the point (x, y) is an occupied pixel inside the contour of mc, not merely whether it is any point inside mc's bounding box.
When we're checking to see if a movie clip intersects mc, we provide hitTest( ) with the target argument specifying the clip to check against. Collision detection between target and mc always uses the bounding boxes of the clips; hitTest( ) does not support pixel-perfect clip-versus-clip detection. Manual pixel-perfect collision-detection routines can be difficult to create and processor-intensive to run. In many situations—for example, a simple spaceship game—it's common practice to detect against a bounding circle rather than exact pixels (see the following Example).
The return value of hitTest( ) is unaffected by the _visible or _alpha properties, which can hide a movie clip from view. An invisible movie clip can still be hit-tested against a point or another invisible clip.
Note that collision is always tested relative to the location of mc on the main Stage of the Player. Therefore, when hitTest( ) is used with a single point, the arguments x and y should always describe a point using Stage coordinates. See MovieClip.localToGlobal for information on converting clip coordinates to Stage coordinates. In clip-versus-clip detection, the coordinates of clips on different timelines are automatically converted to global (i.e., Stage) coordinates.
This example shows how to detect the intersection of two circles manually, without using hitTest( ):
// Check the distance between two circular clips on both axes.
var deltaX = clip1._x - clip2._x; // Horizontal distance
var deltaY = clip1._y - clip2._y; // Vertical distance
// Store the radius of each circle in a convenient property.
var radius1 = clip1._width / 2;
var radius2 = clip2._width / 2;
// If the distance between the circles' centers squared is less
// than or equal to the total length of the two radii squared,
// an intersection occurs.
if ((deltaX * deltaX) + (deltaY * deltaY)
<= (radius1 + radius2) * (radius1 + radius2)) {
trace("intersecting");
} else {
trace("not intersecting");
}
Here we check whether paddle_mc intersects ball_mc using hitTest( ):
if (paddle_mc.hitTest("ball_mc")) {
trace("The paddle hit the ball.");
}
Here we check whether the mouse pointer is over an occupied pixel within house_mc's contour. Notice that the coordinates of the pointer are given in relation to _root (the main Stage). Gaps in a movie clip are detectable when shapeFlag is true; for example, if the house_mc clip uses empty space to represent its windows, then hitTest( ) will return false when the pointer is over a window:
if (house_mc.hitTest(_root._xmouse, _root._ymouse, true)) {
trace("You're pointing to the house.");
}
MovieClip.getBounds( ), MovieClip.localToGlobal( )
