MayaBullet User's Guide

Overview

The MayaBullet plug-in provides access to the Bullet physics engine, which allows you to create large-scale, highly-realistic dynamic and kinematic simulations. You can use MayaBullet to create content for rendered animations for film and visualization, as well as for the setup of game engine and real-time simulations.

For information about installing MayaBullet and loading the plug-in, see your Maya user guide.

This user guide contains the following sections:

User Guide

Running the simulation
Rigid Body and Constraints
Soft Body and Anchors
Character Setup
Interactive Playback

Tutorials
Node Reference
Known Issues

This user guide describes the MayaBullet user-interface and explains how to use MayaBullet objects. For advanced Help on the Bullet library, refer to Bullet Physics Manual at www.bulletphysics.org.

User Guide

Bullet Physics is an open-source collision detection, rigid body and soft body dynamics library. The library provides a collection of objects each corresponding to the various aspects of dynamic simulations. For example, the Bullet solver, rigid bodies, soft bodies and constraints are all unique Bullet objects.

The Bullet solver is the central object in all dynamic simulations. It calculates the physics for the simulations through iterative time steps that use an object's current state to calculate its next state. To set up a typical MayaBullet simulation, you create the rigid bodies and soft bodies, adjust their attributes, add any required constraints between the objects, then play the simulation. Based on these settings and relationships, the solver updates the scene while advancing one frame at a time through the simulation.

The MayaBullet plug-in provides seamless mapping of Bullet objects to Maya objects. The controls to the Bullet objects are exposed in Maya Objects, and the interaction follows the typical Maya dynamics paradigm.

Running the simulation

The Bullet physics simulation is driven by the Maya timeline. To run a simulation, play the animation from the solver's start frame, which by default is frame 1 in the Maya timeline. To increase the duration of the simulation, increase the length of the timeline.

Bullet operates in time (seconds) and has a fixed rate at which it takes simulation steps. The Bullet solver does not use frames as a time unit. The fixed rate determines the resolution of the simulation and is specified by the solver's Internal Fixed Frame Rate attribute, which is set to 60 steps per second by default. For example, if Maya is set to playback at 30 fps, there would be 2 MayaBullet sub-steps per frame.

This design and implementation better supports real-time gaming applications where drawing and computation time per-frame must remain near constant. Allowing the solver to vary the number of simulation steps taken between any two drawing frames would greatly undermine the need to maintain a constant drawing speed.

Another way the Bullet solver maintains constant time to step the simulation, is to use an iterative solution algorithm to solve the dynamic systems equations instead of an explicit algorithm. Iterative solutions first approximate a solution, and then feed these values back into the equations to arrive at more accurate solutions. The time the solver spends approximating the solution is constant and is only dependent on the number of equations. When the solution for a single iteration varies by less than some epsilon, the system is considered to be solved. Depending on the simulation, the solution may require additional iterations before it converges on a solution. The solver’s Max Num Iterations attribute sets a maximum number of times the system of equations is iterated on before the solver stops calculating and uses the last approximate solution as the final solve. Therefore, the total time for a simulation step can be clamped. The drawback to this method is that the results may not be as accurate as more explicit solvers. For most applications in games and movies, the solver's degree of accuracy is sufficient.

The Solver

When you add Bullet objects to a Maya scene, a bulletSolverShape node is created. This node’s attributes manage the overall Bullet physics settings that apply to the entire scene including gravity and wind, and the solver engine that is used (CPU, GPU).

$Description: Description: Description: Description: Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\images\SolverAE.png$

Solver Properties

Start Time – Sets the time (in frames) that the Bullet simulation begins. By setting this attribute to a value greater than 1, you can animate the scene for an interval before the Bullet objects begin moving.
Debug Draw – Enables the Bullet's debug rendering, which displays what the Bullet engine is simulating in the Maya viewport. Debug Draw can be useful for identifying problems when objects are not behaving in the scene as expected.
Split Impulse – When enabled, this option nullifies any velocity that is created to separate interpenetrating objects at the start of the simulation. This is useful to prevent objects from flying violently apart while they are settling into their initial positions.
Solver Acceleration – The soft body solver in Bullet can be greatly accelerated using OpenCL on systems with OpenCL support. This option enables Bullet to take advantage of parallel computing resources such as multiple CPU cores or the graphics processing unit (GPU). For systems without GPU support, the solver can still be significantly accelerated using a CPU-only version of the OpenCL solver, which takes advantage of multiple CPU cores.
Internal Fixed Frame Rate – Sets the rate at which the Bullet physics simulation updates. This setting defines the resolution of the simulation. If the collisions fail to occur due to fast moving objects, reduce the time step by increasing Internal Fixed Frame Rate. See the Bullet Physics Manual (www.bulletphysics.org) for more information.
Max Num Iterations – Maya playback speed determines the time interval between two adjacent frames, for example 24 fps means each time step is 1/24 second. Bullet runs on fixed time steps, which are specified by the Internal Fixed Frame Rate attribute. For example, the default value of 60Hz means that Bullet simulates at fixed internal time step of 1/60 second. Bullet requires that the Maya time interval be less than the product of Max Num Iterations and the fixed time step. See the Bullet Physics Manual (www.bulletphysics.org) for details.

