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