BGE API cleanup: ConstraintActuator.
[blender.git] / source / gameengine / PyDoc / KX_ConstraintActuator.py
1 # $Id$
2 # Documentation for KX_ConstraintActuator
3 from SCA_IActuator import *
4
5 class KX_ConstraintActuator(SCA_IActuator):
6         """
7         A constraint actuator limits the position, rotation, distance or orientation of an object.
8         
9         Properties:
10         
11         @ivar damp: time constant of the constraint expressed in frame (not use by Force field constraint)
12         @type damp: integer
13         
14         @ivar rotDamp: time constant for the rotation expressed in frame (only for the distance constraint)
15                        0 = use damp for rotation as well
16         @type rotDamp: integer
17         
18         @ivar direction: the reference direction in world coordinate for the orientation constraint
19         @type direction: 3-tuple of float: [x,y,z]
20         
21         @ivar option: Binary combination of the following values:
22                       Applicable to Distance constraint:
23                                         KX_ACT_CONSTRAINT_NORMAL    (  64) : Activate alignment to surface
24                                         KX_ACT_CONSTRAINT_DISTANCE  ( 512) : Activate distance control
25                                         KX_ACT_CONSTRAINT_LOCAL         (1024) : direction of the ray is along the local axis
26                                   Applicable to Force field constraint:                                 
27                                         KX_ACT_CONSTRAINT_DOROTFH   (2048) : Force field act on rotation as well
28                                   Applicable to both:
29                                         KX_ACT_CONSTRAINT_MATERIAL  ( 128) : Detect material rather than property
30                                         KX_ACT_CONSTRAINT_PERMANENT ( 256) : No deactivation if ray does not hit target
31         @type option: integer
32         
33         @ivar time: activation time of the actuator. The actuator disables itself after this many frame.
34                         If set to 0, the actuator is not limited in time.
35         @type time: integer
36         
37         @ivar property: the name of the property or material for the ray detection of the distance constraint.
38         @type property: string
39         
40         @ivar min: The lower bound of the constraint
41                    For the rotation and orientation constraint, it represents radiant
42         @type min: float
43         
44         @ivar distance: the target distance of the distance constraint
45         @type distance: float
46         
47         @ivar max: the upper bound of the constraint.
48                    For rotation and orientation constraints, it represents radiant.
49         @type max: float
50         
51         @ivar rayLength: the length of the ray of the distance constraint.
52         @type rayLength: float
53         
54         @ivar limit: type of constraint, use one of the following constant:
55                       KX_ACT_CONSTRAINT_LOCX  ( 1) : limit X coord
56                       KX_ACT_CONSTRAINT_LOCY  ( 2) : limit Y coord
57                       KX_ACT_CONSTRAINT_LOCZ  ( 3) : limit Z coord
58                       KX_ACT_CONSTRAINT_ROTX  ( 4) : limit X rotation
59                       KX_ACT_CONSTRAINT_ROTY  ( 5) : limit Y rotation
60                       KX_ACT_CONSTRAINT_ROTZ  ( 6) : limit Z rotation
61                       KX_ACT_CONSTRAINT_DIRPX ( 7) : set distance along positive X axis
62                       KX_ACT_CONSTRAINT_DIRPY ( 8) : set distance along positive Y axis
63                       KX_ACT_CONSTRAINT_DIRPZ ( 9) : set distance along positive Z axis
64                       KX_ACT_CONSTRAINT_DIRNX (10) : set distance along negative X axis
65                       KX_ACT_CONSTRAINT_DIRNY (11) : set distance along negative Y axis
66                       KX_ACT_CONSTRAINT_DIRNZ (12) : set distance along negative Z axis
67                       KX_ACT_CONSTRAINT_ORIX  (13) : set orientation of X axis
68                       KX_ACT_CONSTRAINT_ORIY  (14) : set orientation of Y axis
69                       KX_ACT_CONSTRAINT_ORIZ  (15) : set orientation of Z axis
70                       KX_ACT_CONSTRAINT_FHPX  (16) : set force field along positive X axis
71                       KX_ACT_CONSTRAINT_FHPY  (17) : set force field along positive Y axis
72                       KX_ACT_CONSTRAINT_FHPZ  (18) : set force field along positive Z axis
73                       KX_ACT_CONSTRAINT_FHNX  (19) : set force field along negative X axis
74                       KX_ACT_CONSTRAINT_FHNY  (20) : set force field along negative Y axis
75                       KX_ACT_CONSTRAINT_FHNZ  (21) : set force field along negative Z axis
76         @type limit: integer
77         """
78         def setDamp(time):
79                 """
80                 Sets the time this constraint is delayed.
81                 
82                 @param time: The number of frames to delay.  
83                              Negative values are ignored.
84                 @type time: integer
85                 """
86         def getDamp():
87                 """
88                 Returns the damping time of the constraint.
89                 
90                 @rtype: integer
91                 """
92         def setMin(lower):
93                 """
94                 Sets the lower bound of the constraint.
95                 
96                 For rotational and orientation constraints, lower is specified in degrees.
97                 
98                 @type lower: float
99                 """
100         def getMin():
101                 """
102                 Gets the lower bound of the constraint.
103                 
104                 For rotational and orientation constraints, the lower bound is returned in radians.
105                 
106                 @rtype: float
107                 """
108         def setMax(upper):
109                 """
110                 Sets the upper bound of the constraint.
111                 
112                 For rotational and orientation constraints, upper is specified in degrees.
113                 
114                 @type upper: float
115                 """
116         def getMax():
117                 """
118                 Gets the upper bound of the constraint.
119                 
120                 For rotational and orientation constraints, the upper bound is returned in radians.
121                 
122                 @rtype: float
123                 """
124         def setLimit(limit):
125                 """
126                 Sets the type of constraint.
127                 
128                 See module L{GameLogic} for valid constraint types.
129                 
130                 @param limit:
131                         Position constraints: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ
132                         Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY or KX_CONSTRAINTACT_ROTZ
133                         Distance contraints: KX_ACT_CONSTRAINT_DIRPX, KX_ACT_CONSTRAINT_DIRPY, KX_ACT_CONSTRAINT_DIRPZ, KX_ACT_CONSTRAINT_DIRNX, KX_ACT_CONSTRAINT_DIRNY, KX_ACT_CONSTRAINT_DIRNZ
134                         Orientation constraints: KX_ACT_CONSTRAINT_ORIX, KX_ACT_CONSTRAINT_ORIY, KX_ACT_CONSTRAINT_ORIZ
135                 """
136         def getLimit():
137                 """
138                 Gets the type of constraint.
139                 
140                 See module L{GameLogic} for valid constraints.
141                 
142                 @return:
143                         Position constraints: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, 
144                         Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ,
145                         Distance contraints: KX_ACT_CONSTRAINT_DIRPX, KX_ACT_CONSTRAINT_DIRPY, KX_ACT_CONSTRAINT_DIRPZ, KX_ACT_CONSTRAINT_DIRNX, KX_ACT_CONSTRAINT_DIRNY, KX_ACT_CONSTRAINT_DIRNZ,
146                         Orientation constraints: KX_ACT_CONSTRAINT_ORIX, KX_ACT_CONSTRAINT_ORIY, KX_ACT_CONSTRAINT_ORIZ
147                 """
148         def setRotDamp(duration):
149                 """
150                 Sets the time constant of the orientation constraint.
151                 
152                 @param duration: If the duration is negative, it is set to 0.
153                 @type duration: integer
154                 """
155         def getRotDamp():
156                 """ 
157                 Returns the damping time for application of the constraint.
158                 
159                 @rtype: integer
160                 """
161         def setDirection(vector):
162                 """
163                 Sets the reference direction in world coordinate for the orientation constraint
164                 
165                 @type vector: 3-tuple
166                 """
167         def getDirection():
168                 """
169                 Returns the reference direction of the orientation constraint in world coordinate.
170                 
171                 @rtype: 3-tuple
172                 """
173         def setOption(option):
174                 """
175                 Sets several options of the distance constraint.
176                 
177                 @type option: integer
178                 @param option: Binary combination of the following values:
179                                64  : Activate alignment to surface
180                                128 : Detect material rather than property
181                                256 : No deactivation if ray does not hit target
182                                512 : Activate distance control
183                 """
184         def getOption():
185                 """
186                 Returns the option parameter.
187                 
188                 @rtype: integer
189                 """
190         def setTime(duration):
191                 """
192                 Sets the activation time of the actuator.
193                 
194                 @type duration: integer
195                 @param duration: The actuator disables itself after this many frame.
196                                  If set to 0 or negative, the actuator is not limited in time.
197                 """
198         def getTime():
199                 """
200                 Returns the time parameter.
201                 
202                 @rtype: integer
203                 """
204         def setProperty(property):
205                 """
206                 Sets the name of the property or material for the ray detection of the distance constraint.
207                 
208                 @type property: string
209                 @param property: If empty, the ray will detect any collisioning object.
210                 """
211         def getProperty():
212                 """
213                 Returns the property parameter.
214                 
215                 @rtype: string
216                 """
217         def setDistance(distance):
218                 """
219                 Sets the target distance in distance constraint.
220                 
221                 @type distance: float
222                 """
223         def getDistance():
224                 """
225                 Returns the distance parameter.
226                 
227                 @rtype: float
228                 """
229         def setRayLength(length):
230                 """
231                 Sets the maximum ray length of the distance constraint.
232                 
233                 @type length: float
234                 """
235         def getRayLength():
236                 """
237                 Returns the length of the ray
238                 
239                 @rtype: float
240                 """
241
242
243
244
245
246
247
248
249