After much investigation here, it seems clear that queryAABB(…) functions somewhat differently than described.
To be as precise as my understanding allows, queryAABB does not find bodies that are themselves within the given bounds, it finds the bodies whose AABB rectangles are within the given bounds.
If I understand correctly, AABB rectangles, as generated by Box2D, are attached to every physics body, and apparently don’t just represent the smallest rectangular area that entirely contains the body’s shape, but under certain conditions can represent potential positions of the body, after accounting for rotation and momentum—meaning that the aabb rectangles can sometimes be a good deal larger than the minimum rectangular bounds of the given body.
I think this calls for a tweaking of the documentation on aabb queries. Unless a fuller explanation seems appropriate, I might suggest an overview along the lines of this:
An intentionally low-precision tool for rapidly detecting bodies that might overlap a given area. User must individually examine detected bodies if more certainty is required.
…and the “returns” text might better be something like this:
Returns
array of bodies potentially overlapping supplied bounding box
…and the in-editor tool text might be better as this:
get all bodies potentially overlapping given rect
I know these descriptions might themselves raise more questions than they answer, but if you ask me it’s better to let Codea programmers know up front that the feature is confusing than to let them wander unsuspecting into the same thicket of confusion from which I myself am only now returning…
