=bmesh= merge from trunk at r36153
[blender.git] / source / gameengine / PyDoc / PhysicsConstraints.py
1 # $Id$
2 """
3 Documentation for the PhysicsConstraints module.
4 ================================================
5
6 Example::
7         
8         
9         #  Adding a point constraint  #
10         ###############################
11         
12         
13         # import BGE internal module
14         import PhysicsConstraints
15         
16         # get object list
17         obj_list = GameLogic.getCurrentScene().objects
18         
19         # get object named Obj_1
20         root = obj_list["root"]
21         obj = obj_list["obj"]
22
23         # get object physics ID
24         phido = obj.getPhysicsId()
25         
26         # get root physics ID
27         phidr = root.getPhysicsId()
28
29         # want to use point constraint type
30         constraint_type = 1
31         
32         # Use bottom right front corner of object for point constraint position
33         point_pos_x = 1.0
34         point_pos_y = -1.0
35         point_pos_z = -1.0
36         
37         # create a point constraint
38         const = PhysicsConstraints.createConstraint( phido, phidr, constraint_type, point_pos_x, point_pos_y, point_pos_z)
39
40         # stores the new constraint ID to be used later
41         obj["constraint_ID"] = const.getConstraintId()  
42         
43         
44 Example::
45         
46         
47         #  Removing a point constraint  #
48         #################################
49         
50         
51         # import BGE internal module
52         import PhysicsConstraints
53         
54         # get object list
55         obj_list = GameLogic.getCurrentScene().objects
56         
57         # get object 1
58         obj = obj_list["obj"]
59         
60         # get constraint ID that was saved as an obj property
61         # when the constraint was created
62         constraint_ID = obj["constraint_ID"]
63         
64         # remove constraint
65         PhysicsConstraints.removeConstraint(constraint_ID)
66
67 """
68
69 def createConstraint(obj_PhysicsID, root_PhysicsID, constraintType, pointPos_x, pointPos_y, pointPos_z, edgePos_x, edgePos_y, edgePos_z, edgeAngle_x, edgeAngle_y, edgeAngle_z):
70         """     
71         Create a point constraint between two objects, an edge constraint between two objects, or a vehicle constraint on an object.
72         
73         You only have to input the needed parammeters depending on the type of constraint you are trying to create.
74         
75
76         B{Point Constraint} ::
77         
78                 While creating a point constraint, the "pointPos" values define where you want the pivot point to be located.
79                 If you are creating a point constraint be sure to assing the integer "1" as the constraintType value.
80         
81                 Parameters to use:
82                 obj_PhysicsID, root_PhysicsID, constraintType, pointPos_x, pointPos_y, pointPos_z
83         
84         B{Edge Constraint} ::
85                 
86                 While creating an edge constraint, the "edgePos" values define where you want the center of the edge constraint to be.
87                 Also, the "edgeAngle" values define in which direction you want the edge constraint to point (As a 3 dimensions vector).
88                 If you want to create an edge constraint be sure to assing the integer "2" as the constraintType value.
89
90                 Parameters to use:
91                 obj_PhysicsID, root_PhysicsID, constraintType, edgePos_x, edgePos_y, edgePos_z, edgeAngle_x, edgeAngle_y, edgeAngle_z}          
92         
93         B{Vehicle Constraint} ::
94                 
95                 While creating a point constraint, the "pointPos" values define where you want the pivot point to be located.
96                 If you want to create an edge constraint be sure to assing the integer "0" as the constraintType value.
97
98                 Parameters to use :
99                 obj_PhysicsID, root_PhysicsID, constraintType
100         
101         @type obj_PhysicsID: integer
102         @param obj_PhysicsID: The physic ID of the first object to constraint.
103
104         @type root_PhysicsID: integer
105         @param root_PhysicsID: The physic ID of the second object to constraint.
106
107         @type constraintType: integer
108         @param constraintType: The type of constraint.
109
110         @type pointPos_x: float
111         @param pointPos_x: The X position of the point constraint.
112
113         @type pointPos_y: float
114         @param pointPos_y: The Y position of the point constraint.
115
116         @type pointPos_z: float
117         @param pointPos_z: The Z position of the point constraint.
118
119         @type edgePos_x: float
120         @param edgePos_x: The X value of the center of the edge constraint.
121
122         @type edgePos_y: float
123         @param edgePos_y: The Y value of the center of the edge constraint.
124
125         @type edgePos_z: float
126         @param edgePos_z: The Z value of the center of the edge constraint.
127
128         @type edgeAngle_x: float
129         @param edgeAngle_x: The X value of the edge's orientation vector.
130
131         @type edgeAngle_y: float
132         @param edgeAngle_y: The Y value of the edge's orientation vector.
133
134         @type edgeAngle_z: float
135         @param edgeAngle_z: The Z value of the edge's orientation vector.
136
137         @rtype: integer
138         @return: The created constraint ID
139         """
140         
141
142 def getAppliedImpulse(constraint_ID):
143         """
144         Returns the applied impulse.
145         
146         @param constraint_ID: The constraint ID that was saved on the creation of the constraint.
147         @type constraint_ID: integer
148         @rtype: float
149         @return: Measure the stress on a constraint.
150         """
151
152
153 def getVehicleConstraint(constraint_ID):
154         """
155         Returns the vehicle constraint ID.
156         
157         @param constraint_ID: The constraint ID that was saved on the creation of the constraint.
158         @type constraint_ID: integer
159         @rtype: integer
160         """
161 def removeConstraint(constraint_ID):
162         """
163         
164         Removes the constraint between 2 game objects (point and edge constraints).
165         
166         It does not remove vehicle constraints.
167         
168         @param constraint_ID: The constraint ID that was saved on the creation of the constraint.
169         @type constraint_ID: integer
170         """
171 def setDeactivationLinearTreshold(linearTreshold):
172         """
173         
174         Sets the linear velocity that an object must be below before the deactivation timer can start.
175         
176         This affects every object in the scene, except for game objects that have 'No sleeping' turned on.
177         
178         @param linearTreshold: The linear velocity.
179         @type linearTreshold: float
180         """
181 def setDeactivationAngularTreshold(angularTreshold):
182         """
183         
184         Sets the angular velocity that an object must be below before the deactivation timer can start.
185         
186         This affects every object in the scene, except for game objects that have 'No sleeping' turned on.
187         
188         @param angularTreshold: The angular velocity.
189         @type angularTreshold: float
190         """
191 def setDeactivationTime(time):
192         """
193         
194         Time (in seconds) after objects with velocity less then thresholds (see below) are deactivated.
195         
196         This affects every object in the scene, except for game objects that have 'No sleeping' turned on.
197         
198         This function is directly related with the 2 above functions.
199         
200         
201         @param time: The time in seconds.
202         @type time: float
203         """
204 def setGravity(gx, gy, gz):
205         """
206         Sets the gravity for the actual scene only.
207         
208         All other scenes remain unaffected.
209         
210         This affects every object in the scene that has physics enabled.
211         
212         @param gx: The force of gravity on world x axis.
213         @type gx: float
214         @param gy: The force of gravity on world y axis.
215         @type gy: float
216         @param gz: The force of gravity on world z axis.
217         @type gz: float
218         """
219 def setLinearAirDamping(damping):
220         """
221         
222         Sets the linear air resistance for all objects in the scene.
223         
224         @param damping: The linear air resistance.
225         @type damping: float
226         """
227 def setNumIterations(numIter):
228         """
229         Sets the number of times an iterative constraint solver is repeated.
230         
231         Increasing the number of iterations improves the constraint solver at the cost of performances & the speed of the game engine.
232         
233         @param numIter: The number of timesubsteps. (Input 0 to suspend simulation numSubStep)
234         @type numIter: integer
235         """
236 def setNumTimeSubSteps(numSubStep):
237         """
238         Set the quality of the entire physics simulation including collision detection and constraint solver.
239         
240         Increase the number of time substeps to improves the quality of the entire physics simulation at the cost of the performance & the speed of the game engine.
241         
242         @param numSubStep: The number of timesubsteps. (Input 0 to suspend simulation numSubStep)
243         @type numSubStep: integer
244         """
245 #def setDebugMode():
246 #       """
247 #       
248 #       
249 #       
250 #       @param numIter: 
251 #       @type numIter: 
252 #       """
253 #def setCcdMode():
254 #       """
255 #       Does something
256 #       
257 #       @rtype: 
258 #       """
259 #def setContactBreakingTreshold():
260 #       """
261 #       Does something
262 #       
263 #       @rtype: 
264 #       """
265 #def setSolverDamping():
266 #       """
267 #       Does something
268 #       
269 #       @rtype: 
270 #       """
271 #def setSolverTau():
272 #       """
273 #       Does something
274 #       
275 #       @rtype: 
276 #       """
277 #def setSolverType():
278 #       """
279 #       Does something
280 #       
281 #       @rtype: 
282 #       """
283 #def setSorConstant():
284 #       """
285 #       Does something
286 #       
287 #       @rtype: 
288 #       """
289 #def setUseEpa():
290 #       """
291 #       Does something
292 #       
293 #       @rtype: 
294 #       """