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