14ebc61dbf5002434dc499faffcd5e0e4ca5f128
[blender.git] / doc / python_api / rst / bge.constraints.rst
1
2 Physics Constraints (bge.constraints)
3 =====================================
4
5 .. module:: bge.constraints
6
7 .. literalinclude:: ../examples/bge.constraints.py
8    :language: rest
9    :lines: 2-4
10
11 .. literalinclude:: ../examples/bge.constraints.py
12    :lines: 6-
13
14 .. function:: createConstraint(physicsid_1, physicsid_2, constraint_type, pivot_X, pivot_y, pivot_z, axis_x, axis_y, axis_z, flag)
15
16    Creates a constraint.
17
18    Constraints types:
19       - :class:`POINTTOPOINT_CONSTRAINT`
20       - :class:`LINEHINGE_CONSTRAINT`
21       - :class:`ANGULAR_CONSTRAINT`
22       - :class:`CONETWIST_CONSTRAINT`
23       - :class:`VEHICLE_CONSTRAINT`
24       - :class:`GENERIC_6DOF_CONSTRAINT` 
25
26    :arg physicsid_1: the physics id of the first object in constraint.
27    :type physicsid_1: int
28
29    :arg physicsid_2: the physics id of the second object in constraint.
30    :type physicsid_2: int
31
32    :arg constrainttype: the type of the constraint.
33    :type constrainttype: int
34
35    :arg pivot_X: pivot X position (optional).
36    :type pivot_X: float
37
38    :arg pivot_Y: pivot Y position (optional).
39    :type pivot_Y: float
40
41    :arg pivot_Z: pivot Z position (optional).
42    :type pivot_Z: float
43
44    :arg axis_X: X axis angle in degrees (optional).
45    :type axis_X: float
46
47    :arg axis_Y: Y axis angle in degrees (optional).
48    :type axis_Y: float
49
50    :arg axis_Z: Z axis angle in degrees (optional).
51    :type axis_Z: float
52
53    :arg flag: 128 to disable collision between linked bodies (optional).
54    :type flag: int
55
56    :return: a constraint wrapper.
57    :rtype: :class:`bge.types.KX_ConstraintWrapper`
58
59 .. attribute:: error
60
61    Symbolic constant string that indicates error.
62
63 .. function:: exportBulletFile(filename)
64
65    export a .bullet file
66
67    :arg filename: File name
68    :type filename: string
69
70 .. function:: getAppliedImpulse(constraintId)
71
72    :arg constraintId: The id of the constraint.
73    :type constraintId: int
74
75    :return: the most recent applied impulse.
76    :rtype: float
77
78 .. function:: getVehicleConstraint(constraintId)
79
80    :arg constraintId: The id of the vehicle constraint.
81    :type constraintId: int
82
83    :return: a vehicle constraint object.
84    :rtype: :class:`bge.types.KX_VehicleWrapper`
85
86 .. function:: getCharacter(gameobj)
87
88    :arg gameobj: The game object with the character physics.
89    :type gameobj: :class:`bge.types.KX_GameObject`
90
91    :return: character wrapper
92    :rtype: :class:`bge.types.KX_CharacterWrapper`
93
94 .. function:: removeConstraint(constraintId)
95
96    Removes a constraint.
97
98    :arg constraintId: The id of the constraint to be removed.
99    :type constraintId: int
100
101 .. function:: setCcdMode(ccdMode)
102
103    .. note::
104       Very experimental, not recommended
105
106    Sets the CCD (Continous Colision Detection) mode in the Physics Environment.
107
108    :arg ccdMode: The new CCD mode.
109    :type ccdMode: int
110
111 .. function:: setContactBreakingTreshold(breakingTreshold)
112
113    .. note::
114       Reasonable default is 0.02 (if units are meters)
115
116    Sets tresholds to do with contact point management.
117
118    :arg breakingTreshold: The new contact breaking treshold.
119    :type breakingTreshold: float
120
121 .. function:: setDeactivationAngularTreshold(angularTreshold)
122
123    Sets the angular velocity treshold.
124
125    :arg angularTreshold: New deactivation angular treshold.
126    :type angularTreshold: float
127
128 .. function:: setDeactivationLinearTreshold(linearTreshold)
129
130    Sets the linear velocity treshold.
131
132    :arg linearTreshold: New deactivation linear treshold.
133    :type linearTreshold: float
134
135 .. function:: setDeactivationTime(time)
136
137    Sets the time after which a resting rigidbody gets deactived.
138
139    :arg time: The deactivation time.
140    :type time: float
141
142 .. function:: setDebugMode(mode)
143
144    Sets the debug mode.
145
146    Debug modes:
147       - :class:`DBG_NODEBUG`
148       - :class:`DBG_DRAWWIREFRAME`
149       - :class:`DBG_DRAWAABB`
150       - :class:`DBG_DRAWFREATURESTEXT`
151       - :class:`DBG_DRAWCONTACTPOINTS`
152       - :class:`DBG_NOHELPTEXT`
153       - :class:`DBG_DRAWTEXT`
154       - :class:`DBG_PROFILETIMINGS`
155       - :class:`DBG_ENABLESATCOMPARISION`
156       - :class:`DBG_DISABLEBULLETLCP`
157       - :class:`DBG_ENABLECCD`
158       - :class:`DBG_DRAWCONSTRAINTS`
159       - :class:`DBG_DRAWCONSTRAINTLIMITS`
160       - :class:`DBG_FASTWIREFRAME`
161
162    :arg mode: The new debug mode.
163    :type mode: int
164
165 .. function:: setGravity(x, y, z)
166
167    Sets the gravity force.
168
169    :arg x: Gravity X force.
170    :type x: float
171
172    :arg y: Gravity Y force.
173    :type y: float
174
175    :arg z: Gravity Z force.
176    :type z: float
177
178 .. function:: setLinearAirDamping(damping)
179
180    .. note::
181       Not implemented.
182
183    Sets the linear air damping for rigidbodies.
184
185 .. function:: setNumIterations(numiter)
186
187    Sets the number of iterations for an iterative constraint solver.
188
189    :arg numiter: New number of iterations.
190    :type numiter: int
191
192 .. function:: setNumTimeSubSteps(numsubstep)
193
194    Sets the number of substeps for each physics proceed. Tradeoff quality for performance.
195
196    :arg numsubstep: New number of substeps.
197    :type numsubstep: int
198
199 .. function:: setSolverDamping(damping)
200
201    .. note::
202       Very experimental, not recommended
203
204    Sets the damper constant of a penalty based solver.
205
206    :arg damping: New damping for the solver.
207    :type damping: float
208
209 .. function:: setSolverTau(tau)
210
211    .. note::
212       Very experimental, not recommended
213
214    Sets the spring constant of a penalty based solver.
215
216    :arg tau: New tau for the solver.
217    :type tau: float
218
219 .. function:: setSolverType(solverType)
220
221    .. note::
222       Very experimental, not recommended
223
224    Sets the solver type.
225
226    :arg solverType: The new type of the solver.
227    :type solverType: int
228
229 .. function:: setSorConstant(sor)
230
231    .. note::
232       Very experimental, not recommended
233
234    Sets the successive overrelaxation constant.
235
236    :arg sor: New sor value.
237    :type sor: float
238
239 .. function:: setUseEpa(epa)
240
241    Not implemented.
242
243 .. data:: DBG_NODEBUG
244
245    .. note::
246       Debug mode to be used with function :class:`setDebugMode`
247
248    No debug.
249
250 .. data:: DBG_DRAWWIREFRAME
251
252    .. note::
253       Debug mode to be used with function :class:`setDebugMode`
254
255    Draw wireframe in debug.
256
257 .. data:: DBG_DRAWAABB
258
259    .. note::
260       Debug mode to be used with function :class:`setDebugMode`
261
262    Draw Axis Aligned Bounding Box in debug.
263
264 .. data:: DBG_DRAWFREATURESTEXT
265
266    .. note::
267       Debug mode to be used with function :class:`setDebugMode`
268
269    Draw freatures text in debug.
270
271 .. data:: DBG_DRAWCONTACTPOINTS
272
273    .. note::
274       Debug mode to be used with function :class:`setDebugMode`
275
276    Draw contact points in debug.
277
278 .. data:: DBG_NOHELPTEXT
279
280    .. note::
281       Debug mode to be used with function :class:`setDebugMode`
282
283    Debug without help text.
284
285 .. data:: DBG_DRAWTEXT
286
287    .. note::
288       Debug mode to be used with function :class:`setDebugMode`
289
290    Draw text in debug.
291
292 .. data:: DBG_PROFILETIMINGS
293
294    .. note::
295       Debug mode to be used with function :class:`setDebugMode`
296
297    Draw profile timings in debug.
298
299 .. data:: DBG_ENABLESATCOMPARISION
300
301    .. note::
302       Debug mode to be used with function :class:`setDebugMode`
303
304    Enable sat comparision in debug.
305
306 .. data:: DBG_DISABLEBULLETLCP
307
308    .. note::
309       Debug mode to be used with function :class:`setDebugMode`
310
311    Disable Bullet LCP.
312
313 .. data:: DBG_ENABLECCD
314
315    .. note::
316       Debug mode to be used with function :class:`setDebugMode`
317
318    Enable Continous Colision Detection in debug.
319
320 .. data:: DBG_DRAWCONSTRAINTS
321
322    .. note::
323       Debug mode to be used with function :class:`setDebugMode`
324
325    Draw constraints in debug.
326
327 .. data:: DBG_DRAWCONSTRAINTLIMITS
328
329    .. note::
330       Debug mode to be used with function :class:`setDebugMode`
331
332    Draw constraint limits in debug.
333
334 .. data:: DBG_FASTWIREFRAME
335
336    .. note::
337       Debug mode to be used with function :class:`setDebugMode`
338
339    Draw a fast wireframe in debug.
340
341 .. data:: POINTTOPOINT_CONSTRAINT
342
343    .. note::
344       Constraint type to be used with function :class:`createConstraint`
345
346    .. to do
347
348 .. data:: LINEHINGE_CONSTRAINT
349
350    .. note::
351       Constraint type to be used with function :class:`createConstraint`
352
353    .. to do
354
355 .. data:: ANGULAR_CONSTRAINT
356
357    .. note::
358       Constraint type to be used with function :class:`createConstraint`
359
360    .. to do
361
362 .. data:: CONETWIST_CONSTRAINT
363
364    .. note::
365        Constraint type to be used with function :class:`createConstraint`
366
367    .. to do
368
369 .. data:: VEHICLE_CONSTRAINT
370
371    .. note::
372       Constraint type to be used with function :class:`createConstraint`
373
374    .. to do
375
376 .. data:: GENERIC_6DOF_CONSTRAINT
377
378    .. note::
379       Constraint type to be used with function :class:`createConstraint`
380
381    .. to do