Basic Fields

Gravity – Specifies the vector representing acceleration due to gravity. Gravity affects all dynamic objects in the scene.
Wind Magnitude – Specifies the strength of the global wind force in the scene. Wind only affects soft bodies.
Wind Direction – Specifies the direction of the wind force as a vector (X, Y, and Z).

Collision Filters

Defines the collision filter names used by rigid and soft bodies when specifying selective collisions. See Collision Filtering - Bullet Physics Manual (www.bulletphysics.org) for more information.

Rigid Body and Constraints

Creating rigid bodies

To create a new rigid body, select Bullet > Create Active Rigid Body > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ or Bullet > Create Passive Rigid Body > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ .

After creating an active rigid body, you can still change the rigid body's initial position and orientation with Maya’s Move tool and Rotate tools if the current time is the same as the Bullet Solver's start time. If the current time is not the same as the Solver's start time, changes to the rigid body position and orientation are ignored when the time changes. Maya automatically detects and stores the new position and orientation as the initial state.

If a mesh is selected when Create Passive Rigid Body is selected, the rigid body is associated with the mesh using the mesh's convex hull as its default collider. If no mesh is selected, a rigid body is created using a box as its default collider shape. You can change the rigid body type by editing the Body Type attribute in the Rigid Body Properties section of the bulletRigidBodyShape node Attribute Editor. You can also change the default settings used when creating new rigid bodies by clicking on the option box to the right of the Bullet menu entry.

Rigid body types

There are three types of MayaBullet rigid bodies. You can specify the rigid body type by setting Body Type in the Create Rigid Body Option window or in the Rigid Body Properties section of the bulletRigidBodyShape node Attribute Editor. In MayaBullet, Dynamic rigid bodies are often referred to as active rigid bodies while Kinematic and Static rigid bodies are also known as passive rigid bodies.

Dynamic rigid bodies (Body Type > Dynamic Rigid Body) are fully simulated physics objects. This type is the most performance intensive rigid body. By default, all rigid bodies are created as Dynamic rigid bodies.
Kinematic rigid bodies (Body Type > Kinematic Rigid Body) can be animated during the physics simulation, but they are not affected by the simulation itself. Because kinematic bodies can be moved, the Bullet physics simulation spends more time updating kinematic rigid bodies than static rigid bodies.
Static rigid bodies (Body Type > Static Rigid Body) do not move during the physics simulation. The Bullet physics simulation can optimize how it updates static rigid bodies in the scene since it knows their positions remain fixed between frames.

You can animate the rigid body type and its transformation. When the Body Type attribute is set to Kinematic Rigid Body, you can set keys for the rigid body's Transform attributes. Keyed transformations have no effect when Body Type is set to Dynamic Rigid Body. Dynamic rigid body transformations are determined by the solver.

Rigid Body Properties

Attributes in the Rigid Body Properties section of the bulletRigidBodyShape node Attribute Editor determine the behavior of dynamic rigid bodies in the simulation. See bulletRigidBodyShape in the Node Reference for information about how these attributes affect the simulation. Two attributes that deserve special attention are:

Never Sleeps – When on, the dynamic rigid body always participates in the simulation. When off, the rigid body does not participate in the simulation if its linear velocity's magnitude is below 0.8 and angular velocity's magnitude is below 1.0. The velocity thresholds are currently not exposed for user control. The rigid body re-engages if it receives an impact. This is an optimization setting and can help to stop the lasting “simmering” motion of a rigid body.
Mass – Setting the mass to zero for a dynamic rigid body effectively turns it into a kinematic rigid body. That is, the rigid body stops moving due to forces in the physics simulation. This attribute can be animated, and can be useful to lock objects in place.

Initial Conditions

This section contains attributes that are applied when the Bullet solver starts simulating.

