Recently I had a need for shape-based collision detection and decided to write up a class to handle it. As the class developed, I discovered other things that would be nice to have but weren’t available, so I worked it out and added the functionality to my class.
Long story short, it developed into a small package of code I call the Collision Detection Kit. It’s been so useful for me that I’ve decided to put it under an MIT license and share it with all of you.
It uses bitmapdata to find overlapping pixels of display objects. Not a new idea, I realize, but I wrote mine out from scratch anyways to handle things the way I needed them handled. This allowed me to figure out a few other nifty features that I include in the kit. Here are the big ones that me and my beta testers/coworkers have been loving:
Set an alpha threshold so that any pixels on a display object below that alpha won’t be checked for collisions.
Exclude colors and color ranges from collision detection.
The kit can approximate the angle of a collision, allowing you to keep your physics convincing when colliding with odd/organic shapes. It took awhile to figure out a good way of doing this. It’s my favorite part of the kit.
Gives you the pixels that overlap in a collision in stage coordinates, making it easier for you to adjust positions or apply off-center rotation convincingly.
The kit takes nesting into account, so it doesn’t matter where your display objects are on the display list.
Takes transforms into account for individual instances, so things like scaling, rotating, and performing color transforms on your objects are no problem. This includes transformation made to any parent containers!
Can be used with display objects on or off the display list. Works great alongside blitting engines.
Works with all display objects: MovieClips, Sprites, TextFields (very cool), FLVs, etc.
I’ve created pre-compiled examples to show off these features and give you a better idea of what this package is capable of doing. I also have all classes documented, available online and for download (includes some rudimentary source code examples).
Feedback is welcomed! I don’t have a discussion list for this yet, but plan on adding that or a forum later this evening (via Google Code). In the meanwhile, post any questions you might have here. I hope this can help some people out, as it’s helped me a ton!
A new version of the CDK (v1.5) is now available! Links have been updated. I’m thrilled that the CDK has been so useful to so many devs, and I’m glad to finally be pushing out this update based on user feedback. Enjoy!
Hahaha, thanks guys! My babies are in high demand, so might have to put you in a queue. Really, though, glad to hear you all like it! It’s been a busy week for me, but I’m going to get a forum put up for it on Google Code soon in case anyone has any questions and so on.
I’m surprised this hasn’t had even more feedback actually.
It’s great. The only thing I would say so far is find ways to optimise performance, for the amount of objects that were active, it seemed a TAD cpu heavy.
When I’ve got time, I’m going to play around with it, and find ways to implement it.
Yea, rumblesushi, I agree there’s probably room for optimization. It went through several phases of redesign along the way, and a few cheap tricks were incorporated into some of the math to get some small increases in performance. Still, there’s always room for improvement! If you end up doing anything with the package (especially if you rewrite it and get it to perform faster), I’d love to hear about it!
I should note that performance will also depend heavily on what features you’re implementing. Color exclusion is the most CPU-intensive, as the bitmapdata samples taken for comparison have to perform significantly more checks against their pixel information to see if they fall under the color ranges a user has specified.
It wouldn’t hurt to include some source code examples of how to use it, like for the examples or something.
More specifically examples showing how the various features that it has are useful for shaped based collision detection.
Ya I already saw those, they aren’t well very good examples sorry and completly fail to show how the various features are useful for practical shaped based collision detection.
Which is why I was asking for some better examples.
Ahhh, gotcha. Yea, when I wrote those source examples, they were only meant to show rudimentary setup for the classes. As far as how to use the features available, well… that’s kind of up to what the programmer requires. Shape-based collision is useful in a lot of different areas, especially game programming. The features included with the package are demonstrated to show what their function does, not what their function is, as that will be different from project to project.
One example I can think of offhand for the alphaThreshold feature would be when a character dies. In many games, the character will come back to life and be slightly transparent for awhile, signifying that they’re invincible at that time. If you were to set the alphaThreshold property to the alpha of the character while they’re invincible, then any weapons fire or enemies attacking the character would be ignored without having to write further logic to define that condition.
In the end, I think I left out more involved examples like that because I feel it’s up to the programmer to decide what tools are right for each job and recognize when that’s the case. Still, I agree it could help clarify the kit’s usefulness if more complete, practical applications of its features were showcased. I know of a few people working with the kit right now in their own projects, and I am planning to incorporate their examples (along with proper credit given). For that matter, if anyone reading this happens to use the kit, please feel free to contact me and let me know about it.
Hi, tarwin! Thanks for the suggestions. I agree there may be a boost in performance in most cases doing AABB checks on the objects first. Currently, I do perform a check based on regular bounding boxes before ever going pixel-deep. Going AABB instead may save from a few needless checks.
Good call on the getColorBoundsRect! Clearly a method I overlooked. I’ll be sure to try that out, thanks!
EDIT - Actually, now that I’m thinking about it, I don’t think I could utilize getColorBoundsRect. Two reasons that come to me offhand.
Receiving bounds will let me know the excluded color(s) exist, but not if there are other (valid) colors. And finding that out using getColorsBoundRect would still have me doing a ton of looping to account for the rest of the color spectrum.
I need those individual pixel locations when finding the angle of collision.
Still, I’ll mull it over and see if there’s a way I could make use of it to speed things up. And either way, I’ll definitely look into doing an AABB check rather than the current standard bounding box check. Thanks again for the suggestions!
Yea, when I wrote those source examples, they were only meant to show rudimentary setup for the classes. As far as how to use the features available, well… that’s kind of up to what the programmer requires. Shape-based collision is useful in a lot of different areas, especially game programming. The features included with the package are demonstrated to show what their function does, not what their function is, as that will be different from project to project.