Notes for upgrading to Crafty 0.9.0
This version of Crafty contains a greater than normal number of breaking changes. The goal of this page is to make upgrading less painful.
Prior versions of Crafty used an event called EnterFrame to drive updates that needed to occur once per frame. This is now almost entirely replaced by the UpdateFrame event internally.
Crafty will now fire three frame-related events: EnterFrame, UpdateFrame, and ExitFrame. If you've previously bound to the EnterFrame event, it will still be fired, but will always be before Crafty's own events (such as those used by motion or animation components.)
It's probably better to simply move any uses of EnterFrame to UpdateFrame unless you need a guarantee that they fire before or after some internal events. For instance the control system does still use EnterFrame, since we want the affects of user input to be processed before any motion occurs.
The Motion component (and components that depend on it, such as Multiway) previously fired a Moved event once the object had been moved. This was in addition to the Move event fired by the 2D component, and had a slightly different syntax.
If you were previously binding to the Moved event, you'll need to migrate to Move instead. The key differences between the two events:
- The argument to
Movedwas an object containing the axis as a string ('x'or'y') and the previous position on that axis - The argument to
Moveis an object containing the old position of the entity, with both_xand_yproperties.
A second change is that the Motion component now sets an entities x/y position in one fell swoop, instead of updating the x and y coordinates separately -- this generates a single Move event, and cascades the motion of any attached entities in one pass instead of two. Because of this, you need to be aware that:
- Previously, simple collision detection which simply "unmoved" the object would never-the-less allow an entity to slide along a wall when moving diagonally. This is because the motion happened in two steps, and only the axis moving into the wall would be cancelled.
- Now, because the motion is accomplished in one step, you'll need to do some sort of additional work to preserve that behavior. If both entities have
Collisionyou can use theoverlap/nx/nyproperties of the SAT collision results to accomplish this.
A third change is to angular motion: the Rotate event now only passes the rotation amount in degrees, rather than a complicated object that contained pre-calculated but redundant information.
When reporting a SAT collision, Crafty provides information about the minimum translation vector (MVT) necessary to resolve a collision. Previously, the normal of the MVT was reported as an object attached to the results. (For whatever reason, this was never part of the official documentation, but was mentioned indirectly in some places.) In the new scheme, the normal components are top level properties of the collision object:
Old style: {obj:entity, normal: {x: 1, y: 0}, overlap: 10}
New style: {obj:entity, nx: 1, ny: 0, overlap: 10}
Sometimes it might be necessary to use Crafty.map.search instead of the methods provided by Collision. This previously supported a boolean flag that controlled whether the search "filtered" the results. In this context, filtering means:
- Entities are guaranteed to overlap with the passed region, rather than just being candidates.
- Any duplicate entries are removed from the list.
Now search only supports the filtered version -- if unfiltered search is necessary, just use unfilteredSearch instead. (The likely reason to use unfiltered search is because you need to do a more complicated intersection check than simple overlap -- that's what the Collision component does, for instance.)