Forces/Impulses

This section contains attributes that control impulses applied to the rigid body every frame. Note that you will often want to animate these values so that they return to zero. Otherwise, in the absence of any counter-acting forces, continuously applying impulses over an entire animation can cause the rigid body to continuously accelerate.

Collider Properties

These attributes specify how the shape of the rigid body is represented in the simulation. In general, simpler shapes perform better and are more stable and predictable. The simplest shapes are plane (infinite), box, sphere, cylinder and capsule. Their shape is determined by the following attributes:

Length – Sets the length of the cylindrical section of a capsule or cylinder.
Radius – Sets the radius of a sphere or cylinder, or the radius of the spherical caps of a capsule.
Extents – Sets the length of the sides of a box collider.

Enabling Auto Fit in the Create Rigid Body Options window computes the tightest Length, Radius, and Extents when a rigid body is first created. Clicking Refit in the Collider Properties section of the Attribute Editor performs a onetime auto-fit on the existing rigid body. Note that the plane collider represents an infinite plane that passes through the position of the object's transform, and is oriented according to its rotation. It extends infinitely in the local X and Z directions.

Selected mesh colliders

If you selected a mesh as a collider when you created your rigid body, you can change the default creation values for new rigid bodies with mesh colliders in the Create Rigid Body Options window.

After you create a rigid body with a mesh collider, you can use the following collider shape types:

Hull – A convex hull is generated around the input mesh to use as the collider shape.
Mesh – The input mesh is used directly as the collider shape.

Collision Filters

These attributes let you configure selective collisions. By default, rigid bodies are members of the Default Filter collision group and collide with other members of the Default Filter collision group. The rigid body may be a member of up to 16 groups and can be configured to collide with up to 16 other members of the same group. The collision filter group names can be customized by the Bullet solver's collisionFilters attribute.

See the Bullet Physics Manual (www.bulletphysics.org) for more information about the different collider shape types.

Creating rigid body constraints

You can use the following constraints with rigid bodies:

Point
Hinge
Slider
Cone-Twist
6 Degrees-of-Freedom
Spring Hinge
Spring 6 Degrees-of-Freedom

The behavior of the different constraint types is described in the Bullet Physics Manual (www.bulletphysics.org).

To create a rigid body constraint:

Select one or two rigid bodies. If you select only one rigid body, the constraint is anchored to its position in Maya worldspace.
Select Bullet > Create Rigid Body Constraint > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ .

Constraint Properties

These attributes determine how the constraint is applied. For example, you can specify how freely the rigid bodies swing or slide by setting Linear Damping or Angular Damping. Linear attributes control the distance between the constraint point and the rigid bodies. Angular attributes control the rotation of the rigid bodies around the constraint point.

Linear Damping is a value between 0.0 and 1.0 with a default of 0.0. A value of 1.0 fully dampens the forces applied to the translation.
Linear Softness is a value between 0.0 and 1.0 with a default of 0.0.
Linear Restitution is a value between 0.0 and 1.0 with a default of 0.0.
Angular Damping is a value between 0.0 and 1.0 with a default of 0.0. A value of 1.0 fully dampens the forces applied to the rotation.
Angular Softness is a value between 0.0 and 1.0 with a default of 0.0.
Angular Restitution is a value between 0.0 and 1.0 with a default of 0.0.

Limits

Using these attributes, you can set limits on the constraint's range of motion. The various constraint types support different combinations of limits. In general, linear constraints control the distance of the rigid bodies from the constraint point affecting sliding motions. Angular constraints control the freedom for rigid bodies to rotate around the constraint point affecting twisting and swinging motions.

Linear Constraint defines whether a linear translation can be locked, free, or limited.
Linear Constraint Min defines the minimum X, Y, and Z translations.
Linear Constraint Max defines the maximum X, Y, and Z translations.
Angular Constraint defines whether the axis rotation can be locked, free, or limited.
Angular Constraint Min defines the minimum angle, for the X, Y, and Z angles, in degrees (-360 and 360).
Angular Constraint Max defines the maximum angle, for the X, Y, and Z angles, in degrees (-360 and 360).

Limit Properties

These attributes determine how the rigid bodies move when they reach a limit, such as whether they stop abruptly or gently at that limit.

