BGE patch: Add PyDoc for new logic bricks, set exception message on Py error, remove...
[blender.git] / source / gameengine / PyDoc / KX_ObjectActuator.py
1 # $Id$
2 # Documentation for KX_ObjectActuator
3 from SCA_IActuator import *
4
5 class KX_ObjectActuator(SCA_IActuator):
6         """
7         The object actuator ("Motion Actuator") applies force, torque, displacement, angular displacement,
8         velocity, or angular velocity to an object.
9         Servo control allows to regulate force to achieve a certain speed target.
10         """
11         def getForce():
12                 """
13                 Returns the force applied by the actuator.
14                 
15                 @rtype: list [fx, fy, fz, local]
16                 @return: A four item list, containing the vector force, and a flag specifying whether the force is local.
17                 """
18         def setForce(fx, fy, fz, local):
19                 """
20                 Sets the force applied by the actuator.
21                 
22                 @type fx: float
23                 @param fx: the x component of the force.
24                 @type fy: float
25                 @param fy: the z component of the force.
26                 @type fz: float
27                 @param fz: the z component of the force.
28                 @type local: boolean
29                 @param local: - False: the force is applied in world coordinates.
30                               - True: the force is applied in local coordinates.
31                 """
32         def getTorque():
33                 """
34                 Returns the torque applied by the actuator.
35                 
36                 @rtype: list [S{Tau}x, S{Tau}y, S{Tau}z, local]
37                 @return: A four item list, containing the vector torque, and a flag specifying whether
38                          the torque is applied in local coordinates (True) or world coordinates (False)
39                 """
40         def setTorque(tx, ty, tz, local):
41                 """
42                 Sets the torque applied by the actuator.
43                 
44                 @type tx: float
45                 @param tx: the x component of the torque.
46                 @type ty: float
47                 @param ty: the z component of the torque.
48                 @type tz: float
49                 @param tz: the z component of the torque.
50                 @type local: boolean
51                 @param local: - False: the torque is applied in world coordinates.
52                               - True: the torque is applied in local coordinates.
53                 """
54         def getDLoc():
55                 """
56                 Returns the displacement vector applied by the actuator.
57                 
58                 @rtype: list [dx, dy, dz, local]
59                 @return: A four item list, containing the vector displacement, and whether
60                          the displacement is applied in local coordinates (True) or world
61                          coordinates (False)
62                 """
63         def setDLoc(dx, dy, dz, local):
64                 """
65                 Sets the displacement vector applied by the actuator.
66                 
67                 Since the displacement is applied every frame, you must adjust the displacement
68                 based on the frame rate, or you game experience will depend on the player's computer
69                 speed.
70                 
71                 @type dx: float
72                 @param dx: the x component of the displacement vector.
73                 @type dy: float
74                 @param dy: the z component of the displacement vector.
75                 @type dz: float
76                 @param dz: the z component of the displacement vector.
77                 @type local: boolean
78                 @param local: - False: the displacement vector is applied in world coordinates.
79                               - True: the displacement vector is applied in local coordinates.
80                 """
81         def getDRot():
82                 """
83                 Returns the angular displacement vector applied by the actuator.
84                 
85                 @rtype: list [dx, dy, dz, local]
86                 @return: A four item list, containing the angular displacement vector, and whether
87                          the displacement is applied in local coordinates (True) or world
88                          coordinates (False)
89                 """
90         def setDRot(dx, dy, dz, local):
91                 """
92                 Sets the angular displacement vector applied by the actuator.
93                 
94                 Since the displacement is applied every frame, you must adjust the displacement
95                 based on the frame rate, or you game experience will depend on the player's computer
96                 speed.
97                 
98                 @type dx: float
99                 @param dx: the x component of the angular displacement vector.
100                 @type dy: float
101                 @param dy: the z component of the angular displacement vector.
102                 @type dz: float
103                 @param dz: the z component of the angular displacement vector.
104                 @type local: boolean
105                 @param local: - False: the angular displacement vector is applied in world coordinates.
106                               - True: the angular displacement vector is applied in local coordinates.
107                 """
108         def getLinearVelocity():
109                 """
110                 Returns the linear velocity applied by the actuator.
111                 For the servo control actuator, this is the target speed.
112                 
113                 @rtype: list [vx, vy, vz, local]
114                 @return: A four item list, containing the vector velocity, and whether
115                          the velocity is applied in local coordinates (True) or world
116                              coordinates (False)
117                 """
118         def setLinearVelocity(vx, vy, vz, local):
119                 """
120                 Sets the linear velocity applied by the actuator.
121                 For the servo control actuator, sets the target speed.
122                 
123                 @type vx: float
124                 @param vx: the x component of the velocity vector.
125                 @type vy: float
126                 @param vy: the z component of the velocity vector.
127                 @type vz: float
128                 @param vz: the z component of the velocity vector.
129                 @type local: boolean
130                 @param local: - False: the velocity vector is in world coordinates.
131                               - True: the velocity vector is in local coordinates.
132                 """
133         def getAngularVelocity():
134                 """
135                 Returns the angular velocity applied by the actuator.
136                 
137                 @rtype: list [S{omega}x, S{omega}y, S{omega}z, local]
138                 @return: A four item list, containing the vector velocity, and whether
139                          the velocity is applied in local coordinates (True) or world
140                          coordinates (False)
141                 """
142         def setAngularVelocity(wx, wy, wz, local):
143                 """
144                 Sets the angular velocity applied by the actuator.
145                 
146                 @type wx: float
147                 @param wx: the x component of the velocity vector.
148                 @type wy: float
149                 @param wy: the z component of the velocity vector.
150                 @type wz: float
151                 @param wz: the z component of the velocity vector.
152                 @type local: boolean
153                 @param local: - False: the velocity vector is applied in world coordinates.
154                               - True: the velocity vector is applied in local coordinates.
155                 """
156         def getDamping():
157                 """
158                 Returns the damping parameter of the servo controller.
159                 
160                 @rtype: integer
161                 @return: the time constant of the servo controller in frame unit.
162                 """
163         def setDamping(damp):
164                 """
165                 Sets the damping parameter of the servo controller.
166                 
167                 @type damp: integer
168                 @param damp: the damping parameter in frame unit.
169                 """
170         def getForceLimitX():
171                 """
172                 Returns the min/max force limit along the X axis used by the servo controller.
173                 
174                 @rtype: list [min, max, enabled]
175                 @return: A three item list, containing the min and max limits of the force as float
176                          and whether the limits are active(true) or inactive(true)
177                 """
178         def setForceLimitX(min, max, enable):
179                 """
180                 Sets the min/max force limit along the X axis and activates or deactivates the limits in the servo controller.
181                 
182                 @type min: float
183                 @param min: the minimum value of the force along the X axis.
184                 @type max: float
185                 @param max: the maximum value of the force along the X axis.
186                 @type enable: boolean
187                 @param enable: - True: the force will be limited to the min/max
188                                - False: the force will not be limited                          
189                 """
190         def getForceLimitY():
191                 """
192                 Returns the min/max force limit along the Y axis used by the servo controller.
193                 
194                 @rtype: list [min, max, enabled]
195                 @return: A three item list, containing the min and max limits of the force as float
196                          and whether the limits are active(true) or inactive(true)
197                 """
198         def setForceLimitY(min, max, enable):
199                 """
200                 Sets the min/max force limit along the Y axis and activates or deactivates the limits in the servo controller.
201                 
202                 @type min: float
203                 @param min: the minimum value of the force along the Y axis.
204                 @type max: float
205                 @param max: the maximum value of the force along the Y axis.
206                 @type enable: boolean
207                 @param enable: - True: the force will be limited to the min/max
208                                - False: the force will not be limited                          
209                 """
210         def getForceLimitZ():
211                 """
212                 Returns the min/max force limit along the Z axis used by the servo controller.
213                 
214                 @rtype: list [min, max, enabled]
215                 @return: A three item list, containing the min and max limits of the force as float
216                          and whether the limits are active(true) or inactive(true)
217                 """
218         def setForceLimitZ(min, max, enable):
219                 """
220                 Sets the min/max force limit along the Z axis and activates or deactivates the limits in the servo controller.
221                 
222                 @type min: float
223                 @param min: the minimum value of the force along the Z axis.
224                 @type max: float
225                 @param max: the maximum value of the force along the Z axis.
226                 @type enable: boolean
227                 @param enable: - True: the force will be limited to the min/max
228                                - False: the force will not be limited                          
229                 """
230         def getPID():
231                 """
232                 Returns the PID coefficient of the servo controller.
233                 
234                 @rtype: list [P, I, D]
235                 @return: A three item list, containing the PID coefficient as floats:
236                          P : proportional coefficient
237                          I : Integral coefficient
238                          D : Derivate coefficient
239                 """
240         def setPID(P, I, D):
241                 """
242                 Sets the PID coefficients of the servo controller.
243                 
244                 @type P: flat
245                 @param P: proportional coefficient
246                 @type I: float
247                 @param I: Integral coefficient
248                 @type D: float
249                 @param D: Derivate coefficient
250                 """
251
252