Want more documentation?
Post suggestions or questions on the forums about what
topics you want covered!
Documentation and Demo Source:
API Reference:v0.14.1
v0.13.0
v0.12.1
(Having trouble opening the .chm? Right click on the file, go to properties, and click "Unblock.")
Introduction to BEPUphysics and Physics Simulation
Applying Physics Engines
-Blocks Explode Your Castle
Getting Started
-BasicSetupDemo
-GettingStartedDemo
Internal Multithreading
-MultithreadingDemo
Asynchronous Update
-AsynchronousUpdateDemo
Entity Events
Collision Rules
Joints and Constraints
-Ragdolls Demo
General Documentation:
BEPUphysics uses an overall design scheme as follows:Entities, such as boxes, are contained in a Space. Entities compose all dynamic and nondynamic objects within the world. Interaction Handlers such as Controllers and Constraints manage behavior between Entities.
Updateables provide a framework to perform a wide range of operations at different points of execution (during force computation, before collision detection, at the end of each timestep, and at the end of a frame).
The Toolbox helper class contains miscellaneous tests and functions that can assist with engine interaction.
General Tips:
-Avoid using very large or very small objects. These can cause sometimes noticeable artifacts.
-Avoid large mass ratios. Very heavy objects sitting on top of light objects can be unstable.
-While entity margins are adjustable, avoid extremely small values.
-If something isn't clear, be sure to ask on the forums or let us know!
Have questions that aren't addressed here? Head to the forums or contact us directly. Forums are the preferred method of communication as others may learn from what is posted there. The library comes with full XML documentation for intellisense viewing.
Entities:
All simulated objects fall under the category of Entity. Entities are stored within and updated by their associated Space object.There are currently nine base types of Entity:
Box
Specialized primitive with a mathematical definition, well suited for crate duty.
Capsule
Spherically expanded line segment; a pill.
Cylinder
Mathematically defined object with a height and radius with two circular ends.
Cone
Mathematically defined object with a height and radius with one circular and one single-point end.
Sphere
Simple mathematically defined object with a radius.
Triangle
Three vertices connected by three edges.
MinkowskiSum
Sweeps the two component entities through each other to form a new shape.
ConvexHull
A triangulated exterior shell of a point set.
WrappedBody
An implicit convex hull around a set of shapes.
-Note that while the display graphics of the Cylinder, Capsule, Cone, and Sphere are triangulated, they are considered to have 'perfect' curves during simulation as they are defined through equations instead of a series of triangles.
Each basic type of Entity can be either physically simulated or not. Switching between these states is as simple as calling Entity.makePhysical(float mass) or Entity.makeNonDynamic(). Physical objects respond to collisions and operate based on forces. Nondynamic objects, on the other hand, operate purely on the velocity level. In collisions, they are considered to have infinite inertia.
A special type is CompoundBody; other entities can be added to its listing by using the function addBody(Entity body), or removed by using the removeBody(Entity body) method. When added to a CompoundBody, an Entity's relative position to the CompoundBody and its existing elements becomes fixed and the object will act as a part of the CompoundBody physically. CompoundBodies can be added to other CompoundBodies, allowing for hierarchies of objects.
World and Environment: Space
There needs to be somewhere to put all of the objects to be simulated. This is handled through the Space class.A Space object can be created with no parameters or with a list of entities. To add additional objects after creating the Space, call add(Entity entity). This will place the entity in the list of entities to be updated each frame. Conversely, objects can be removed from the update loop by calling remove(Entity entity). Constraints can be added and removed by using the add(Constraint constraint) and remove(Constraint constraint) functions, respectively.
A raycast against the entire world can be performed by using Space.rayCast; this searches through the broad phase listing and any ray castable containers (such as static triangle groups) within the world.
Additionally, there are a set of important fields contained in a Space's SimulationSettings which can be used to tune the simulation. These range from varying position correction and integration methods to the lower bound on velocity before being clamped to zero. Other collision detection options are also available here, allowing continuous collision detection to be enabled and disabled.
Broad Phases
Broad phases provide a method for determining collision pairs. They can also be queried with bounding shapes for determining objects in an area. Beyond the following, custom broad phases can be derived from the BroadPhase class and used in the space.PersistentUniformGrid
Separates the space into an infinite number of cubes. Objects within these cells are checked only against other entities within the applicable cells. Keeps track of objects through frames and does not rebuild the representation every frame.
BruteForce
Simple pairwise check between entities with no spatial partitioning. Provides acceptable performance only for small (low hundreds or less) numbers of objects.
DynamicBinaryHierarchy
Creates and incrementally maintains a bounding box hierarchy. High update speed and insertion speed; a good fit for most simulations. Used by default.
Broad phases also support methods for getting entities within bounding volumes and raycasting against their contents.
Updateables and Other Frameworks
The engine supports a framework for new types of objects to be maintained by the space. These include Updateables, SolverUpdateables, CombinedUpdateables, and ForceFields. Default subclasses of these are listed below; others can be added externally.Static Triangle Groups : Updateable
An efficient container for complex static triangulated geometry. Can be loaded in based on a mesh. Capable of handling thousands of triangles quickly.
Static Groups : Updateable
Nonmoving elements of the simulation, such as level geometry, can be represented within StaticGroups. The entities added to a StaticGroup will be added into the associated space dynamically as needed (such as when physically simulated bodies approach). With large amounts of geometry, the computational savings can be great. Note that entities added to a StaticGroup need not be added directly to the space; the StaticGroup will handle all of the adding and removing.
Terrain : Updateable
A conceptual subset of static groups, Terrain converts a list of heights into appropriately placed triangles dynamically. As with static groups, the triangles will persist only when necessary. Heights can be modified on the fly, allowing deformability.
Vehicle : CombinedUpdateable
Vehicles are wheeled mechanisms that can be driven around while saying "vroom vrooooom rrrrrrrroooom." They support numerous friction coefficients, braking, acceleration, and tuning variables. In order to get a solid feel for the friction forces of the tires, vehicle force calculation needed to be integrated directly into the solver. Additionally, to update the graphical portion of the vehicle (wheel positions relative to interpolated positions), the end of frame update component of CombinedUpdateable is used. Using the same basis or directly using the SolverUpdateable, other types can be directly tied into the solver. This has the benefit of letting forces and impulses applied during the updates to be 'felt' across the simulation, causing the propagation of momentum rather than stopping nonphysically.
Toolbox
Contains numerous math and geometry tests. Includes methods for:-Segment/Ray - Triangle Tests
-Point - Triangle Tests
-Line - Line Tests
-Triangle - Triangle Tests
-Point - Plane Tests
-General Entity/Entity Tests
-Ray-Entity tests
-Miscellaneous vector, float, list, and quaternion operations
Additionally, the Toolbox contains computational constants epsilon and bigEpsilon, corresponding to floating point tolerances. Default values are epsilon = 1E-7f and bigEpsilon = 1E-5f.
Interaction Handlers
ForceThe Force class and its associated framework was removed in v0.11.0 in favor of the impulse methods. A force can be simulated by applying tiny impulses many times every second. An impulse is essentially a force applied over a very short period of time.
An example of a steady force can be found in the Thruster class of the BEPUphysicsDemos, which acts like the earlier Force class.
Entities have multiple methods and properties, including applyImpulse, angularVelocity, and linearVelocity, that can be used to control their motion. These methods instantly 'push' the entity with an impulse.
Constraint
Constraints can be formed between two Entities. Their parent class, SolverUpdateable, provides a framework for classes which iteratively solve different velocity requirements. There are many kinds of SolverUpdateables, from Vehicles to BallSocketJoints.
A list of constraints can be found in the BEPUphysics.Constraints namespace.
Collision Pairs
Collision pairs manage the collision of two objects. They persist over multiple frames, as long as the possible collision exists (as determined by the broad phase collision detection). During their lifespan, CollisionPairs will keep track of the state of the collision. If the objects intersect, the CollisionPair will move them apart to a safe collision margin and create Contact points to maintain noninterpenetration.
Contact
Contacts are generated by CollisionPairs to keep objects out of intersection. At each Contact location, an impulse is iteratively calculated using the number of iterations defined in the Space class.
Collision Rules
In v0.10.0, a collision rules system was implemented that allows categories of collisions as well as specific exceptions. See the specialized Collision Rules documentation for more information.
Events
Individual events can be hooked for collision events by using the Entity.eventManager.addEventHook method.Events without an "immediate" suffix are deferred to the end of the frame, allowing for most operations to be called safely. Each of these events also has an accompanying "immediate" version, which is called from the middle of engine execution. This allows direct access to relevant information. The demos (#30) have an example of how to use the event system in game logic.
The DetectorVolume class also offers intersection events against arbitrary closed triangle meshes.
Thread Safety
As of v0.7.0, running BEPUphysics in a separate thread has become significantly easier. Entity states such as position and velocity are buffered so that reads get the last valid result and writes wait until the engine is ready before changing values. Along with the buffered states, unbuffered properties are available; any property with a prefix of "internal," such as Entity.internalLinearVelocity, read and write values directly. This can be handy for immediate changes when it is known that thread safety isn't an issue.Space contains synchronization objects for use by external operations. The engine takes out locks on these synchronization objects as necessary, so locking the lockerUpdate object will ensure that your code will not run while the engine updates. The finer grained locks on entities, controllers, constraints, and updateables provide additional control.
The BroadPhase has its own lockerBroadPhaseUpdating object which is used internally by the updateControllers, getEntities, and rayCast methods. On the PC, lockerBroadPhaseUpdating is a ReaderWriterLockSlim, while on the Xbox it is an object which is locked by the updateControllers method. Note that the Xbox will not lock the lockerBroadPhaseUpdating locker during a raycast or query.