Linear Limit Bias is a value between 0.0 and 1.0 with a default of 0.3.
Linear Limit Softness is a value between 0.0 and 1.0 with a default of 1.0.
Linear Limit Relaxation is a value between 0.0 and 1.0 with a default of 1.0.
Angular Limit Softness specifies the percentage of limit where the movement is free. Beyond this softness percentage, the limit is gradually enforced until the "hard" (1.0) limit is reached. The value is between 0.0 and 1.0 with a default of 1.0. The recommended value is 0.8.
Angular Limit Bias specifies the strength with which the constraint resists angular limit violation. The value is between 0.0 and 1.0 with a default of 0.3.
Angular Limit Relaxation specifies how much a constraint resists velocities which violate the angular limits. The lower the value, the less the constraint resists the violation. The value is between 0.0 and 1.0 with a default of 1.0. The recommended value is near 1.0.

Motors

These attributes let you setup motors which can actively drive the constraint. Typically, rigid bodies attached to a constraint move freely until they come to rest. With motors, the constraints actively move the rigid bodies. The hinge and Six Degrees-Of-Freedom (SixDOF) constraints support angular motors, which rotate the rigid body around the constraint. The slider constraint supports linear motors, which push or pull the rigid body.

Angular Motor Enabled turns the motor on the X, Y, and Z axis on and off.
Angular Motor Target Speed specifies the target velocity for the motor's X, Y, and Z axis.
Angular Motor Max Force specifies the maximum motor impulse, for each X, Y, and Z axis, that can be applied at a single simulation step. It has a value greater than or equal to 0.0.

Springs

These attributes set the stiffness and dampening effect of the spring on the translation and rotation of the constrained body. Normally, rigid bodies attached to a constraint move freely until they come to rest. The spring hinge and spring Six-DOF constraints support linear and angular springs.

Constraint Type

When you create a constraint, you can select its type from the Constraint Type list in the Create Rigid Body Constraint Options window. After a constraint is created, you can change its type by selecting one from the Constraint Type list of the bulletRigidBodyConstraintShape node Attribute Editor. You can select from the following constraint types:

Point

The Point constraint (called a point-to-point constraint in the Bullet Physics library) limits the translation so that pivot points between the two rigid bodies match in world space. You can use the Point constraint to create effects, such as a chain-link, or to pin objects together.

The Point constraint supports the following attributes:

Angular Dampening

Hinge

The Hinge constraint restricts the translation and two additional angular degrees of freedom, so the body can only rotate around one axis. The hinge axis is defined by the Z axis of the constraint. This constraint is useful for representing doors or wheels rotating around an axis. The user can specify limits and motor settings for the hinge.

The Hinge constraint supports the following attributes:

Angular Limit Softness
Angular Limit Bias
Angular Limit Relaxation
Angular Constraint Min Z
Angular Constraint Max Z
Angular Motor Enabled turns the Z axis motor on and off.
Angular Motor Target Speed specifies the Z axis target velocity.
Angular Motor Max Force specifies the maximum motor impulse that can be applied to the Z axis in a single simulation step.

Slider

The Slider constraint allows rigid bodies to rotate around one axis and translate along the same axis. The slide axis is defined by the Z axis of the constraint.

The Slider constraint supports the following attributes:

Linear Damping
Linear Softness
Linear Restitution
Linear Limit Bias
Linear Limit Softness
Linear Limit Relaxation
Linear Constraint Min X
Linear Constraint Max X
Linear Motor Enabled turns the motor on the X axis on and off.
Linear Motor Target Speed specifies the target velocity for the motor. Only the X field is used.
Linear Motor Max Force specifies the maximum motor impulse. Only the X field is used.
Angular Damping
Angular Softness
Angular Restitution
Angular Limit Softness
Angular Limit Bias
Angular Limit Relaxation
Angular Constraint Min X
Angular Constraint Max X
Angular Motor Enabled turns the motor on the X axis on and off.
Angular Motor Target Speed uses only the X value.
Angular Motor Max Force uses only the X value.

Cone-Twist

For ragdolls, the Cone-Twist constraint is useful for limbs like the upper arm. It is a special point-to-point constraint that adds cone and twist axis limits. The X axis serves as twist axis.

The Cone-Twist constraint supports the following attributes:

Angular Damping
Angular Limit Softness
Angular Limit Bias
Angular Limit Relaxation
Angular Constraint Max X specifies the twist span angle in degrees.
Angular Constraint Max Y specifies the swing span 2 angle in degrees.
Angular Constraint Max Z specifies the swing span 1 angle in degrees.
Angular Motor Enabled turns the motor on the X axis on and off.
Angular Motor Max Force X

Six Degrees-of-Freedom

