Physics Constraints (bge.constraints)

Bullet Physics provides collision detection and rigid body dynamics for the Blender Game Engine.

Features:

Vehicle simulation.
Rigid body constraints: hinge and point to point (ball socket).
Access to internal physics settings, like deactivation time, and debugging features

Note

Note about parameter settings

Since this API is not well documented, it can be unclear what kind of values to use for setting parameters. In general, damping settings should be in the range of 0 to 1 and stiffness settings should not be much higher than about 10.

Examples

Basic Physics Constraint

Example of how to create a hinge Physics Constraint between two objects.

from bge import logic
from bge import constraints

# get object list
objects = logic.getCurrentScene().objects

# get object named Object1 and Object 2
object_1 = objects["Object1"]
object_2 = objects["Object2"]

# want to use Edge constraint type
constraint_type = 2

# get Object1 and Object2 physics IDs
physics_id_1 = object_1.getPhysicsId()
physics_id_2 = object_2.getPhysicsId()

# use bottom right edge of Object1 for hinge position
edge_position_x = 1.0
edge_position_y = 0.0
edge_position_z = -1.0

# rotate the pivot z axis about 90 degrees
edge_angle_x = 0.0
edge_angle_y = 0.0
edge_angle_z = 90.0

# create an edge constraint
constraints.createConstraint(physics_id_1, physics_id_2,
                             constraint_type,
                             edge_position_x, edge_position_y, edge_position_z,
                             edge_angle_x, edge_angle_y, edge_angle_z)

Functions

bge.constraints.createConstraint(physicsid_1, physicsid_2, constraint_type, pivot_x=0.0, pivot_y=0.0, pivot_z=0.0, axis_x=0.0, axis_y=0.0, axis_z=0.0, flag=0)

Creates a constraint.

Parameters

physicsid_1 (int) – The physics id of the first object in constraint.
physicsid_2 (int) – The physics id of the second object in constraint.
constraint_type (int) – The type of the constraint, see Create Constraint Constants.
pivot_x (float) – Pivot X position. (optional)
pivot_y (float) – Pivot Y position. (optional)
pivot_z (float) – Pivot Z position. (optional)
axis_x (float) – X axis angle in degrees. (optional)
axis_y (float) – Y axis angle in degrees. (optional)
axis_z (float) – Z axis angle in degrees. (optional)
flag (int) – 128 to disable collision between linked bodies. (optional)

Returns

A constraint wrapper.

Return type

KX_ConstraintWrapper

bge.constraints.createVehicle(physicsid)

Creates a vehicle constraint.

Parameters: physicsid (int) – The physics id of the chassis object in constraint.
Returns: A vehicle constraint wrapper.
Return type: KX_VehicleWrapper

bge.constraints.exportBulletFile(filename)

Exports a file representing the dynamics world (usually using .bullet extension).

See Bullet binary serialization.

Parameters: filename (str) – File path.

bge.constraints.getAppliedImpulse(constraintId)

Parameters: constraintId (int) – The id of the constraint.
Returns: The most recent applied impulse.
Return type: float

bge.constraints.getVehicleConstraint(constraintId)

Parameters: constraintId (int) – The id of the vehicle constraint.
Returns: A vehicle constraint object.
Return type: KX_VehicleWrapper

bge.constraints.getCharacter(gameobj)

Parameters: gameobj (KX_GameObject) – The game object with the character physics.
Returns: Character wrapper.
Return type: KX_CharacterWrapper

bge.constraints.removeConstraint(constraintId)

Removes a constraint.

Parameters: constraintId (int) – The id of the constraint to be removed.

bge.constraints.setContactBreakingTreshold(breakingTreshold)

Note

Reasonable default is 0.02 (if units are meters)

Sets tresholds to do with contact point management.

Parameters: breakingTreshold (float) – The new contact breaking treshold.

bge.constraints.setDeactivationAngularTreshold(angularTreshold)

Sets the angular velocity treshold.

Parameters: angularTreshold (float) – New deactivation angular treshold.

bge.constraints.setDeactivationLinearTreshold(linearTreshold)

Sets the linear velocity treshold.

Parameters: linearTreshold (float) – New deactivation linear treshold.

bge.constraints.setDeactivationTime(time)

Sets the time after which a resting rigidbody gets deactived.

Parameters: time (float) – The deactivation time.

bge.constraints.setERPNonContact(erp)

Sets the Error Reduction Parameter (ERP) for non-contact constraints. The Error Reduction Parameter (ERP) specifies what proportion of the joint error will be fixed during the next simulation step. If ERP = 0.0 then no correcting force is applied and the bodies will eventually drift apart as the simulation proceeds. If ERP = 1.0 then the simulation will attempt to fix all joint error during the next time step. However, setting ERP = 1.0 is not recommended, as the joint error will not be completely fixed due to various internal approximations. A value of ERP = 0.1 to 0.8 is recommended.

