Hey everyone!
As you may or may not have known, the good folks on our Physics team have been working on a revamp of the body movers system. These new movers take advantage of the attachment/constraint system and all of the other optimizations we have been making under the hood.
To help you get started, we’ve created a sample place showcasing the new movers in various configurations. While we tried to cover a lot of simple cases, this merely scratches the surface of what you can do, so don’t be afraid to experiment! You can get a copy of the place here: New Body Movers Example.rbxl (17.6 KB)
#Documentation
One of the goals of the new movers was to allow you to recreate behaviors that you had with the old movers, along with some cool new features that were hard or simply impossible with the old system. We have some initial documentation of all the members of the new Instances that we will lists below, but for a quick reference if you want to see how old behavior can be mapped to new:
- BodyForce > VectorForce (relative to World)
- BodyThrust > VectorForce (relative to Attachment0)
- BodyAngularVelocity > Torque (only for torque. Use actuated hinge to reach specific rotational velocity)
- BodyGyro > AlignOrientation
- BodyPosition > AlignPosition
- RocketPropulsion > AlignOrientation + AlignPosition/VectorForce
- (No legacy mover) > LineForce
##Vector Force
A VectorForce is used to apply a force to a part or assembly of parts. The direction and strength of the force is determined by a Vector3 and can be relative to an attachment on the part, another attachment, or the world coordinate system.
###Location of Force
A VectorForce will apply its force on the Parent of its Attachment0, but the location where the force is applied is determined by the VectorForce’s ApplyAtCenterOfMass property.
When ApplyAtCenterOfMass is false, which it is by default, the force will be applied to the part at the Attachement0’s location. This means that if the attachment is not at the center of the part, it can create a torque on the part.
When ApplyAtCenterOfMass is set to true, the force will check if any other parts are rigidly connected to the parent part of its Attachment0. If there are, then the force will apply at the center of mass of all of the connected parts. If there are no rigid connections to other parts, the force will simply be applied at the center of mass of the part.
###Direction of Force
The direction of the force is determined by the Vector3 defined by force, but it will also be affected by the RelativeTo property.
By default, RelativeTo is set to Attachment0, meaning the force will be applied in the space local to the attachment. Remember that when visualizing an attachment, the yellow arrow shows the direction of positive X, and the orange bar shows the direction of positive Y. If the part the attachment is connected to rotates, the force will change direction to make sure it is still in the context of the attachment.
RelativeTo can also be set to Attachment1. In this case, the force will be applied in the space local to Attachment1, regardless of the orientation of Attachment0 or its connected part. If Attachment1 rotates, then the force will change to stay oriented correctly.
Last, RelativeTo can also be set to World. In this mode, the force is applied in world coordinates, regardless of the orientation of Attachment0 or its part.
###Properties
- Enabled (bool) - Determines whether the VectorForce is active or not.
- ApplyAtCenterOfMass (bool) - When true, applies force at center of mass of Attachment0’s parent Part. When false, applied at Attachment0.
- Force (Vector3) - The strength and direction of the force.
- RelativeTo (enum - Attachment0, Attachment1, World) - The coordinate frame in which the Force is expressed.
- Attachment0 (Attachment) - The base attachment. The parent of this attachment is the part that will be affected by the force.
- Attachment1 (Attachment) - The attachment to use for the reference frame if RelativeTo is equal to Attachment1. Note that this only determines the direction of the attachment. The force will still be applied to Attachment0. If RelativeTo is not equal to Attachment1 then this property is not used.
##Line Force
A LineForce is used to apply a force along a line between two points. As the end points of the line move, the direction of the force will change accordingly.
###Direction of Force
The direction that a LineForce applies its force in is determined by its attachments and ApplyAtCenterOfMass properties. When ApplyAtCenter of mass is false, which it is by default, the direction of the force will be from the location of Attachment0 to the location of Attachment1. If ApplyToCenter is false, then the direction will be from the center of mass of Attachment0’s parent to the location of Attachment1. Note that if the parent of Attachment0 is rigidly connected to other parts, then the LineForce will use the center of mass of all of the parts to determine the origin of the direction.
###Location of Force
A VectorForce will apply its force on the Parent of its Attachment0, but the location where the force is applied is determined by the VectorForce’s ApplyAtCenterOfMass property.
When ApplyAtCenterOfMass is false, which it is by default, the force will be applied to the part at the Attachement0’s location. This means that if the attachment is not at the center of the part, it can create a torque on the part.
When ApplyAtCenterOfMass is set to true, the force will check if any other parts are rigidly connected to the parent part of its Attachment0. If there are, then the force will apply at the center of mass of all of the connected parts. If there are no rigid connections to other parts, the force will simply be applied at the center of mass of the part.
###Strength of Force
The strength of the force applied by a VectorForce is determined by the VectorForce’s Magnitude and InverseSquareLaw properties. The InverseSquareLaw property determines whether the force is constant or not.
When InverseSquareLaw is false, which is is by default, the force applied is constant, and its magnitude is equal to the magnitude defined by the Magnitude property.
When InverseSquareLaw is true, then the force will scale based on how much distance there is between the two endpoints. When the distance is 1 stud, then the force’s magnitude will be the value of the Magnitude property. If the two points are further away, the force will decrease. Conversely, the force will increase if the two points move closer together. This function can be used to determine the force at any given separation:
ActualMagnitude = Magnitude / (Separation ^ 2)
Tip: VectorForces with InverseSquareLaw set to true can be used to simulate various physical systems such as gravity or electric fields.
###Properties
- Enabled (bool) - Determines whether the LineForce is active or not.
- ApplyAtCenterOfMass (bool) - When true, applies force at center of mass of Attachment0’s parent Part, and the line determining the direction of the force will start at the said center of mass. When false, the force is applied at Attachment0’s location and the line determining the direction will also start at Attachment0.
- Magnitude (number) - The magnitude of the force.
- InverseSquareLaw (bool) - When true, the force magnitude is multiplied by the inverse square of the distance.
- Attachment0 - The base attachment. This Attachment is used to determine both the origin of the line that determines the direction of the force, along with where the force will be applied.
- Attachment1 - The second attachment in the system. This Attachment is used to determine the end point of the line that determines the direction of the force.
##Torque
A TorqueActuator is used to apply a torque to a part or assembly. When active, this object will find the center of mass of the part or assembly connected to its Attachment0 and will apply a torque, spinning the part or parts.
###Direction of Torque
The direction of the spin is determined by the Torque and RelativeTo properties. The Torque defines the spin about the X, Y, and Z axes. However, these axes are oriented based on the RelativeTo property.
When RelativeTo is set to Attachment0, the torque will be oriented based on the local space of Attachment0. If Attachment0 moves or rotates, the torque will change to make sure it is still applying in the correct directions. Similarly, when RelativeTo is set to Attachment1, the torque will be applied based on Attachment1’s orientation, regardless of the position or direction of Attachment0. Last, RelativeTo can be set to World, which will use the world coordinate system to determine the axes for rotation.
###Properties
- Enabled (bool) - Determines whether the Torque is active or not.
- RelativeTo (enum - Attachment0, Attachment1, World) - The coordinate frame in which the Torque is expressed.
- Torque (Vector3) - The strength and direction of the torque.
- Attachment0 (Attachment) - The base attachment. The parent of this attachment is the part that will be affected by the torque.
- Attachment1 (Attachment) - The attachment to use for the reference frame if RelativeTo is equal to Attachment1. Note that this only determines the direction of the attachment. The torque will still be applied to Attachment0. If RelativeTo is not equal to Attachment1 then this property is not used.
##AlignPosition
An AlignPosition is used to apply a force towards a location. Like other constraints, AlignPositions have two Attachments. In this case the attachments are constrained to be in the same position, although not necessarily in the same orientation. By default, this constraint only applies forces on Attachment0, although it can be configured to apply forces on both attachments.
###Reaction Force
AlignPositions by default only apply a force on Attachment0’s parent Part. The parent Part of Attachment1 remains unaffected. However, a force can also be applied to Attachment1 by enabling the ReactionForceEnabled. This will cause a force to be applied to both Attachment0 and Attachment1 in the direction of each other.
###Force Location
By default the force created by an AlignPosition is applied to the parent Part of Attachment0 at the Attachment’s location. The direction of the force is always towards Attachment1. This means that if the center of mass of the Part is not aligned with the direction of the force, a torque will be applied to the part as well as a force.
AlignPositions’ behaviors can be changed with the ApplyAtCenterOfMass property. When enabled, the AlignPosition will check if other Parts are rigidly connected to the parent Part of Attachment0. If there are, then the force will be applied at the center of mass of those connected parts. If not, then the force will be applied at the center of mass of the parent part itself.
###Force Magnitude
The force used to constrain an AlignPosition can either be configured or set to the maximum that constraints allow. Whether the force is configurable is determined by the RigidityEnabled property.
When RigidityEnabled is true, then the physics solver will use as much force as possible to move the two attachment points together. This is the same scale of force used to connect other constraints, such as hinges when their attachments are separated.
When RigidityEnabled is false, then the force will be determined by the MaxForce, MaxVelocity, and Responsiveness. MaxForce and MaxVelocity are caps to the force and velocities respectively. The actual scale of the force is determined by the Responsiveness. The mechanism for responsiveness is a little complicated, but put simply the higher the responsiveness, the quicker the constraint will try to reach its goal.
###Properties
- Enabled (bool) - Determines whether the AlignPosition is active or not.
- ApplyAtCenterOfMass (bool) - When true, applies force at center of mass of Attachment0’s parent Part. When false, applied at Attachment0.
- ReactionForceEnabled (bool) - When true the constraint will apply force on both Attachments to achieve the goal.
- RigidityEnabled (bool) - When true the solver will react as quickly as possible to move the attachments together. When false, force dependant on MaxForce, MaxVelocity, and Responsiveness.
- MaxForce (float) - Maximum force the constraint can apply to achieve its goal. Only used if RigidityEnabled is false.
- MaxVelocity (float) - Maximum speed the Attachment can move when converging. Only used if RigidityEnabled is false.
- Responsiveness (float) - Used to control how quickly the constraint will reach its goal. Higher values will cause the attachments to move together quicker. Value can be between 5 and 200.
- Attachment0 (Attachment) - The first attachment of the constraint.
- Attachment1 (Attachment) - The second attachment of the constraint.
##AlignOrientation
An AlignOrientation is a constraint that applies a torque to make its attachments align. Like other constraints, this has two Attachments. In this case the two attachments are constrained to be oriented in the same direction but not necessarily the same position. By default, this constraint only applies torque on Attachment0’s parent, although it can be configured to apply torque on both attachments.
Note that any torque created by AlignOrientation will be applied about the center of mass of the parent of the attachments (or the center of mass of rigidly connected parts to the parents).
###PrimaryAxis
The behavior of an AlignOrientation is determined by its PrimaryAxisOnly property. By default this value is false and an AlignOrientation will work so that the orientation of its Attachment0 exactly matches the orientation of its Attachment1. It will apply torque about all 3 axes to achieve this goal.
If PrimaryAxisOnly is set to true, then the AlignOrientation will only apply torque if the primary axis of its Attachment0 becomes unaligned with Attachment1. This means that any rotation about the Attachment0’s primary axis will not create a torque.
###TorqueMagnitude
The torque used to constrain an AlignOrientation can either be configured or set to the maximum that constraints allow. Whether the torque is configurable is determined by the RigidityEnabled property.
When RigidityEnabled is true, then the physics solver will use as much torque as possible to move the two attachment points together. This is the same scale of force used to align other constraints, such as prismatics when their attachments are misaligned.
When RigidityEnabled is false, then the force will be determined by the MaxTorque, MaxAngularVelocity, and Responsiveness. MaxForce and MaxVelocity are caps to the torque and angular velocity respectively. The actual scale of the torque is determined by the Responsiveness. The mechanism for responsiveness is a little complicated, but put simply the higher the responsiveness, the quicker the constraint will try to reach its goal.
###Reaction Force
AlignOrientations by default only apply a torque on Attachment0’s parent Part. The parent Part of Attachment1 remains unaffected. However, a torque can also be applied to Attachment1 by enabling the ReactionForceEnabled. This will cause a torque to be applied to both Attachment0 and Attachment1 in equal and opposite directions.
###Properties
- Enabled (bool) - Determines whether the AlignOrientation is active or not.
- ReactionTorqueEnabled (bool) - When true the constraint will apply torque on both Attachments to achieve the goal.
- RigidityEnabled (bool) - When true the solver will react as quickly as possible to align the attachments. When false, torque dependant on MaxTorque, MaxAngularVelocity, and Responsiveness.
- MaxAngularVelocity (float) - The maximum angular velocity the constraint can use to reach its goal.
- MaxTorque (float) - The maximum torque the constraint can use to reach its goal.
- Responsiveness (float) - Used to control how quickly the constraint will reach its goal. Higher values will cause the attachment to align quicker. Value can be between 5 and 200.
- Attachment0 (Attachment) - The first attachment of the constraint.
- Attachment1 (Attachment) - The second attachment of the constraint.