The Six Degrees-Of-Freedom (SixDOF) constraint can emulate a variety of standard constraints if each of the six Degrees of Freedom (DOF) is configured. The first 3 DOFs axis are linear axis, which represent the translation of rigid bodies, while the latter 3 DOFs axis represent the angular motion. Each axis can be locked, free, or limited. By default, all axes are unlocked.

The SixDOF constraint supports the following attributes:

Linear Damping
Linear Softness
Linear Restitution
Linear Constraint
Linear Constraint Min
Linear Constraint Max
Linear Motor Enabled
Linear Motor Target Speed
Linear Motor Max Force
Angular Damping
Angular Softness
Angular Restitution
Angular Constraint
Angular Constraint Min
Angular Constraint Max
Angular Motor Enabled
Angular Motor Target Speed
Angular Motor Max Force

Spring Hinge

The Spring Hinge has three degrees-of-freedom. These include two rotational degrees-of-freedom around Z (Axis 1) and X (Axis 2), and one translational along Z (Axis 1) with a suspension spring. A use-case example of a Spring Hinge constraint is the steering wheel of a car, where one axis allows the wheel to be steered while the other axis allows the wheel to rotate. For this case, you need to rotate the spring hinge -90 in X to align Axis 1 with Y.

The Spring Hinge constraint has an anchor point for Axis 2, which is specified by the position of the constraint. Axis 1 is specified relative to body 1. This would be the steering axis if body 1 is the chassis. Axis 2 is specified relative to body 2 and is perpendicular to Axis 1 (along X). This would be the wheel axis if body 2 is the wheel. Axis 1 (along Z) can have springs as well as angular and linear limits, but Axis 2 (along X) is free. You cannot have springs and motors enabled at the same time. If you want to drive Axis 2, modify the X Torque Impulse of body 2.

The Spring Hinge constraint supports the following attributes:

Linear Constraint
Linear Constraint Min Z
Linear Constraint Max Z
Linear Spring Enabled
Linear Spring Stiffness
Linear Spring Dampening
Angular Constraint
Angular Constraint Min Z
Angular Constraint Max Z
Angular Spring Enabled
Angular Spring Stiffness
Angular Spring Dampening

Spring Six Degrees-Of-Freedom

The Spring Six Degrees-Of-Freedom (SpringSixDOF) constraint is a variant of the Six Degrees-of-Freedom constraint that includes the addition of springs for each of the degrees of freedom. Springs and motors cannot be combined on this constraint.

The SpringSixDOF constraint supports the following attributes:

Linear Constraint
Linear Constraint Min
Linear Constraint Max
Linear Spring Enabled
Linear Spring Stiffness
Linear Spring Dampening
Angular Constraint
Angular Constraint Min
Angular Constraint Max
Angular Spring Enabled
Angular Spring Stiffness
Angular Spring Dampening

Baking rigid body simulation

Bullet rigid bodies support Maya's standard baking workflow by using Edit > Keys > Bake Simulation. The following workflow creates the least number of animation curves:

Select the rigid body(s) to bake.
Select all the Translate and Rotate attributes in the Maya Channel Box.
Select Edit > Keys >Bake Simulation > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . The Bake Simulation Options window appears.
In the Bake Simulation Options window, select From Channel Box.
Click Bake.

The baking process creates an animation curve for each attribute and connects them to the corresponding pairBlend input attribute. An additional animation curve is also created to notify the rigid body when to use the simulation or key-framed result.

Duplicate rigid bodies and constraints

There are two ways to duplicate a rigid body. One way is to use the copy, cut, and paste command combination, while the other is to use Duplicate Special. When you use copy, cut, and paste, the original and duplicate rigid bodies share the existing solver. When Duplicate Special is used, the solver is duplicated along with the rigid body.

To use Duplicate Special do the following:

Select the rigid body and its associated constraints in the scene.
Select Edit > Duplicate Special > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . The Duplicate Special Options window appears.
In the Duplicate Special Options window, turn on Duplicate Input Graph.
Click the Duplicate Special.

Soft Body and Anchors

Creating soft bodies

You can create Bullet soft bodies from Maya polygon meshes. When a soft body is created, a new mesh node, identified by the original polygon object name, suffixed with _Solved, is also created. This object is the mesh that is deformed by the Bullet soft body simulation. Polygon planes work well as cloth soft bodies, although any polygon mesh can be used.

To create a soft body

Select the polygon mesh you want to use as a soft body.
Select Bullet > Create Soft Body > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . The Create Soft Body Options window appears.
Configure your soft body options and click Apply and Close.

