{"id":13744150,"url":"https://github.com/mziwisky/bullet-ane","last_synced_at":"2025-04-15T18:03:26.339Z","repository":{"id":10451700,"uuid":"12621326","full_name":"mziwisky/bullet-ane","owner":"mziwisky","description":"Adobe AIR native extension for the Bullet physics simulation library","archived":false,"fork":false,"pushed_at":"2015-08-25T05:30:34.000Z","size":19906,"stargazers_count":40,"open_issues_count":1,"forks_count":10,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-15T18:03:13.339Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"ActionScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mziwisky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-09-05T15:28:19.000Z","updated_at":"2019-06-19T03:04:12.000Z","dependencies_parsed_at":"2022-09-22T19:24:49.891Z","dependency_job_id":null,"html_url":"https://github.com/mziwisky/bullet-ane","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mziwisky%2Fbullet-ane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mziwisky%2Fbullet-ane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mziwisky%2Fbullet-ane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mziwisky%2Fbullet-ane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mziwisky","download_url":"https://codeload.github.com/mziwisky/bullet-ane/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249125958,"owners_count":21216705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T05:01:03.992Z","updated_at":"2025-04-15T18:03:26.307Z","avatar_url":"https://github.com/mziwisky.png","language":"ActionScript","funding_links":[],"categories":["Native Extension","AIR Native Extensions"],"sub_categories":["Multimedia ANE"],"readme":"Bullet.ane\n======\n\nAn Adobe AIR Native Extension for the Bullet Physics Simulation Library\n\nImbue your AIR mobile and desktop apps with the magic of physics!\n\nCompared with AwayPhysics, Bullet.ane increases performance on mobile apps by \nan order of magnitude.  See a video comparison: \n[http://youtu.be/IH4mrUagA74](http://youtu.be/IH4mrUagA74)\n\n\nCurrently written to work with Away3D, but certainly could be made compatible \nwith other Stage3D-based AS3 graphics libraries.\n\nTrue native implementations are built for iOS (7.0 SDK), iOS Simulator, and \nAndroid.  All other platforms (which I think is only desktops now that Android \nis supported, right?) fall back on \n[AwayPhysics](https://github.com/away3d/awayphysics-core-fp11), a pure-AS3 \nimplementation of Bullet, meaning the extension will work on all platforms AIR \nsupports.\n\n---\n\nThe rest of the README:\n\n* Getting Started\n* Building the ANE\n* Comparison to AwayPhysics and Bullet C++ Lib\n\t* Bullet.ane vs. Bullet C++ Lib\n\t* Bullet.ane vs. AwayPhysics\n\t* Nested Meshes\n\t* A Word on Scaling\n* To-do\n* Links\n\n\nGetting Started\n-----\n\nFor convenience, the compiled extension is included in the repository, located \nat `as3/aneBulletTester/ane/Bullet.ane`.  Usage examples can be found in \n`as3/aneBulletTester/src/`.\n\nIf you're already familiar with using ANEs, then go wild.\n\nBut if this is your first ANE experience... To add it to your ActionScript \nMobile project in Flash Builder 4.7 (sorry, I don't know about other IDEs), \nright-click your project and select `Properties`, then click `ActionScript \nBuild Path` on the left side-bar, then `Native Extensions` across the top, \nthen `Add ANE...`\n\nFinally, ensure the extension gets packaged with your debug and release \nbuilds; from the `Properties` window, twist open `ActionScript Build \nPackaging` on the left and select `Apple iOS`, then click `Native Extensions` \nacross the top and ensure that the `Package` checkbox is checked.  Do the same \nwith the `Android` platform.\n\n\nBuilding the ANE\n-----\n\nIf you're the type that's going to build `Bullet.ane` from source, this \nsection should help.  It might not be very complete, so I apologize -- ask on \nGitHub if you need help (github.com/mziwisky/bullet-ane).\n\nFirst off, if you don't have a Mac, I can't help you (yet), because I'm \nbuilding the native iOS library with Xcode.  Also, I rely on Flash Builder for \nthe ActionScript compilation, so I can't help with other IDEs.\n\nOK, you'll need to acquire the following AS3 dependencies:\n\n* [Away3D](https://github.com/away3d/away3d-core-fp11)\n* [AwayPhysics](https://github.com/away3d/awayphysics-core-fp11)\n\n`as3/aneBulletLib` depends on Away3D and `as3/aneBulletDefault` depends on \nboth.  Build those two `aneBullet*` projects.\n\nThen, `cd` to `native/bullet-itself` and run \n`./fetchSourceAndMakeXcodeProjects.bash`.\n\nThen, open `native/ios/BulletANE/BulletANE.xcodeproj` in Xcode and build it \nfor both iOS Device and iPad Simulator.\n\nThen, `cd` back to the top directory and edit the properties in `build.xml` to \naccomodate your system.  Most of it should be alright, but you may need to \nchange `airsdk.dir` and `iossdk.dir`.\n\nFinally, run `ant` in the top directory.\n\nAgain, if anything goes wrong here that you can't figure out on your own, feel \nfree to contact me on GitHub.\n\n\nComparison to AwayPhysics and Bullet C++ Lib\n-----\n\nBullet.ane is certainly inspired by AwayPhysics, but where AwayPhysics methods \ndiffer from their Bullet Lib counterpart, Bullet.ane tends to favor the Bullet \nC++ Lib version over the AwayPhysics version.  This choice was made so that \nthe Bullet Lib documentation, forum posts, etc. are more likely to be accurate \nand helpful in using Bullet.ane.\n\nFor example, the AwayPhysics method `AWPRigidBody::applyForce()` implicitly \ncalls `AWPRigidBody::activate()` after applying the force.  Bullet Lib's \n`btRigidBody::applyForce()` does not implicitly call \n`btRigidBody::activate()`, and nor does Bullet.ane's `RigidBody::applyForce()` \ncall `RigidBody::activate()`.\n\nThere are, however, a few things I preferred about AwayPhysics' API, so I made \nsome deviations from Bullet Lib in a few spots.\n\nFor example, the `Generic6DofConstraint` constructor takes a position vector \nand rotation vector argument for each of the two involved bodies' frames, \nrather than a transform matrix for each of the frames.\n\nI won't make a comprehensive list here of the differences between Bullet.ane \nand AwayPhysics, but I'll try to note all the differences between the \nsemantics of Bullet.ane and Bullet Lib which might lead to headaches if you \ndon't realize them.  I'll also point out a few ways in which Bullet.ane tends \nto differ from AwayPhysics.\n\n#### Bullet.ane vs. Bullet C++ Lib ####\n\n* The Bullet.ane `DiscreteDynamicsWorld` constructor will create a world with \n  the same default configuration that AwayPhysics uses in its \n`::initWithDbvtBroadphase()` method.  So you don't have to do all the typical \nboilerplate code that Bullet Lib requires.  On the other hand, you don't have \ncontrol over the things that the boilerplate code constructs, like the \nCollisionConfiguration and CollisionDispatcher.\n* The Bullet.ane `DiscreteDynamicsWorld::addRigidBody()` method, when called \n  without the optional `group` and `mask` parameters, defaults to `group=1` \nand `mask=-1`.  This is indeed what Bullet Lib does for dynamic (i.e., \nnon-static \u0026\u0026 non-kinematic) RigidBodies, but not for non-dynamic bodies.  \nBullet.ane does so regardless of the dynamic-ness.\n* The Bullet.ane `BoxShape` takes full-extents as parameters.  The Bullet Lib \n  counterpart takes half-extents.\n\n#### Bullet.ane vs. AwayPhysics ####\n\n* Bullet.ane performs initialization of a `DiscreteDynamicsWorld` within the \n  constructor as opposed to AwayPhysics, which requires a call to \n`AWPDynamicsWorld::initWithDbvtBroadphase()` after construction.\n* AwayPhysics expects any arguments that are rotation vectors to be Euler \n  angles in degrees.  Bullet.ane expects them to be Euler angles in radians.\n* Bullet.ane often expects a `Matrix3D` defining a transform as a method \n  parameter where AwayPhysics would expect a pair of `Vector3D`s defining a \nposition and a rotation.  E.g., in `CompoundShape::addChildShape()`.\n\n#### Nested Meshes ####\n\nHere's what happened.  I was building this app which had an ObjectContainer3D \nhierarchy.  (NOTE: I'm going to talk about some Away3D classes here, like \nObjectContainer3D.  And Mesh.)  Each visible Mesh was a child of one of a set \nof invisible ObjectContainer3Ds, and each of those ObjectContainer3Ds was a \nchild of the Scene3D.  The ObjectContainer3Ds each had a non-identity \ntransform, as did each of the visible Meshes.\n\nI wanted the Meshes to act like physical objects, so I associated each one \nwith a RigidBody, but I did *not* want the ObjectContainer3Ds to be involved \nin the physics.  An Away3D Mesh can have its *local* transform matrix \nmanipulated directly, but not its *scene* transform.  So when I let Bullet \ntake control over the Meshes transforms, it treated them all as direct \nchildren of a single scene, not realizing that their visual representation was \nactually modulated by the transform of their parent ObjectContainer3Ds.  This \ncaused problems such as objects colliding when they were visually very far \napart, e.g., if they each have a local transform of identity, but their \nparents have transforms that are far from each other.\n\nTo reconcile this, the `DiscreteDynamicsWorld` constructor takes a boolean \nparameter, `expectNestedMeshes`, which defaults to `false`.  If it's set to \n`true`, then the scenario I described above is fixed; the ANE uses the inverse \nscene transform of each Mesh's parent to figure out how to set the Mesh's \nlocal transform such that its scene transform correctly matches its Bullet \nworld transform.\n\nMost people won't need to deal with this, because the typical use case will be \nto add Bullet-controlled Meshes directly to the Scene3D, not to parent \ncontainers.\n\n#### A Word on Scaling ####\n\nBy default, the Bullet C++ Lib assumes all units to be SI -- sizes and \npositions are meters, masses are kilograms, time is seconds, etc.  Bullet Lib \nworks best when moving objects are in the size range of 0.05 to 10.0 units \n(meters).  Refer to [the Bullet wiki page on scaling the \nworld](http://www.bulletphysics.org/mediawiki-1.5.8/index.php?title=Scaling_The_World).\n\nAs a convenience, the DiscreteDynamicsWorld constructor takes a `scaling` \nparameter, and the ANE multiplies all user-specified positions and sizes by \n`(1/scaling)` before it passes those values to the Bullet library.\n\nTherefore, 1 Bullet unit equals `scaling` visual (Away3D) units.\n\nThe default `scaling` is 100.  So by default, the ANE will work best when \nmoving objects are created with a size in the range of 5 to 1000.\n\nNote that ONLY sizes and positions get scaled.  In spite of what the referred \nwiki page suggests, we don't scale velocities, torques, etc.  So a scaling of \n100 can be interpreted as follows.  All positions and sizes (both input to and \noutput from the ANE) are in centimeters, but all other units remain SI.  \nTherefore velocities are m/s (not cm/s), accelerations -- in particular \nacceleration due to gravity -- are m/s^2, forces are Newtons, torques are \nNewton-meters, etc. Note that this agrees with the convention that AwayPhysics \nuses (i.e., only scaling distances and sizes).\n\n\nTo-do\n-----\n\nAn abbreviated list of things on the to-do list for the ANE.  Feel free to \ncontribute!\n\n* Native Desktop lib.  Right now it falls back on AwayPhysics, which is \n  awesome, but performs significantly worse than native code.\n* Add support for other Stage3D-based graphics libraries.\n* Maybe make a big start-to-finish build script if enough people are \n  interested in such a thing.\n* Add collision callbacks.\n* More and more API exposure.\n\n\nLinks\n-----\n\n#### Bullet Physics Library ####\n* [Wiki](http://www.bulletphysics.org/mediawiki-1.5.8/index.php/Main_Page)\n* [Forums](http://www.bulletphysics.org/Bullet/phpBB3)\n* [Documentation](http://www.bulletphysics.org/mediawiki-1.5.8/index.php?title=Documentation)\n* [Homepage](http://www.bulletphysics.org/)\n\n#### AIR Native Extensions ####\n* [Nice Adobe \n  reference](http://help.adobe.com/en_US/air/extensions/air_extensions.pdf)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmziwisky%2Fbullet-ane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmziwisky%2Fbullet-ane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmziwisky%2Fbullet-ane/lists"}