Parameters: erp (float [0.0, 1.0]) – The ERP parameter for non-contact constraints.

bge.constraints.setERPContact(erp2)

Sets the Error Reduction Parameter (ERP) for contact constraints. The Error Reduction Parameter (ERP) specifies what proportion of the joint error will be fixed during the next simulation step. If ERP = 0.0 then no correcting force is applied and the bodies will eventually drift apart as the simulation proceeds. If ERP = 1.0 then the simulation will attempt to fix all joint error during the next time step. However, setting ERP = 1.0 is not recommended, as the joint error will not be completely fixed due to various internal approximations. A value of ERP = 0.1 to 0.8 is recommended.

Parameters: erp2 (float [0.0, 1.0]) – The ERP parameter for contact constraints.

bge.constraints.setCFM(cfm)

Sets the Constraint Force Mixing (CFM) for soft constraints. If the Constraint Force Mixing (CFM) is set to zero, the constraint will be hard. If CFM is set to a positive value, it will be possible to violate the constraint by pushing on it (for example, for contact constraints by forcing the two contacting objects together). In other words the constraint will be soft, and the softness will increase as CFM increases.

Parameters: cfm (float [0.0, 10000.0]) – The CFM parameter for soft constraints.

bge.constraints.setDebugMode(mode)

Sets the debug mode.

Parameters: mode (int) – The new debug mode, see Debug Mode Constants.

bge.constraints.setGravity(x, y, z)

Sets the gravity force.

Parameters

x (float) – Gravity X force.
y (float) – Gravity Y force.
z (float) – Gravity Z force.

Sets the linear air damping for rigidbodies.

bge.constraints.setNumIterations(numiter)

Sets the number of iterations for an iterative constraint solver.

Parameters: numiter (int) – New number of iterations.

bge.constraints.setNumTimeSubSteps(numsubstep)

Sets the number of substeps for each physics proceed. Tradeoff quality for performance.

Parameters: numsubstep (int) – New number of substeps.

bge.constraints.setSolverDamping(damping)

Note

Very experimental, not recommended

Sets the damper constant of a penalty based solver.

Parameters: damping (float) – New damping for the solver.

bge.constraints.setSolverTau(tau)

Note

Very experimental, not recommended

Sets the spring constant of a penalty based solver.

Parameters: tau (float) – New tau for the solver.

bge.constraints.setSolverType(solverType)

Note

Very experimental, not recommended

Sets the solver type.

Parameters: solverType (int) – The new type of the solver.

bge.constraints.setSorConstant(sor)

Note

Very experimental, not recommended

Sets the successive overrelaxation constant.

Parameters: sor (float) – New sor value.

Constants

bge.constraints.error

Symbolic constant string that indicates error.

Type: str

Debug Mode Constants

Debug mode to be used with setDebugMode().

bge.constraints.DBG_NODEBUG

No debug.

Type: integer

bge.constraints.DBG_DRAWWIREFRAME

Draw wireframe in debug.

Type: integer

bge.constraints.DBG_DRAWAABB

Draw Axis Aligned Bounding Box in debug.

Type: integer

bge.constraints.DBG_DRAWFREATURESTEXT

Draw features text in debug.

Type: integer

bge.constraints.DBG_DRAWCONTACTPOINTS

Draw contact points in debug.

Type: integer

bge.constraints.DBG_NOHELPTEXT

Debug without help text.

Type: integer

bge.constraints.DBG_DRAWTEXT

Draw text in debug.

Type: integer

bge.constraints.DBG_PROFILETIMINGS

Draw profile timings in debug.

Type: integer

bge.constraints.DBG_ENABLESATCOMPARISION

Enable sat comparision in debug.

Type: integer

bge.constraints.DBG_DISABLEBULLETLCP

Disable Bullet LCP.

Type: integer

bge.constraints.DBG_ENABLECCD

Enable Continous Collision Detection in debug.

Type: integer

bge.constraints.DBG_DRAWCONSTRAINTS

Draw constraints in debug.

Type: integer

bge.constraints.DBG_DRAWCONSTRAINTLIMITS

Draw constraint limits in debug.

Type: integer

bge.constraints.DBG_FASTWIREFRAME

Draw a fast wireframe in debug.

Type: integer

Create Constraint Constants

Constraint type to be used with createConstraint().

bge.constraints.POINTTOPOINT_CONSTRAINT

Type: integer

bge.constraints.LINEHINGE_CONSTRAINT

Type: integer

bge.constraints.ANGULAR_CONSTRAINT

Type: integer

bge.constraints.CONETWIST_CONSTRAINT

Type: integer

bge.constraints.VEHICLE_CONSTRAINT

Type: integer

bge.constraints.GENERIC_6DOF_CONSTRAINT

Type: integer