Soft body attributes

Soft Body Construction

These attributes affect how the soft body is created.

Generate Bend Constraints creates constraints in the soft body system that control how much the joints at each vertex can bend.
Self Collision causes the solver to detect and resolve collisions between different parts of the same soft body, such as when a patch of cloth folds back on itself.

Soft Body Properties

These attributes affect how the soft body behaves when simulated by the solver.

Bend Resistance controls how strongly the bend constraints resist parts of the soft body bending. This attribute does nothing if Generate Bend Constraints is off.
Linear Stiffness controls how much stretch is in the soft body.
Friction sets the amount of friction between the soft body and other objects.
Damping is a damping factor applied to the overall motion of the soft body. Too much damping prevents the soft body from moving.
Mass is the total mass of the soft body. The paintable particleMass attribute is a scaling factor of the total mass on each vertex.

Aerodynamics

These attributes affect how the soft body reacts to the air around it.

Pressure determines how strongly a closed soft body, such as a sphere, maintains its shape and volume. High Pressure values cause the body to expand, while low Pressure values cause it to collapse.
Drag controls the amount of drag acting on the soft body as it moves through the air.
Lift controls the amount of lift that is generated as the soft body moves through the air.

Pose Matching

These attributes let you setup the soft body pose matching system, which works on closed shapes. You can use any combination of shape and volume matching on a single soft body.

Enable Shape Matching – When on, the soft body tries to maintain its original shape.
Shape Coefficient-Specifies the degree to which the rigid body attempts to maintain its shape. Higher Shape Coefficient values cause the rigid body to adhere more strictly to its original shape. If the values are too high, the soft body may penetrate or even fall through other objects.
Enable Volume Matching – When on, the soft body tries to maintain its original volume.
Volume Coefficient-Specifies the degree to which the rigid body attempts to maintain its initial volume. The higher Volume Coefficient value, the more the soft body resists changes to its original volume. High Volume Coefficient values can cause the simulation to become unstable.

Contacts

These attributes determine the degree to which the solver resists changes to the soft body's shape when it comes in contact with various types of objects.

Soft Body Solver

These attributes are used by the Bullet solver to modify how it updates the soft body system.

Collision Filters

These attributes let you configure selective collisions. By default, soft bodies are members of the Default Filter collision group and collide with other members of the Default Filter collision group. The soft body may be a member of up to 16 groups and can be configured to collide with up to 16 other members of the same group. The collision filter group names can be customized by the Bullet Solver's collisionFilters attribute.

Duplicate soft bodies and constraints

There are two ways to duplicate a soft body. One way is to use the copy, cut, and paste command combination, while the other is to use Duplicate Special. When you use copy, cut, and paste, the original and duplicate soft bodies share the existing solver. When Duplicate Special is used, the solver is duplicated along with the soft body.

To use Duplicate Special do the following:

Select the soft body and its associated constraints in the scene.
Select Edit > Duplicate Special > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . The Duplicate Special Options window appears.
In the Duplicate Special Options window, turn on Duplicate Input Graph.
Click the Duplicate Special.

Creating soft body anchors

To create a soft body anchor

Do one of the following:

Select a vertex on the soft body.
Select a rigid body to anchor the vertex to. If you do not select a rigid body, a new one is created.

Select Bullet > Create Constraint:Soft Body Anchor.

The vertex is now anchored to the rigid body. The rigid body can be animated or simulated with the results affecting the soft body simulation.

Painting soft body vertex properties

MayaBullet lets you paint per-vertex attributes onto a soft-body. You can paint the Mass, Linear Stiffness, and Bend Resistance attributes. Setting the Mass to zero has the effect of locking the vertex in place.

To paint property values on the vertices of a soft body:

Select the soft body. Soft bodies are identified in Maya’s Outliner by the original polygon object name suffixed by _Solved.
Select Bullet > Paint Soft Body Vertex Properties and select the property to be painted.

The Maya Paint Attributes Tool is activated allowing you to use all of its painting modes and options. If the Paint Attributes settings are not initially visible, select Window > Settings/Preferences > Tool Settings. To see the weights in the Maya viewport, you need to select Shading > Smooth shade All or Shading > Wireframe On Shaded from the Maya’s Panel menu.

To streamline "pinning" vertices on a soft body by setting their Mass to 0, use the Set SoftBody Vertex Properties option.

