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