An Adobe AIR Native Extension for the Bullet Physics Simulation Library
Imbue your AIR mobile and desktop apps with the magic of physics!
Compared with AwayPhysics, Bullet.ane increases performance on mobile apps by an order of magnitude. See a video comparison: http://youtu.be/IH4mrUagA74
Currently written to work with Away3D, but certainly could be made compatible with other Stage3D-based AS3 graphics libraries.
True native implementations are built for iOS (7.0 SDK), iOS Simulator, and Android. All other platforms (which I think is only desktops now that Android is supported, right?) fall back on AwayPhysics, a pure-AS3 implementation of Bullet, meaning the extension will work on all platforms AIR supports.
The rest of the README:
- Getting Started
- Building the ANE
- Comparison to AwayPhysics and Bullet C++ Lib
- Bullet.ane vs. Bullet C++ Lib
- Bullet.ane vs. AwayPhysics
- Nested Meshes
- A Word on Scaling
For convenience, the compiled extension is included in the repository, located
as3/aneBulletTester/ane/Bullet.ane. Usage examples can be found in
If you're already familiar with using ANEs, then go wild.
But if this is your first ANE experience... To add it to your ActionScript
Mobile project in Flash Builder 4.7 (sorry, I don't know about other IDEs),
right-click your project and select
Properties, then click
ActionScript Build Path on the left side-bar, then
Native Extensions across the top,
Finally, ensure the extension gets packaged with your debug and release
builds; from the
Properties window, twist open
ActionScript Build Packaging on the left and select
Apple iOS, then click
across the top and ensure that the
Package checkbox is checked. Do the same
Building the ANE
If you're the type that's going to build
Bullet.ane from source, this
section should help. It might not be very complete, so I apologize -- ask on
GitHub if you need help (github.com/mziwisky/bullet-ane).
First off, if you don't have a Mac, I can't help you (yet), because I'm building the native iOS library with Xcode. Also, I rely on Flash Builder for the ActionScript compilation, so I can't help with other IDEs.
OK, you'll need to acquire the following AS3 dependencies:
as3/aneBulletLib depends on Away3D and
as3/aneBulletDefault depends on
both. Build those two
native/bullet-itself and run
native/ios/BulletANE/BulletANE.xcodeproj in Xcode and build it
for both iOS Device and iPad Simulator.
cd back to the top directory and edit the properties in
accomodate your system. Most of it should be alright, but you may need to
ant in the top directory.
Again, if anything goes wrong here that you can't figure out on your own, feel free to contact me on GitHub.
Comparison to AwayPhysics and Bullet C++ Lib
Bullet.ane is certainly inspired by AwayPhysics, but where AwayPhysics methods differ from their Bullet Lib counterpart, Bullet.ane tends to favor the Bullet C++ Lib version over the AwayPhysics version. This choice was made so that the Bullet Lib documentation, forum posts, etc. are more likely to be accurate and helpful in using Bullet.ane.
For example, the AwayPhysics method
AWPRigidBody::activate() after applying the force. Bullet Lib's
btRigidBody::applyForce() does not implicitly call
btRigidBody::activate(), and nor does Bullet.ane's
There are, however, a few things I preferred about AwayPhysics' API, so I made some deviations from Bullet Lib in a few spots.
For example, the
Generic6DofConstraint constructor takes a position vector
and rotation vector argument for each of the two involved bodies' frames,
rather than a transform matrix for each of the frames.
I won't make a comprehensive list here of the differences between Bullet.ane and AwayPhysics, but I'll try to note all the differences between the semantics of Bullet.ane and Bullet Lib which might lead to headaches if you don't realize them. I'll also point out a few ways in which Bullet.ane tends to differ from AwayPhysics.
Bullet.ane vs. Bullet C++ Lib
- The Bullet.ane
DiscreteDynamicsWorldconstructor will create a world with the same default configuration that AwayPhysics uses in its
::initWithDbvtBroadphase()method. So you don't have to do all the typical boilerplate code that Bullet Lib requires. On the other hand, you don't have control over the things that the boilerplate code constructs, like the CollisionConfiguration and CollisionDispatcher.
- The Bullet.ane
DiscreteDynamicsWorld::addRigidBody()method, when called without the optional
maskparameters, defaults to
mask=-1. This is indeed what Bullet Lib does for dynamic (i.e., non-static && non-kinematic) RigidBodies, but not for non-dynamic bodies.
Bullet.ane does so regardless of the dynamic-ness.
- The Bullet.ane
BoxShapetakes full-extents as parameters. The Bullet Lib counterpart takes half-extents.
Bullet.ane vs. AwayPhysics
- Bullet.ane performs initialization of a
DiscreteDynamicsWorldwithin the constructor as opposed to AwayPhysics, which requires a call to
- AwayPhysics expects any arguments that are rotation vectors to be Euler angles in degrees. Bullet.ane expects them to be Euler angles in radians.
- Bullet.ane often expects a
Matrix3Ddefining a transform as a method parameter where AwayPhysics would expect a pair of
Vector3Ds defining a position and a rotation. E.g., in
Here's what happened. I was building this app which had an ObjectContainer3D hierarchy. (NOTE: I'm going to talk about some Away3D classes here, like ObjectContainer3D. And Mesh.) Each visible Mesh was a child of one of a set of invisible ObjectContainer3Ds, and each of those ObjectContainer3Ds was a child of the Scene3D. The ObjectContainer3Ds each had a non-identity transform, as did each of the visible Meshes.
I wanted the Meshes to act like physical objects, so I associated each one with a RigidBody, but I did not want the ObjectContainer3Ds to be involved in the physics. An Away3D Mesh can have its local transform matrix manipulated directly, but not its scene transform. So when I let Bullet take control over the Meshes transforms, it treated them all as direct children of a single scene, not realizing that their visual representation was actually modulated by the transform of their parent ObjectContainer3Ds. This caused problems such as objects colliding when they were visually very far apart, e.g., if they each have a local transform of identity, but their parents have transforms that are far from each other.
To reconcile this, the
DiscreteDynamicsWorld constructor takes a boolean
expectNestedMeshes, which defaults to
false. If it's set to
true, then the scenario I described above is fixed; the ANE uses the inverse
scene transform of each Mesh's parent to figure out how to set the Mesh's
local transform such that its scene transform correctly matches its Bullet
Most people won't need to deal with this, because the typical use case will be to add Bullet-controlled Meshes directly to the Scene3D, not to parent containers.
A Word on Scaling
By default, the Bullet C++ Lib assumes all units to be SI -- sizes and positions are meters, masses are kilograms, time is seconds, etc. Bullet Lib works best when moving objects are in the size range of 0.05 to 10.0 units (meters). Refer to the Bullet wiki page on scaling the world.
As a convenience, the DiscreteDynamicsWorld constructor takes a
parameter, and the ANE multiplies all user-specified positions and sizes by
(1/scaling) before it passes those values to the Bullet library.
Therefore, 1 Bullet unit equals
scaling visual (Away3D) units.
scaling is 100. So by default, the ANE will work best when
moving objects are created with a size in the range of 5 to 1000.
Note that ONLY sizes and positions get scaled. In spite of what the referred
wiki page suggests, we don't scale velocities, torques, etc. So a scaling of
100 can be interpreted as follows. All positions and sizes (both input to and
output from the ANE) are in centimeters, but all other units remain SI.
Therefore velocities are m/s (not cm/s), accelerations -- in particular acceleration due to gravity -- are m/s^2, forces are Newtons, torques are Newton-meters, etc. Note that this agrees with the convention that AwayPhysics uses (i.e., only scaling distances and sizes).
An abbreviated list of things on the to-do list for the ANE. Feel free to contribute!
- Native Desktop lib. Right now it falls back on AwayPhysics, which is awesome, but performs significantly worse than native code.
- Add support for other Stage3D-based graphics libraries.
- Maybe make a big start-to-finish build script if enough people are interested in such a thing.
- Add collision callbacks.
- More and more API exposure.