Select the vertices you wish to set.
Select Bullet > Set Soft Body Vertex Properties > Mass. The Bullet Soft Body Per-Particle Set window appears.
In the Bullet Soft Body Per-Particle Set window, type a new Mass value. In this case, 0.
Click OK.

Character Setup

MayaBullet provides two tools to assist with setting up characters and other assets based on skeletons (joint hierarchies).

Use the following steps to add kinematic rigid bodies to a skeleton:

Select the root node of the skeleton.
Select Bullet > Add Colliders to Skeleton > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ .

This tool examines the joint hierarchy starting from the currently selected joint, and creates a capsule around each bone. These capsules follow the animation of the skeleton, and collide with dynamic Bullet objects. Note that the dynamic objects do not affect the character animation. Their interaction only affects the dynamic objects.

The capsule generation process can be adjusted from the Add Colliders Options window (Bullet > Add Colliders to Skeleton > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ ).

Capsule:Bone Length Ratio controls how much of each bone is covered by a capsule. Reducing this value reduces the amount of overlap between the capsules at the joints.
Capsule Radius:Length Ratio controls the width of the capsules, relative to the length of the bones.

To create a dynamic ragdoll from a skeleton:

Select the root joint the skeleton.
Select Bullet > Create Ragdoll from Skeleton > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ .

The tool creates a network of dynamic rigid body capsules that correspond to the bones of the skeleton, and connects them with constraints that match the attributes of the joints. The names of the capsules and constraints are based on the names of the joints in the skeleton. This naming convention makes it easier for tools developers when writing exporters or rigging scripts to combine the ragdoll motion with standard skeletal animations.

The Create Ragdoll Options window can be customized in the same way as the Add Colliders Options window. In addition to capsule parameters, there are parameters for configuring the constraints. The Joint Name Separator setting can be changed to modify the character(s) that appear between joint names when naming capsules.

Interactive Playback

MayaBullet also provides an Interactive Playback mode. During normal animation playback, you cannot manipulate objects in the Maya scene. By selecting Interactive Playbackmode (Bullet > Interactive Playback), you can move scene objects, such as passive rigid bodies, and see them interact in the Bullet simulation.

Interactive Playback only works on passive rigid bodies. To use Interactive Playback, the passive rigid body needs to have an additional transform as the parent so as not to interfere with the transform that the rigid body operates on. Select the additional transform and start Interactive Playback. You can change the Maya move, rotate, and scale tools and see the simulation update according to these changes.

Tutorials

Lesson 1: Rigid Body Simulation with Collision Detection

This tutorial demonstrates the rigid body simulation and collision detection between any two of the three objects.

In a new Maya scene, set the Maya Time Slider duration to 100 frames and ensure it is set to playback at frame 1.
Create a polygon plane by selecting Create > Polygon Primitives > Plane > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . Set the Width and Height to 20, and click Create.
Convert the plane to a rigid body by selecting it and selecting Bullet > Create Passive Rigid Body.
Create a polygon cube by selecting Create > Polygon Primitives > Cube > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . Set the Width, Height, and Depth to 20, and click Create.
Position the cube by setting its Translate values to the following: X: 0, Y: 1, and Z: 0.
Create a polygon sphere by selecting Create > Polygon Primitives > Sphere > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . Set the Radius to 1 and click Create.
Position the sphere by setting its Translate values to: X: -10, Y: 1, and Z: 0.
Convert the cube and sphere to rigid bodies by selecting them and selecting Bullet > Create Active Rigid Body.
Select the cube and select its bulletRigidBodyShape node tab in the Attribute Editor.
In the Rigid Body Properties section, set Friction to 0.1. This reduces the force due to friction that is currently acting on the object.
Select the sphere and select its bulletRigidBodyShape node tab in the Attribute Editor.
In the Rigid Body Properties section, set Friction to 0.1 and in the Forces/Impulses section, set Impulse along the X axis to 0.2
In the Collider Properties section, set Collider Shape Type to sphere.
Playback to the simulation. The Impulse attribute applies a force along the X axis causing the rigid body sphere to roll along the plane and collide with the cube.

Lesson 2: Cloth Simulation and Anchor Constraint

This tutorial demonstrates a simple cloth simulation using a soft body plane and an anchor constraint.

In a new Maya scene, set the Maya Time Slider duration to 200 frames and ensure it is set to playback at frame 1.
Create a polygon plane by selecting Create > Polygon Primitives > Plane > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . Set the Width and Height to 5 and the Width divisions and Height divisions to 20. Click Create.
Position the plane by opening the Channel Box and setting its Translate values to: X: 2.5, Y: 0, and Z: 2.5. One of the planes four corners should now be at the origin.
Convert the plane to a soft body by selecting it and selecting Bullet > Create Soft Body. The plane is now a soft body object.
Select Create > Locator to create a locator at the origin.
Right-click the mesh and select Vertex from the menu that appears.
Shift select the mesh vertex at the origin and the locator and select Bullet > Create Constraint Soft Body Anchor. This attaches the selected vertex to the locator.
Playback the simulation. The cloth falls due to gravity but hangs on to the locator like constrained cloth.

Lesson 3: Hinge Constraint Simulation

In a new Maya scene, set the Maya Time Slider duration to 1000 frames and ensure it is set to playback at frame 1.
Create two polygon meshes by selecting Create > Polygon Primitives > Plane > $Description: Description: Description: Description: C:\Users\ellwoor\Documents\Baretta\MayaBullet\MayaBulletFinalDevDrop\doc\doc\MayaBulletGuide_edits_files\image001.jpg$ . When you create each plane, set the Width and Height to 5.
Translate the meshes so that they meet along the Z axis. One way to do this is to set the X Translate value of one mesh to 2.5 and the other 0 -2.5.
Select one mesh and convert it to a passive rigid body by selecting Bullet > Create Passive Rigid Body. This is considered Rigid Body A.
Select the other mesh and convert it to a active rigid body by selecting Bullet >Create Active Rigid Body. This is considered Rigid Body B.
Select two meshes and select Bullet >Create Rigid Body Constraint to create a constraint between them.
In the Outliner (Window > Outliner), select the bulletRigidBodyConstraint node.
In the Attribute Editor, click the bulletRigidBodyConstraintShape node tab.
From the Constraint Type list, select Hinge. This creates a Hinge constraint between Rigid Body A and Rigid Body B along each object Z axis.
Select Rigid Body B.
In the Attribute Editor, click the bulletRigidBodyShape node tab.
In the Rigid Body Properties section set Angular Damping to 0.4.
Playback the simulation. Rigid Body B swings back and forth along it Z axis. Over time, the rigid body swings decrease until they stop at around frame 1000.
To see the effects of enabling a Motor on the constraint, in the Outliner, select the bulletRigidBodyConstraint node.
In the Attribute Editor, in the Motors section, turn on Angular Motor Enabled.
Playback the simulation. Rigid Body B now swings at a constant speed in 360 degree rotations due to the Angular Motor.

Node Reference

The following is a complete list of MayaBullet nodes:

Known Issues

General

After duplicating Bullet objects, you may need to rewind to start frame of the Maya timeline to see the correct result.
The Bullet node structure not ideal for modifying or deleting.
With OpenCL acceleration, the capsule is the only recognizable rigid body shape type. In addition, capsules whose length is less than or equal to twice the radius will be ignored.
Bullet OpenCL acceleration does not support soft body to soft body collisions.
CPU and GPU accelerated solvers only support capsule as the Collider Shape Type. Other Collider Shape Types are not be recognized by these solvers.

Bullet Solver

· Bullet nodes may not appear correctly in the viewport if the Maya timeline is not rewound to frame 1. This occurs because the solver needs to be reinitialized to recognize new objects. New objects in the scene are reinitialized at frame 1 of the Maya timeline.

· The output from the Bullet solver Debug Draw for collisions between soft bodies and plane collider shapes may appear erratic. This occurs because Bullet renders a yellow wire-frame for the triangles that represent the projection of the soft body's axis-aligned bounding box onto the plane. This is the expected behavior. It may be easier to visualize the collisions by viewing the scene from the Top perspective viewport.

Rigid Body, Soft Body, and Ragdoll

· Output meshes with per-facet shaders cannot locate the bulletSoftBodyShape node when setting the per-particle particleMass attribute. As a workaround, use the source mesh to set the per-particle particleMass attribute.

· Ragdoll does not collapse as if the pieces are properly joined.

The Never Sleeps attribute for rigid bodies does not work properly.

· An active rigid body does not simulate if its original mesh has had Freeze Transformations performed on it.

If a static rigid body has an associated animated rigid body, Bullet treats the static rigid body as a kinematic rigid body internally. This means that the optimization by the solver for static rigid body is disabled. As a workaround, go to the Maya timeline start frame and replay the simulation.
Setting the Linear Constraint X, Y, and Z attribute to Locked may not lock the constraint completely along this specified axis.
The Limits attributes for rigid body constraints may not work properly.