svn merge https://svn.blender.org/svnroot/bf-blender/trunk/blender -r22704:22717
[blender.git] / source / gameengine / PyDoc / GameTypes.py
1 """
2 Documentation for the GameTypes Module.
3 =======================================
4
5 @group Base: PyObjectPlus, CValue, CPropValue, SCA_ILogicBrick, SCA_IObject, SCA_ISensor, SCA_IController, SCA_IActuator
6
7 @group Object: KX_GameObject, KX_LightObject, KX_Camera
8
9 @group Mesh: KX_MeshProxy, KX_PolyProxy, KX_VertexProxy
10
11 @group Shading: KX_PolygonMaterial, KX_BlenderMaterial, BL_Shader
12
13 @group Sensors: SCA_ActuatorSensor, SCA_AlwaysSensor, SCA_DelaySensor, SCA_JoystickSensor, SCA_KeyboardSensor, KX_MouseFocusSensor, SCA_MouseSensor, KX_NearSensor, KX_NetworkMessageSensor, SCA_PropertySensor, KX_RadarSensor, SCA_RandomSensor, KX_RaySensor, KX_TouchSensor
14
15 @group Actuators: SCA_2DFilterActuator, BL_ActionActuator, KX_SCA_AddObjectActuator, KX_CameraActuator, KX_ConstraintActuator, KX_SCA_DynamicActuator, KX_SCA_EndObjectActuator, KX_GameActuator, KX_IpoActuator, KX_NetworkMessageActuator, KX_ObjectActuator, KX_ParentActuator, SCA_PropertyActuator, SCA_RandomActuator, KX_SCA_ReplaceMeshActuator, KX_SceneActuator, BL_ShapeActionActuator, KX_SoundActuator, KX_StateActuator, KX_TrackToActuator, KX_VisibilityActuator
16
17 @group Controllers: SCA_ANDController, SCA_NANDController, SCA_NORController, SCA_ORController, SCA_PythonController, SCA_XNORController, SCA_XORController
18 """
19 import GameLogic
20
21 class PyObjectPlus:
22         """
23         PyObjectPlus base class of most other types in the Game Engine.
24         
25         @ivar invalid:  Test if the object has been freed by the game engine and is no longer valid.
26                                         
27                                         Normally this is not a problem but when storing game engine data in the GameLogic module,
28                                         KX_Scenes or other KX_GameObjects its possible to hold a reference to invalid data.
29                                         Calling an attribute or method on an invalid object will raise a SystemError.
30                                         
31                                         The invalid attribute allows testing for this case without exception handling.
32         @type invalid:  bool
33         """
34         
35         def isA(game_type):
36                 """
37                 Check if this is a type or a subtype game_type.
38
39                 @param game_type: the name of the type or the type its self from the L{GameTypes} module.
40                 @type game_type: string or type
41                 @return: True if this object is a type or a subtype of game_type.
42                 @rtype: bool
43                 """
44
45 class CValue(PyObjectPlus):
46         """
47         This class is a basis for other classes.
48         @ivar name: The name of this CValue derived object (read-only).
49         @type name: string
50         @group Deprecated: getName
51         """
52         def getName():
53                 """
54                 Returns the name of the CValue.
55                 
56                 @deprecated: Use the L{name} attribute instead.
57                 @note: in most cases the CValue's subclasses will override this function.
58                 @rtype: string
59                 """
60
61 class CPropValue(CValue):
62         """
63         This class has no python functions
64         """
65         pass
66
67 class SCA_ILogicBrick(CValue):
68         """
69         Base class for all logic bricks.
70         
71         @ivar executePriority: This determines the order controllers are evaluated, and actuators are activated (lower priority is executed first).
72         @type executePriority: int
73         @ivar owner: The game object this logic brick is attached to (read-only).
74         @type owner: L{KX_GameObject} or None in exceptional cases.
75         @ivar name: The name of this logic brick (read-only).
76         @type name: string
77         """
78
79 #{ Deprecated
80         def getOwner():
81                 """
82                 Gets the game object associated with this logic brick.
83                 
84                 @deprecated: Use the L{owner} attribute instead.
85                 @rtype: L{KX_GameObject}
86                 """
87         
88         def setExecutePriority(priority):
89                 """
90                 Sets the priority of this logic brick.
91                 
92                 This determines the order controllers are evaluated, and actuators are activated.
93                 Bricks with lower priority will be executed first.
94                 
95                 @deprecated: Use the L{executePriority} attribute instead.
96                 @type priority: integer
97                 @param priority: the priority of this logic brick.
98                 """
99         def getExecutePriority():
100                 """
101                 Gets the execution priority of this logic brick.
102                 
103                 @deprecated: Use the L{executePriority} attribute instead.
104                 @rtype: integer
105                 @return: this logic bricks current priority.
106                 """
107 #}
108
109 class SCA_IObject(CValue):
110         """
111         This class has no python functions
112         """
113         pass
114
115 class SCA_ISensor(SCA_ILogicBrick):
116         """
117         Base class for all sensor logic bricks.
118         
119         @ivar usePosPulseMode: Flag to turn positive pulse mode on and off.
120         @type usePosPulseMode: boolean
121         @ivar useNegPulseMode: Flag to turn negative pulse mode on and off.
122         @type useNegPulseMode: boolean
123         @ivar frequency: The frequency for pulse mode sensors.
124         @type frequency: int
125         @ivar level: Option whether to detect level or edge transition when entering a state.
126                                         It makes a difference only in case of logic state transition (state actuator).
127                                         A level detector will immediately generate a pulse, negative or positive
128                                         depending on the sensor condition, as soon as the state is activated.
129                                         A edge detector will wait for a state change before generating a pulse.
130                                         note: mutually exclusive with L{tap}, enabling will disable L{tap}.
131         @type level: boolean
132         @ivar tap: When enabled only sensors that are just activated will send a positive event,
133                                         after this they will be detected as negative by the controllers.
134                                         This will make a key thats held act as if its only tapped for an instant.
135                                         note: mutually exclusive with L{level}, enabling will disable L{level}.
136         @type tap: boolean
137         @ivar invert: Flag to set if this sensor activates on positive or negative events.
138         @type invert: boolean
139         @ivar triggered: True if this sensor brick is in a positive state. (read-only)
140         @type triggered: boolean
141         @ivar positive: True if this sensor brick is in a positive state. (read-only)
142         @type positive: boolean
143         """
144         
145         def reset():
146                 """
147                 Reset sensor internal state, effect depends on the type of sensor and settings.
148                 
149                 The sensor is put in its initial state as if it was just activated.
150                 """
151 #{ Deprecated
152         def isPositive():
153                 """
154                 True if this sensor brick is in a positive state.
155                 
156                 @deprecated: use L{positive}
157                 """
158         
159         def isTriggered():
160                 """
161                 True if this sensor brick has triggered the current controller.
162                 
163                 @deprecated: use L{triggered}
164                 """
165         
166         def getUsePosPulseMode():
167                 """
168                 True if the sensor is in positive pulse mode.
169                 
170                 @deprecated: use L{usePosPulseMode}
171                 """
172         def setUsePosPulseMode(pulse):
173                 """
174                 Sets positive pulse mode.
175                 
176                 @type pulse: boolean
177                 @param pulse: If True, will activate positive pulse mode for this sensor.
178                 @deprecated: use L{usePosPulseMode}
179                 """
180         def getFrequency():
181                 """
182                 The frequency for pulse mode sensors.
183                 
184                 @rtype: integer
185                 @return: the pulse frequency in 1/50 sec.
186                 @deprecated: use L{frequency}
187                 """
188         def setFrequency(freq):
189                 """
190                 Sets the frequency for pulse mode sensors.
191                 
192                 @type freq: integer
193                 @return: the pulse frequency in 1/50 sec.
194                 @deprecated: use L{frequency}
195                 """
196         def getUseNegPulseMode():
197                 """
198                 True if the sensor is in negative pulse mode.
199                 
200                 @deprecated: use L{useNegPulseMode}
201                 """
202         def setUseNegPulseMode(pulse):
203                 """
204                 Sets negative pulse mode.
205                 
206                 @type pulse: boolean
207                 @param pulse: If True, will activate negative pulse mode for this sensor.
208                 @deprecated: use L{useNegPulseMode}
209                 """
210         def getInvert():
211                 """
212                 True if this sensor activates on negative events.
213                 
214                 @deprecated: use L{invert}
215                 """
216         def setInvert(invert):
217                 """
218                 Sets if this sensor activates on positive or negative events.
219                 
220                 @type invert: boolean
221                 @param invert: true if activates on negative events; false if activates on positive events.
222                 @deprecated: use L{invert}
223                 """
224         def getLevel():
225                 """
226                 Returns whether this sensor is a level detector or a edge detector.
227                 It makes a difference only in case of logic state transition (state actuator).
228                 A level detector will immediately generate a pulse, negative or positive
229                 depending on the sensor condition, as soon as the state is activated.
230                 A edge detector will wait for a state change before generating a pulse.
231                 
232                 @rtype: boolean
233                 @return: true if sensor is level sensitive, false if it is edge sensitive
234                 @deprecated: use L{level}
235                 """
236         def setLevel(level):
237                 """
238                 Set whether to detect level or edge transition when entering a state.
239                 
240                 @param level: Detect level instead of edge? (KX_TRUE, KX_FALSE)
241                 @type level: boolean
242                 @deprecated: use L{level}
243                 """
244 #}
245
246 class SCA_IController(SCA_ILogicBrick):
247         """
248         Base class for all controller logic bricks.
249         
250         @ivar state: the controllers state bitmask.
251                      This can be used with the GameObject's state to test if the controller is active.
252         @type state: int bitmask
253         @ivar sensors: a list of sensors linked to this controller
254                                         - note: the sensors are not necessarily owned by the same object.
255                                         - note: when objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
256         @type sensors: sequence supporting index/string lookups and iteration.
257         @ivar actuators: a list of actuators linked to this controller.
258                                                 - note: the sensors are not necessarily owned by the same object.
259                                                 - note: when objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
260         @type actuators: sequence supporting index/string lookups and iteration.
261         @ivar useHighPriority: When set the controller executes always before all other controllers that dont have this set.
262                         note: Order of execution between high priority controllers is not guaranteed.
263         @type useHighPriority: bool
264         """
265 #{ Deprecated
266         def getState():
267                 """
268                 Get the controllers state bitmask, this can be used with the GameObject's state to test if the the controller is active.
269                 This for instance will always be true however you could compare with a previous state to see when the state was activated.
270                 GameLogic.getCurrentController().state & GameLogic.getCurrentController().owner.state
271                 @deprecated: Use the L{state} property
272                 @rtype: int
273                 """
274         def getSensors():
275                 """
276                 Gets a list of all sensors attached to this controller.
277                 @deprecated: use the L{sensors} property
278                 @rtype: list [L{SCA_ISensor}]
279                 """
280         def getSensor(name):
281                 """
282                 Gets the named linked sensor.
283                 @deprecated: use the L{sensors}[name] property
284                 @type name: string
285                 @rtype: L{SCA_ISensor}
286                 """
287         def getActuators():
288                 """
289                 Gets a list of all actuators linked to this controller.
290                 @deprecated: Use the L{actuators} property
291                 @rtype: list [L{SCA_IActuator}]
292                 """
293         def getActuator(name):
294                 """
295                 Gets the named linked actuator.
296                 @deprecated: use the L{actuators}[name] property
297                 @type name: string
298                 @rtype: L{SCA_IActuator}
299                 """
300 #}
301
302 class SCA_IActuator(SCA_ILogicBrick):
303         """
304         Base class for all actuator logic bricks.
305         """
306
307 class BL_ActionActuator(SCA_IActuator):
308         """
309         Action Actuators apply an action to an actor.
310         
311         @ivar action: The name of the action to set as the current action.
312         @type action: string
313         @ivar channelNames: A list of channel names that may be used with L{setChannel} and L{getChannel}
314         @type channelNames: list of strings
315         @ivar frameStart: Specifies the starting frame of the animation.
316         @type frameStart: float
317         @ivar frameEnd: Specifies the ending frame of the animation.
318         @type frameEnd: float
319         @ivar blendIn: Specifies the number of frames of animation to generate when making transitions between actions.
320         @type blendIn: float
321         @ivar priority: Sets the priority of this actuator. Actuators will lower
322                                  priority numbers will override actuators with higher
323                                  numbers.
324         @type priority: integer
325         @ivar frame: Sets the current frame for the animation.
326         @type frame: float
327         @ivar propName: Sets the property to be used in FromProp playback mode.
328         @type propName: string
329         @ivar blendTime: Sets the internal frame timer. This property must be in
330                                                 the range from 0.0 to blendIn.
331         @type blendTime: float
332         @ivar mode: The operation mode of the actuator. KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
333         @type mode: integer
334         @ivar useContinue: The actions continue option, True or False.
335                                         When True, the action will always play from where last left off,
336                                         otherwise negative events to this actuator will reset it to its start frame.
337         @type useContinue: boolean
338         @ivar framePropName: The name of the property that is set to the current frame number.
339         @type framePropName: string
340         """
341         def setChannel(channel, matrix):
342                 """
343                 Alternative to the 2 arguments, 4 arguments (channel, matrix, loc, size, quat) are also supported.
344                 
345                 @note: These values are relative to the bones rest position, currently the api has no way to get this info (which is annoying), but can be worked around by using bones with a rest pose that has no translation.
346                 @param channel: A string specifying the name of the bone channel, error raised if not in L{channelNames}.
347                 @type channel: string
348                 @param matrix: A 4x4 matrix specifying the overriding transformation
349                                as an offset from the bone's rest position.
350                 @type matrix: list [[float]]
351                 """
352
353         def getChannel(channel):
354                 """
355                 @param channel: A string specifying the name of the bone channel. error raised if not in L{channelNames}.
356                 @type channel: string
357                 @rtype: tuple
358                 @return: (loc, size, quat)
359                 """
360
361 #{ Deprecated
362         def setAction(action, reset = True):
363                 """
364                 Sets the current action.
365                 @deprecated: use the L{action} property
366                 @param action: The name of the action to set as the current action.
367                 @type action: string
368                 @param reset: Optional parameter indicating whether to reset the
369                               blend timer or not.  A value of 1 indicates that the
370                               timer should be reset.  A value of 0 will leave it
371                               unchanged.  If reset is not specified, the timer will
372                               be reset.
373                 """
374
375         def setStart(start):
376                 """
377                 Specifies the starting frame of the animation.
378                 @deprecated: Use the L{frameStart} property
379                 @param start: the starting frame of the animation
380                 @type start: float
381                 """
382
383         def setEnd(end):
384                 """
385                 Specifies the ending frame of the animation.
386                 @deprecated: use the L{frameEnd} property 
387                 @param end: the ending frame of the animation
388                 @type end: float
389                 """
390         def setBlendin(blendin):
391                 """
392                 Specifies the number of frames of animation to generate
393                 when making transitions between actions.
394                 @deprecated: use the L{blendIn} property
395                 @param blendin: the number of frames in transition.
396                 @type blendin: float
397                 """
398
399         def setPriority(priority):
400                 """
401                 Sets the priority of this actuator.
402                 
403                 @deprecated: Use use the L{priority} property
404                 @param priority: Specifies the new priority.  Actuators will lower
405                                  priority numbers will override actuators with higher
406                                  numbers.
407                 @type priority: integer
408                 """
409         def setFrame(frame):
410                 """
411                 Sets the current frame for the animation.
412                 
413                 @deprecated: use the L{frame} property
414                 @param frame: Specifies the new current frame for the animation
415                 @type frame: float
416                 """
417
418         def setProperty(prop):
419                 """
420                 Sets the property to be used in FromProp playback mode.
421                 
422                 @deprecated: use the L{property} property
423                 @param prop: the name of the property to use.
424                 @type prop: string.
425                 """
426
427         def setBlendtime(blendtime):
428                 """
429                 Sets the internal frame timer.
430                 
431                 Allows the script to directly modify the internal timer
432                 used when generating transitions between actions.  
433                 
434                 @deprecated: use the L{blendTime} property
435                 @param blendtime: The new time. This parameter must be in the range from 0.0 to 1.0.
436                 @type blendtime: float
437                 """
438
439         def setType(mode):
440                 """
441                 Sets the operation mode of the actuator
442
443                 @deprecated: use the L{type} property
444                 @param mode: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
445                 @type mode: integer
446                 """
447         
448         def setContinue(cont):
449                 """
450                 Set the actions continue option True or False. see getContinue.
451
452                 @deprecated: use the L{useContinue} property
453                 @param cont: The continue option.
454                 @type cont: bool
455                 """
456
457         def getType():
458                 """
459                 Returns the operation mode of the actuator
460
461                 @deprecated: use the L{type} property
462                 @rtype: integer
463                 @return: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
464                 """
465
466         def getContinue():
467                 """
468                 When True, the action will always play from where last left off, otherwise negative events to this actuator will reset it to its start frame.
469
470                 @deprecated: use the L{useContinue} property
471                 @rtype: bool
472                 """
473         
474         def getAction():
475                 """
476                 getAction() returns the name of the action associated with this actuator.
477                 
478                 @deprecated: use the L{action} property
479                 @rtype: string
480                 """
481         
482         def getStart():
483                 """
484                 Returns the starting frame of the action.
485                 
486                 @deprecated: use the L{frameStart} property
487                 @rtype: float
488                 """
489         def getEnd():
490                 """
491                 Returns the last frame of the action.
492                 
493                 @deprecated: use the L{frameEnd} property
494                 @rtype: float
495                 """
496         def getBlendin():
497                 """
498                 Returns the number of interpolation animation frames to be generated when this actuator is triggered.
499                 
500                 @deprecated: use the L{blendIn} property
501                 @rtype: float
502                 """
503         def getPriority():
504                 """
505                 Returns the priority for this actuator.  Actuators with lower Priority numbers will
506                 override actuators with higher numbers.
507                 
508                 @deprecated: use the L{priority} property
509                 @rtype: integer
510                 """
511         def getFrame():
512                 """
513                 Returns the current frame number.
514                 
515                 @deprecated: use the L{frame} property
516                 @rtype: float
517                 """
518         def getProperty():
519                 """
520                 Returns the name of the property to be used in FromProp mode.
521                 
522                 @deprecated: use the L{property} property
523                 @rtype: string
524                 """
525         def setFrameProperty(prop):
526                 """
527                 @deprecated: use the L{framePropName} property
528                 @param prop: A string specifying the property of the object that will be updated with the action frame number.
529                 @type prop: string
530                 """
531         def getFrameProperty():
532                 """
533                 Returns the name of the property that is set to the current frame number.
534                 
535                 @deprecated: use the L{framePropName} property
536                 @rtype: string
537                 """
538 #}
539
540 class BL_Shader(PyObjectPlus):
541         """
542         BL_Shader GLSL shaders.
543         
544         TODO - Description
545         """
546         
547         def setUniformfv(name, fList):
548                 """
549                 Set a uniform with a list of float values
550                 
551                 @param name: the uniform name
552                 @type name: string
553                 
554                 @param fList: a list (2, 3 or 4 elements) of float values
555                 @type fList: list[float]
556                 """
557
558         def delSource():
559                 """
560                 Clear the shader. Use this method before the source is changed with L{setSource}.
561                 """
562         def getFragmentProg():
563                 """
564                 Returns the fragment program.
565                 
566                 @rtype: string
567                 @return: The fragment program.
568                 """
569         def getVertexProg():
570                 """
571                 Get the vertex program.
572                 
573                 @rtype: string
574                 @return: The vertex program.
575                 """
576         def isValid():
577                 """
578                 Check if the shader is valid.
579
580                 @rtype: bool
581                 @return: True if the shader is valid
582                 """
583         def setAttrib(enum):
584                 """
585                 Set attribute location. (The parameter is ignored a.t.m. and the value of "tangent" is always used.)
586                 
587                 @param enum: attribute location value
588                 @type enum: integer
589                 """
590         def setNumberOfPasses( max_pass ):
591                 """
592                 Set the maximum number of passes. Not used a.t.m.
593                 
594                 @param max_pass: the maximum number of passes
595                 @type max_pass: integer
596                 """
597         def setSampler(name, index):
598                 """
599                 Set uniform texture sample index.
600                 
601                 @param name: Uniform name
602                 @type name: string
603
604                 @param index: Texture sample index.
605                 @type index: integer
606                 """
607         def setSource(vertexProgram, fragmentProgram):
608                 """
609                 Set the vertex and fragment programs
610                 
611                 @param vertexProgram: Vertex program
612                 @type vertexProgram: string
613
614                 @param fragmentProgram: Fragment program
615                 @type fragmentProgram: string
616                 """
617         def setUniform1f(name, fx):
618                 """
619                 Set a uniform with 1 float value.
620                 
621                 @param name: the uniform name
622                 @type name: string
623                 
624                 @param fx: Uniform value
625                 @type fx: float
626                 """
627         def setUniform1i(name, ix):
628                 """
629                 Set a uniform with an integer value.
630                 
631                 @param name: the uniform name
632                 @type name: string
633
634                 @param ix: the uniform value
635                 @type ix: integer
636                 """
637         def setUniform2f(name, fx, fy):
638                 """
639                 Set a uniform with 2 float values
640                 
641                 @param name: the uniform name
642                 @type name: string
643
644                 @param fx: first float value
645                 @type fx: float
646                 
647                 @param fy: second float value
648                 @type fy: float
649                 """
650         def setUniform2i(name, ix, iy):
651                 """
652                 Set a uniform with 2 integer values
653                 
654                 @param name: the uniform name
655                 @type name: string
656
657                 @param ix: first integer value
658                 @type ix: integer
659                 
660                 @param iy: second integer value
661                 @type iy: integer
662                 """
663         def setUniform3f(name, fx,fy,fz):
664                 """
665                 Set a uniform with 3 float values.
666                 
667                 @param name: the uniform name
668                 @type name: string
669
670                 @param fx: first float value
671                 @type fx: float
672                 
673                 @param fy: second float value
674                 @type fy: float
675
676                 @param fz: third float value
677                 @type fz: float
678                 """
679         def setUniform3i(name, ix,iy,iz):
680                 """
681                 Set a uniform with 3 integer values
682                 
683                 @param name: the uniform name
684                 @type name: string
685
686                 @param ix: first integer value
687                 @type ix: integer
688                 
689                 @param iy: second integer value
690                 @type iy: integer
691                 
692                 @param iz: third integer value
693                 @type iz: integer
694                 """
695         def setUniform4f(name, fx,fy,fz,fw):
696                 """
697                 Set a uniform with 4 float values.
698                 
699                 @param name: the uniform name
700                 @type name: string
701
702                 @param fx: first float value
703                 @type fx: float
704                 
705                 @param fy: second float value
706                 @type fy: float
707
708                 @param fz: third float value
709                 @type fz: float
710
711                 @param fw: fourth float value
712                 @type fw: float
713                 """
714         def setUniform4i(name, ix,iy,iz, iw):
715                 """
716                 Set a uniform with 4 integer values
717                 
718                 @param name: the uniform name
719                 @type name: string
720
721                 @param ix: first integer value
722                 @type ix: integer
723                 
724                 @param iy: second integer value
725                 @type iy: integer
726                 
727                 @param iz: third integer value
728                 @type iz: integer
729                 
730                 @param iw: fourth integer value
731                 @type iw: integer
732                 """
733         def setUniformDef(name, type):
734                 """
735                 Define a new uniform
736                 
737                 @param name: the uniform name
738                 @type name: string
739
740                 @param type: uniform type
741                 @type type: UNI_NONE, UNI_INT, UNI_FLOAT, UNI_INT2, UNI_FLOAT2, UNI_INT3, UNI_FLOAT3, UNI_INT4, UNI_FLOAT4,     UNI_MAT3, UNI_MAT4,     UNI_MAX
742                 """
743         def setUniformMatrix3(name, mat, transpose):
744                 """
745                 Set a uniform with a 3x3 matrix value
746                 
747                 @param name: the uniform name
748                 @type name: string
749
750                 @param mat: A 3x3 matrix [[f,f,f], [f,f,f], [f,f,f]]
751                 @type mat: 3x3 matrix
752                 
753                 @param transpose: set to True to transpose the matrix
754                 @type transpose: bool
755                 """
756         def setUniformMatrix4(name, mat, transpose):
757                 """
758                 Set a uniform with a 4x4 matrix value
759                 
760                 @param name: the uniform name
761                 @type name: string
762
763                 @param mat: A 4x4 matrix [[f,f,f,f], [f,f,f,f], [f,f,f,f], [f,f,f,f]]
764                 @type mat: 4x4 matrix
765                 
766                 @param transpose: set to True to transpose the matrix
767                 @type transpose: bool
768                 """
769         def setUniformiv(name, iList):
770                 """
771                 Set a uniform with a list of integer values
772                 
773                 @param name: the uniform name
774                 @type name: string
775                 
776                 @param iList: a list (2, 3 or 4 elements) of integer values
777                 @type iList: list[integer]
778                 """
779         def validate():
780                 """
781                 Validate the shader object.
782                 
783                 """
784
785 class BL_ShapeActionActuator(SCA_IActuator):
786         """
787         ShapeAction Actuators apply an shape action to an mesh object.\
788
789         @ivar action: The name of the action to set as the current shape action.
790         @type action: string
791         @ivar frameStart: Specifies the starting frame of the shape animation.
792         @type frameStart: float
793         @ivar frameEnd: Specifies the ending frame of the shape animation.
794         @type frameEnd: float
795         @ivar blendIn: Specifies the number of frames of animation to generate when making transitions between actions.
796         @type blendIn: float
797         @ivar priority: Sets the priority of this actuator. Actuators will lower
798                                  priority numbers will override actuators with higher
799                                  numbers.
800         @type priority: integer
801         @ivar frame: Sets the current frame for the animation.
802         @type frame: float
803         @ivar propName: Sets the property to be used in FromProp playback mode.
804         @type propName: string
805         @ivar blendTime: Sets the internal frame timer. This property must be in
806                                                 the range from 0.0 to blendin.
807         @type blendTime: float
808         @ivar mode: The operation mode of the actuator.
809                                         KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER,
810                                         KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
811         @type mode: integer
812         @ivar framePropName: The name of the property that is set to the current frame number.
813         @type framePropName: string
814         
815         """
816 #{ Deprecated
817         def setAction(action, reset = True):
818                 """
819                 Sets the current action.
820                 
821                 @deprecated: use the L{action} property
822                 @param action: The name of the action to set as the current action.
823                 @type action: string
824                 @param reset: Optional parameter indicating whether to reset the
825                               blend timer or not.  A value of 1 indicates that the
826                               timer should be reset.  A value of 0 will leave it
827                               unchanged.  If reset is not specified, the timer will
828                               be reset.
829                 """
830
831         def setStart(start):
832                 """
833                 Specifies the starting frame of the animation.
834                 
835                 @deprecated: use the L{frameStart} property
836                 @param start: the starting frame of the animation
837                 @type start: float
838                 """
839
840         def setEnd(end):
841                 """
842                 Specifies the ending frame of the animation.
843                 
844                 @deprecated: use the L{frameEnd} property
845                 @param end: the ending frame of the animation
846                 @type end: float
847                 """
848         def setBlendin(blendin):
849                 """
850                 Specifies the number of frames of animation to generate
851                 when making transitions between actions.
852                 
853                 @deprecated: use the L{blendIn} property
854                 @param blendin: the number of frames in transition.
855                 @type blendin: float
856                 """
857
858         def setPriority(priority):
859                 """
860                 Sets the priority of this actuator.
861                 
862                 @deprecated: use the L{priority} property
863                 @param priority: Specifies the new priority.  Actuators will lower
864                                  priority numbers will override actuators with higher
865                                  numbers.
866                 @type priority: integer
867                 """
868         def setFrame(frame):
869                 """
870                 Sets the current frame for the animation.
871                 
872                 @deprecated: use the L{frame} property
873                 @param frame: Specifies the new current frame for the animation
874                 @type frame: float
875                 """
876
877         def setProperty(prop):
878                 """
879                 Sets the property to be used in FromProp playback mode.
880                 
881                 @deprecated: use the L{property} property
882                 @param prop: the name of the property to use.
883                 @type prop: string.
884                 """
885
886         def setBlendtime(blendtime):
887                 """
888                 Sets the internal frame timer.
889                 
890                 Allows the script to directly modify the internal timer
891                 used when generating transitions between actions.  
892                 
893                 @deprecated: use the L{blendTime} property
894                 @param blendtime: The new time. This parameter must be in the range from 0.0 to 1.0.
895                 @type blendtime: float
896                 """
897
898         def setType(mode):
899                 """
900                 Sets the operation mode of the actuator
901
902                 @deprecated: use the L{type} property
903                 @param mode: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
904                 @type mode: integer
905                 """
906         
907         def getType():
908                 """
909                 Returns the operation mode of the actuator
910                 
911                 @deprecated: use the L{type} property
912                 @rtype: integer
913                 @return: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
914                 """
915
916         def getAction():
917                 """
918                 getAction() returns the name of the action associated with this actuator.
919                 
920                 @deprecated: use the L{action} property
921                 @rtype: string
922                 """
923         
924         def getStart():
925                 """
926                 Returns the starting frame of the action.
927                 
928                 @deprecated: use the L{frameStart} property
929                 @rtype: float
930                 """
931         def getEnd():
932                 """
933                 Returns the last frame of the action.
934                 
935                 @deprecated: use the L{frameEnd} property
936                 @rtype: float
937                 """
938         def getBlendin():
939                 """
940                 Returns the number of interpolation animation frames to be generated when this actuator is triggered.
941                 
942                 @deprecated: use the L{blendIn} property
943                 @rtype: float
944                 """
945         def getPriority():
946                 """
947                 Returns the priority for this actuator.  Actuators with lower Priority numbers will
948                 override actuators with higher numbers.
949                 
950                 @deprecated: use the L{priority} property
951                 @rtype: integer
952                 """
953         def getFrame():
954                 """
955                 Returns the current frame number.
956                 
957                 @deprecated: use the L{frame} property
958                 @rtype: float
959                 """
960         def getProperty():
961                 """
962                 Returns the name of the property to be used in FromProp mode.
963                 
964                 @deprecated: use the L{property} property
965                 @rtype: string
966                 """
967         def setFrameProperty(prop):
968                 """
969                 @deprecated: use the L{framePropName} property
970                 @param prop: A string specifying the property of the object that will be updated with the action frame number.
971                 @type prop: string
972                 """
973         def getFrameProperty():
974                 """
975                 Returns the name of the property that is set to the current frame number.
976                 
977                 @deprecated: use the L{framePropName} property
978                 @rtype: string
979                 """
980 #}
981
982 class CListValue(CPropValue):
983         """
984         CListValue
985         
986         This is a list like object used in the game engine internally that behaves similar to a python list in most ways.
987         
988         As well as the normal index lookup.
989         C{val= clist[i]}
990         
991         CListValue supports string lookups.
992         C{val= scene.objects["OBCube"]}
993         
994         Other operations such as C{len(clist), list(clist), clist[0:10]} are also supported.
995         """
996         def append(val):
997                 """
998                 Add an item to the list (like pythons append)
999                 
1000                 Warning: Appending values to the list can cause crashes when the list is used internally by the game engine.
1001                 """
1002
1003         def count(val):
1004                 """
1005                 Count the number of instances of a value in the list.
1006                 
1007                 @rtype: integer
1008                 @return: number of instances
1009                 """
1010         def index(val):
1011                 """
1012                 Return the index of a value in the list.
1013                 
1014                 @rtype: integer
1015                 @return: The index of the value in the list.
1016                 """
1017         def reverse():
1018                 """
1019                 Reverse the order of the list.
1020                 """
1021         def get(key, default=None):
1022                 """
1023                 Return the value matching key, or the default value if its not found.
1024                 @return: The key value or a default.
1025                 """
1026         def has_key(key):
1027                 """
1028                 Return True if the key is found.
1029                 @rtype: boolean
1030                 @return: The key value or a default.
1031                 """
1032         def from_id(id):
1033                 """
1034                 This is a funtion especially for the game engine to return a value with a spesific id.
1035                 
1036                 Since object names are not always unique, the id of an object can be used to get an object from the CValueList.
1037                 
1038                 Example.
1039                         
1040                 C{myObID = id(gameObject)}
1041                 
1042                 C{...}
1043                 
1044                 C{ob= scene.objects.from_id(myObID)}
1045                 
1046                 Where myObID is an int or long from the id function.
1047                 
1048                 This has the advantage that you can store the id in places you could not store a gameObject.
1049                 
1050                 Warning: the id is derived from a memory location and will be different each time the game engine starts.
1051                 """
1052
1053 class KX_BlenderMaterial(PyObjectPlus): # , RAS_IPolyMaterial)
1054         """
1055         KX_BlenderMaterial
1056         
1057         """
1058         
1059         def getShader():
1060                 """
1061                 Returns the material's shader.
1062                 
1063                 @rtype: L{BL_Shader}
1064                 @return: the material's shader
1065                 """
1066
1067         def setBlending(src, dest):
1068                 """
1069                 Set the pixel color arithmetic functions.
1070                 
1071                 @param src: Specifies how the red, green, blue,
1072                                         and alpha source blending factors are computed.
1073                 @type src:      GL_ZERO,
1074                                         GL_ONE,
1075                                         GL_SRC_COLOR,
1076                                         GL_ONE_MINUS_SRC_COLOR,
1077                                         GL_DST_COLOR,
1078                                         GL_ONE_MINUS_DST_COLOR,
1079                                         GL_SRC_ALPHA,
1080                                         GL_ONE_MINUS_SRC_ALPHA,
1081                                         GL_DST_ALPHA,
1082                                         GL_ONE_MINUS_DST_ALPHA,
1083                                         GL_SRC_ALPHA_SATURATE
1084
1085                 
1086                 @param dest: Specifies how the red, green, blue,
1087                     and alpha destination blending factors are computed.
1088                 @type dest: GL_ZERO,
1089                                         GL_ONE,
1090                                         GL_SRC_COLOR,
1091                                         GL_ONE_MINUS_SRC_COLOR,
1092                                         GL_DST_COLOR,
1093                                         GL_ONE_MINUS_DST_COLOR,
1094                                         GL_SRC_ALPHA,
1095                                         GL_ONE_MINUS_SRC_ALPHA,
1096                                         GL_DST_ALPHA,
1097                                         GL_ONE_MINUS_DST_ALPHA,
1098                                         GL_SRC_ALPHA_SATURATE
1099
1100                 """
1101         def getMaterialIndex():
1102                 """
1103                 Returns the material's index.
1104                 
1105                 @rtype: integer
1106                 @return: the material's index
1107                 """
1108
1109 class KX_CameraActuator(SCA_IActuator):
1110         """
1111         Applies changes to a camera.
1112         
1113         @ivar min: minimum distance to the target object maintained by the actuator
1114         @type min: float
1115         @ivar max: maximum distance to stay from the target object
1116         @type max: float
1117         @ivar height: height to stay above the target object
1118         @type height: float
1119         @ivar useXY: axis this actuator is tracking, true=X, false=Y
1120         @type useXY: boolean
1121         @ivar object: the object this actuator tracks.
1122         @type object: KX_GameObject or None
1123         @author: snail
1124         """
1125 #{ Deprecated
1126         def getObject(name_only = 1):
1127                 """
1128                 Returns the name of the object this actuator tracks.
1129                 
1130                 @deprecated: Use the L{object} attribute instead.
1131                 @type name_only: bool
1132                 @param name_only: optional argument, when 0 return a KX_GameObject
1133                 @rtype: string, KX_GameObject or None if no object is set
1134                 """
1135         
1136         def setObject(target):
1137                 """
1138                 Sets the object this actuator tracks.
1139                 
1140                 @deprecated: Use the L{object} attribute instead.
1141                 @param target: the object to track.
1142                 @type target: L{KX_GameObject}, string or None
1143                 """
1144         
1145         def getMin():
1146                 """
1147                 Returns the minimum distance to target maintained by the actuator.
1148                 
1149                 @deprecated: Use the L{min} attribute instead.
1150                 @rtype: float
1151                 """
1152         
1153         def setMin(distance):
1154                 """
1155                 Sets the minimum distance to the target object maintained by the
1156                 actuator.
1157                 
1158                 @deprecated: Use the L{min} attribute instead.
1159                 @param distance: The minimum distance to maintain.
1160                 @type distance: float
1161                 """
1162                 
1163         def getMax():
1164                 """
1165                 Gets the maximum distance to stay from the target object.
1166                 
1167                 @deprecated: Use the L{max} attribute instead.
1168                 @rtype: float
1169                 """
1170         
1171         def setMax(distance):
1172                 """
1173                 Sets the maximum distance to stay from the target object.
1174                 
1175                 @deprecated: Use the L{max} attribute instead.
1176                 @param distance: The maximum distance to maintain.
1177                 @type distance: float
1178                 """
1179
1180         def getHeight():
1181                 """
1182                 Returns the height to stay above the target object.
1183                 
1184                 @deprecated: Use the L{height} attribute instead.
1185                 @rtype: float
1186                 """
1187         
1188         def setHeight(height):
1189                 """
1190                 Sets the height to stay above the target object.
1191                 
1192                 @deprecated: Use the L{height} attribute instead.
1193                 @type height: float
1194                 @param height: The height to stay above the target object.
1195                 """
1196         
1197         def setXY(xaxis):
1198                 """
1199                 Sets the axis to get behind.
1200                 
1201                 @deprecated: Use the L{useXY} attribute instead.
1202                 @param xaxis: False to track Y axis, True to track X axis.
1203                 @type xaxis: boolean
1204                 """
1205
1206         def getXY():
1207                 """
1208                 Returns the axis this actuator is tracking.
1209                 
1210                 @deprecated: Use the L{useXY} attribute instead.
1211                 @return: True if tracking X axis, False if tracking Y axis.
1212                 @rtype: boolean
1213                 """
1214 #}
1215
1216 class KX_ConstraintActuator(SCA_IActuator):
1217         """
1218         A constraint actuator limits the position, rotation, distance or orientation of an object.
1219         
1220         Properties:
1221         
1222         @ivar damp: time constant of the constraint expressed in frame (not use by Force field constraint)
1223         @type damp: integer
1224         
1225         @ivar rotDamp: time constant for the rotation expressed in frame (only for the distance constraint)
1226                        0 = use damp for rotation as well
1227         @type rotDamp: integer
1228         
1229         @ivar direction: the reference direction in world coordinate for the orientation constraint
1230         @type direction: 3-tuple of float: [x,y,z]
1231         
1232         @ivar option: Binary combination of the following values:
1233                                 Applicable to Distance constraint:
1234                                         - KX_ACT_CONSTRAINT_NORMAL    (  64) : Activate alignment to surface
1235                                         - KX_ACT_CONSTRAINT_DISTANCE  ( 512) : Activate distance control
1236                                         - KX_ACT_CONSTRAINT_LOCAL               (1024) : direction of the ray is along the local axis
1237                                 Applicable to Force field constraint:                                   
1238                                         - KX_ACT_CONSTRAINT_DOROTFH   (2048) : Force field act on rotation as well
1239                                 Applicable to both:
1240                                         - KX_ACT_CONSTRAINT_MATERIAL  ( 128) : Detect material rather than property
1241                                         - KX_ACT_CONSTRAINT_PERMANENT ( 256) : No deactivation if ray does not hit target
1242         @type option: integer
1243         
1244         @ivar time: activation time of the actuator. The actuator disables itself after this many frame.
1245                         If set to 0, the actuator is not limited in time.
1246         @type time: integer
1247         
1248         @ivar propName: the name of the property or material for the ray detection of the distance constraint.
1249         @type propName: string
1250         
1251         @ivar min: The lower bound of the constraint
1252                    For the rotation and orientation constraint, it represents radiant
1253         @type min: float
1254         
1255         @ivar distance: the target distance of the distance constraint
1256         @type distance: float
1257         
1258         @ivar max: the upper bound of the constraint.
1259                    For rotation and orientation constraints, it represents radiant.
1260         @type max: float
1261         
1262         @ivar rayLength: the length of the ray of the distance constraint.
1263         @type rayLength: float
1264         
1265         @ivar limit: type of constraint, use one of the following constant:
1266                       KX_ACT_CONSTRAINT_LOCX  ( 1) : limit X coord
1267                       KX_ACT_CONSTRAINT_LOCY  ( 2) : limit Y coord
1268                       KX_ACT_CONSTRAINT_LOCZ  ( 3) : limit Z coord
1269                       KX_ACT_CONSTRAINT_ROTX  ( 4) : limit X rotation
1270                       KX_ACT_CONSTRAINT_ROTY  ( 5) : limit Y rotation
1271                       KX_ACT_CONSTRAINT_ROTZ  ( 6) : limit Z rotation
1272                       KX_ACT_CONSTRAINT_DIRPX ( 7) : set distance along positive X axis
1273                       KX_ACT_CONSTRAINT_DIRPY ( 8) : set distance along positive Y axis
1274                       KX_ACT_CONSTRAINT_DIRPZ ( 9) : set distance along positive Z axis
1275                       KX_ACT_CONSTRAINT_DIRNX (10) : set distance along negative X axis
1276                       KX_ACT_CONSTRAINT_DIRNY (11) : set distance along negative Y axis
1277                       KX_ACT_CONSTRAINT_DIRNZ (12) : set distance along negative Z axis
1278                       KX_ACT_CONSTRAINT_ORIX  (13) : set orientation of X axis
1279                       KX_ACT_CONSTRAINT_ORIY  (14) : set orientation of Y axis
1280                       KX_ACT_CONSTRAINT_ORIZ  (15) : set orientation of Z axis
1281                       KX_ACT_CONSTRAINT_FHPX  (16) : set force field along positive X axis
1282                       KX_ACT_CONSTRAINT_FHPY  (17) : set force field along positive Y axis
1283                       KX_ACT_CONSTRAINT_FHPZ  (18) : set force field along positive Z axis
1284                       KX_ACT_CONSTRAINT_FHNX  (19) : set force field along negative X axis
1285                       KX_ACT_CONSTRAINT_FHNY  (20) : set force field along negative Y axis
1286                       KX_ACT_CONSTRAINT_FHNZ  (21) : set force field along negative Z axis
1287         @type limit: integer
1288         """
1289 #{ Deprecated
1290         def setDamp(time):
1291                 """
1292                 Sets the time this constraint is delayed.
1293                 
1294                 @param time: The number of frames to delay.  
1295                              Negative values are ignored.
1296                 @type time: integer
1297                 """
1298         def getDamp():
1299                 """
1300                 Returns the damping time of the constraint.
1301                 
1302                 @rtype: integer
1303                 """
1304         def setMin(lower):
1305                 """
1306                 Sets the lower bound of the constraint.
1307                 
1308                 For rotational and orientation constraints, lower is specified in degrees.
1309                 
1310                 @type lower: float
1311                 """
1312         def getMin():
1313                 """
1314                 Gets the lower bound of the constraint.
1315                 
1316                 For rotational and orientation constraints, the lower bound is returned in radians.
1317                 
1318                 @rtype: float
1319                 """
1320         def setMax(upper):
1321                 """
1322                 Sets the upper bound of the constraint.
1323                 
1324                 For rotational and orientation constraints, upper is specified in degrees.
1325                 
1326                 @type upper: float
1327                 """
1328         def getMax():
1329                 """
1330                 Gets the upper bound of the constraint.
1331                 
1332                 For rotational and orientation constraints, the upper bound is returned in radians.
1333                 
1334                 @rtype: float
1335                 """
1336         def setLimit(limit):
1337                 """
1338                 Sets the type of constraint.
1339                 
1340                 See module L{GameLogic} for valid constraint types.
1341                 
1342                 @param limit:
1343                         Position constraints: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ
1344                         Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY or KX_CONSTRAINTACT_ROTZ
1345                         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
1346                         Orientation constraints: KX_ACT_CONSTRAINT_ORIX, KX_ACT_CONSTRAINT_ORIY, KX_ACT_CONSTRAINT_ORIZ
1347                 """
1348         def getLimit():
1349                 """
1350                 Gets the type of constraint.
1351                 
1352                 See module L{GameLogic} for valid constraints.
1353                 
1354                 @return:
1355                         Position constraints: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, 
1356                         Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ,
1357                         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,
1358                         Orientation constraints: KX_ACT_CONSTRAINT_ORIX, KX_ACT_CONSTRAINT_ORIY, KX_ACT_CONSTRAINT_ORIZ
1359                 """
1360         def setRotDamp(duration):
1361                 """
1362                 Sets the time constant of the orientation constraint.
1363                 
1364                 @param duration: If the duration is negative, it is set to 0.
1365                 @type duration: integer
1366                 """
1367         def getRotDamp():
1368                 """ 
1369                 Returns the damping time for application of the constraint.
1370                 
1371                 @rtype: integer
1372                 """
1373         def setDirection(vector):
1374                 """
1375                 Sets the reference direction in world coordinate for the orientation constraint
1376                 
1377                 @type vector: 3-tuple
1378                 """
1379         def getDirection():
1380                 """
1381                 Returns the reference direction of the orientation constraint in world coordinate.
1382                 
1383                 @rtype: 3-tuple
1384                 """
1385         def setOption(option):
1386                 """
1387                 Sets several options of the distance constraint.
1388                 
1389                 @type option: integer
1390                 @param option: Binary combination of the following values:
1391                                64  : Activate alignment to surface
1392                                128 : Detect material rather than property
1393                                256 : No deactivation if ray does not hit target
1394                                512 : Activate distance control
1395                 """
1396         def getOption():
1397                 """
1398                 Returns the option parameter.
1399                 
1400                 @rtype: integer
1401                 """
1402         def setTime(duration):
1403                 """
1404                 Sets the activation time of the actuator.
1405                 
1406                 @type duration: integer
1407                 @param duration: The actuator disables itself after this many frame.
1408                                  If set to 0 or negative, the actuator is not limited in time.
1409                 """
1410         def getTime():
1411                 """
1412                 Returns the time parameter.
1413                 
1414                 @rtype: integer
1415                 """
1416         def setProperty(property):
1417                 """
1418                 Sets the name of the property or material for the ray detection of the distance constraint.
1419                 
1420                 @type property: string
1421                 @param property: If empty, the ray will detect any collisioning object.
1422                 """
1423         def getProperty():
1424                 """
1425                 Returns the property parameter.
1426                 
1427                 @rtype: string
1428                 """
1429         def setDistance(distance):
1430                 """
1431                 Sets the target distance in distance constraint.
1432                 
1433                 @type distance: float
1434                 """
1435         def getDistance():
1436                 """
1437                 Returns the distance parameter.
1438                 
1439                 @rtype: float
1440                 """
1441         def setRayLength(length):
1442                 """
1443                 Sets the maximum ray length of the distance constraint.
1444                 
1445                 @type length: float
1446                 """
1447         def getRayLength():
1448                 """
1449                 Returns the length of the ray
1450                 
1451                 @rtype: float
1452                 """
1453 #}
1454
1455 class KX_ConstraintWrapper(PyObjectPlus):
1456         """
1457         KX_ConstraintWrapper
1458         
1459         """
1460         def getConstraintId(val):
1461                 """
1462                 Returns the contraint's ID
1463                 
1464                 @rtype: integer
1465                 @return: the constraint's ID
1466                 """
1467
1468 class KX_GameActuator(SCA_IActuator):
1469         """
1470         The game actuator loads a new .blend file, restarts the current .blend file or quits the game.
1471         
1472         Properties:
1473         
1474         @ivar fileName: the new .blend file to load
1475         @type fileName: string.
1476         @ivar mode: The mode of this actuator
1477         @type mode: Constant in...
1478                                 - L{GameLogic.KX_GAME_LOAD}
1479                                 - L{GameLogic.KX_GAME_START}
1480                                 - L{GameLogic.KX_GAME_RESTART}
1481                                 - L{GameLogic.KX_GAME_QUIT}
1482                                 - L{GameLogic.KX_GAME_SAVECFG}
1483                                 - L{GameLogic.KX_GAME_LOADCFG}
1484         """
1485 #{ Deprecated
1486         def getFile():
1487                 """
1488                 Returns the filename of the new .blend file to load.
1489                 
1490                 @deprecated: use the L{fileName} property
1491                 @rtype: string
1492                 """
1493         def setFile(filename):
1494                 """
1495                 Sets the new .blend file to load.
1496                 
1497                 @deprecated: use the L{fileName} property
1498                 @param filename: The file name this actuator will load.
1499                 @type filename: string
1500                 """
1501 #}
1502
1503 class KX_GameObject(SCA_IObject):
1504         """
1505         All game objects are derived from this class.
1506         
1507         Properties assigned to game objects are accessible as attributes of this class.
1508                 - note: Calling ANY method or attribute on an object that has been removed from a scene will raise a SystemError, if an object may have been removed since last accessing it use the L{invalid} attribute to check.
1509
1510         @ivar name: The object's name. (read-only)
1511                 - note: Currently (Blender 2.49) the prefix "OB" is added to all objects name. This may change in blender 2.5.
1512         @type name: string.
1513         @ivar mass: The object's mass
1514                 - note: The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0
1515         @type mass: float
1516         @ivar linVelocityMin: Enforces the object keeps moving at a minimum velocity.
1517                 - note: Applies to dynamic and rigid body objects only.
1518                 - note: A value of 0.0 disables this option.
1519                 - note: While objects are stationary the minimum velocity will not be applied.
1520         @type linVelocityMin: float
1521         @ivar linVelocityMax: Clamp the maximum linear velocity to prevent objects moving beyond a set speed.
1522                 - note: Applies to dynamic and rigid body objects only.
1523                 - note: A value of 0.0 disables this option (rather then setting it stationary).
1524         @type linVelocityMax: float
1525         @ivar localInertia: the object's inertia vector in local coordinates. Read only.
1526         @type localInertia: list [ix, iy, iz]
1527         @ivar parent: The object's parent object. (read-only)
1528         @type parent: L{KX_GameObject} or None
1529         @ivar visible: visibility flag.
1530                 - note: Game logic will still run for invisible objects.
1531         @type visible: boolean
1532         @ivar occlusion: occlusion capability flag.
1533         @type occlusion: boolean
1534         @ivar position: The object's position. 
1535
1536                                         deprecated: use L{localPosition} and L{worldPosition}
1537         @type position: list [x, y, z] On write: local position, on read: world position
1538         @ivar orientation: The object's orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.
1539
1540                                            deprecated: use L{localOrientation} and L{worldOrientation}
1541         @type orientation: 3x3 Matrix [[float]] On write: local orientation, on read: world orientation
1542         @ivar scaling: The object's scaling factor. list [sx, sy, sz]
1543
1544                                    deprecated: use L{localScale} and L{worldScale}
1545         @type scaling: list [sx, sy, sz] On write: local scaling, on read: world scaling
1546         @ivar localOrientation: The object's local orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.
1547         @type localOrientation: 3x3 Matrix [[float]]
1548         @ivar worldOrientation: The object's world orientation.
1549         @type worldOrientation: 3x3 Matrix [[float]]
1550         @ivar localScale: The object's local scaling factor.
1551         @type localScale: list [sx, sy, sz]
1552         @ivar worldScale: The object's world scaling factor. Read-only
1553         @type worldScale: list [sx, sy, sz]
1554         @ivar localPosition: The object's local position.
1555         @type localPosition: list [x, y, z]
1556         @ivar worldPosition: The object's world position. 
1557         @type worldPosition: list [x, y, z]
1558         @ivar timeOffset: adjust the slowparent delay at runtime.
1559         @type timeOffset: float
1560         @ivar state: the game object's state bitmask, using the first 30 bits, one bit must always be set.
1561         @type state: int
1562         @ivar meshes: a list meshes for this object.
1563                 - note: Most objects use only 1 mesh.
1564                 - note: Changes to this list will not update the KX_GameObject.
1565         @type meshes: list of L{KX_MeshProxy}
1566         @ivar sensors: a sequence of L{SCA_ISensor} objects with string/index lookups and iterator support.
1567                 - note: This attribute is experemental and may be removed (but probably wont be).
1568                 - note: Changes to this list will not update the KX_GameObject.
1569         @type sensors: list
1570         @ivar controllers: a sequence of L{SCA_IController} objects with string/index lookups and iterator support.
1571                 - note: This attribute is experemental and may be removed (but probably wont be).
1572                 - note: Changes to this list will not update the KX_GameObject.
1573         @type controllers: list of L{SCA_ISensor}.
1574         @ivar actuators: a list of L{SCA_IActuator} with string/index lookups and iterator support.
1575                 - note: This attribute is experemental and may be removed (but probably wont be).
1576                 - note: Changes to this list will not update the KX_GameObject.
1577         @type actuators: list
1578         @ivar attrDict: get the objects internal python attribute dictionary for direct (faster) access.
1579         @type attrDict: dict
1580         @ivar children: direct children of this object, (read-only).
1581         @type children: L{CListValue} of L{KX_GameObject}'s
1582         @ivar childrenRecursive: all children of this object including childrens children, (read-only).
1583         @type childrenRecursive: L{CListValue} of L{KX_GameObject}'s
1584         @group Deprecated: getPosition, setPosition, setWorldPosition, getOrientation, setOrientation, getState, setState, getParent, getVisible, getMass, getMesh, getChildren, getChildrenRecursive
1585         @group Property Access: get, has_key, attrDict, getPropertyNames
1586         """
1587         def endObject():
1588                 """
1589                 Delete this object, can be used inpace of the EndObject Actuator.
1590                 The actual removal of the object from the scene is delayed.
1591                 """     
1592         def replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False):
1593                 """
1594                 Replace the mesh of this object with a new mesh. This works the same was as the actuator.
1595                 @type mesh: L{KX_MeshProxy} or mesh name
1596                 @type useDisplayMesh: bool
1597                 @param useDisplayMesh: when enabled the display mesh will be replaced (optional argument).
1598                 @type usePhysicsMesh: bool
1599                 @param usePhysicsMesh: when enabled the physics mesh will be replaced (optional argument).
1600                 """     
1601         def getVisible():
1602                 """
1603                 Gets the game object's visible flag.
1604                 
1605                 @deprecated: use L{visible}
1606                 @rtype: boolean
1607                 """     
1608         def setVisible(visible, recursive):
1609                 """
1610                 Sets the game object's visible flag.
1611                 
1612                 @type visible: boolean
1613                 @type recursive: boolean
1614                 @param recursive: optional argument to set all childrens visibility flag too.
1615                 """
1616         def setOcclusion(occlusion, recursive):
1617                 """
1618                 Sets the game object's occlusion capability.
1619                 
1620                 @type occlusion: boolean
1621                 @type recursive: boolean
1622                 @param recursive: optional argument to set all childrens occlusion flag too.
1623                 """
1624         def getState():
1625                 """
1626                 Gets the game object's state bitmask.
1627                 
1628                 @deprecated: use L{state}
1629                 @rtype: int
1630                 @return: the objects state.
1631                 """     
1632         def setState(state):
1633                 """
1634                 Sets the game object's state flag.
1635                 The bitmasks for states from 1 to 30 can be set with (1<<0, 1<<1, 1<<2 ... 1<<29) 
1636                 @deprecated: use L{state}
1637                 @type state: integer
1638                 """
1639         def setPosition(pos):
1640                 """
1641                 Sets the game object's position.
1642                 Global coordinates for root object, local for child objects.
1643                 
1644                 @deprecated: use L{localPosition}
1645                 @type pos: [x, y, z]
1646                 @param pos: the new position, in local coordinates.
1647                 """
1648         def setWorldPosition(pos):
1649                 """
1650                 Sets the game object's position in world coordinates regardless if the object is root or child.
1651                 
1652                 @deprecated: use L{worldPosition}
1653                 @type pos: [x, y, z]
1654                 @param pos: the new position, in world coordinates.
1655                 """
1656         def getPosition():
1657                 """
1658                 Gets the game object's position.
1659                 
1660                 @deprecated: use L{worldPosition}
1661                 @rtype: list [x, y, z]
1662                 @return: the object's position in world coordinates.
1663                 """
1664         def setOrientation(orn):
1665                 """
1666                 Sets the game object's orientation.
1667                 
1668                 @deprecated: use L{localOrientation}
1669                 @type orn: 3x3 rotation matrix, or Quaternion.
1670                 @param orn: a rotation matrix specifying the new rotation.
1671                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
1672                 """
1673         def alignAxisToVect(vect, axis, factor):
1674                 """
1675                 Aligns any of the game object's axis along the given vector.
1676                 
1677                 @type vect: 3d vector.
1678                 @param vect: a vector to align the axis.
1679                 @type axis: integer.
1680                 @param axis:The axis you want to align
1681                                         - 0: X axis
1682                                         - 1: Y axis
1683                                         - 2: Z axis (default) 
1684                 @type factor: float
1685                 @param factor: Only rotate a feaction of the distance to the target vector (0.0 - 1.0)
1686                 """
1687         def getAxisVect(vect):
1688                 """
1689                 Returns the axis vector rotates by the objects worldspace orientation.
1690                 This is the equivalent if multiplying the vector by the orientation matrix.
1691                 
1692                 @type vect: 3d vector.
1693                 @param vect: a vector to align the axis.
1694                 @rtype: 3d vector.
1695                 @return: The vector in relation to the objects rotation.
1696
1697                 """
1698         def getOrientation():
1699                 """
1700                 Gets the game object's orientation.
1701                 
1702                 @deprecated: use L{worldOrientation}
1703                 @rtype: 3x3 rotation matrix
1704                 @return: The game object's rotation matrix
1705                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
1706                 """
1707         def applyMovement(movement, local = 0):
1708                 """
1709                 Sets the game object's movement.
1710                 
1711                 @type movement: 3d vector.
1712                 @param movement: movement vector.
1713                 @type local: boolean
1714                 @param local: - False: you get the "global" movement ie: relative to world orientation (default).
1715                               - True: you get the "local" movement ie: relative to object orientation.
1716                 """     
1717         def applyRotation(rotation, local = 0):
1718                 """
1719                 Sets the game object's rotation.
1720                 
1721                 @type rotation: 3d vector.
1722                 @param rotation: rotation vector.
1723                 @type local: boolean
1724                 @param local: - False: you get the "global" rotation ie: relative to world orientation (default).
1725                                           - True: you get the "local" rotation ie: relative to object orientation.
1726                 """     
1727         def applyForce(force, local = 0):
1728                 """
1729                 Sets the game object's force.
1730                 
1731                 This requires a dynamic object.
1732                 
1733                 @type force: 3d vector.
1734                 @param force: force vector.
1735                 @type local: boolean
1736                 @param local: - False: you get the "global" force ie: relative to world orientation (default).
1737                                           - True: you get the "local" force ie: relative to object orientation.
1738                 """     
1739         def applyTorque(torque, local = 0):
1740                 """
1741                 Sets the game object's torque.
1742                 
1743                 This requires a dynamic object.
1744                 
1745                 @type torque: 3d vector.
1746                 @param torque: torque vector.
1747                 @type local: boolean
1748                 @param local: - False: you get the "global" torque ie: relative to world orientation (default).
1749                                           - True: you get the "local" torque ie: relative to object orientation.
1750                 """
1751         def getLinearVelocity(local = 0):
1752                 """
1753                 Gets the game object's linear velocity.
1754                 
1755                 This method returns the game object's velocity through it's centre of mass,
1756                 ie no angular velocity component.
1757                 
1758                 @type local: boolean
1759                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
1760                               - True: you get the "local" velocity ie: relative to object orientation.
1761                 @rtype: list [vx, vy, vz]
1762                 @return: the object's linear velocity.
1763                 """
1764         def setLinearVelocity(velocity, local = 0):
1765                 """
1766                 Sets the game object's linear velocity.
1767                 
1768                 This method sets game object's velocity through it's centre of mass,
1769                 ie no angular velocity component.
1770                 
1771                 This requires a dynamic object.
1772                 
1773                 @type velocity: 3d vector.
1774                 @param velocity: linear velocity vector.
1775                 @type local: boolean
1776                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
1777                               - True: you get the "local" velocity ie: relative to object orientation.
1778                 """
1779         def getAngularVelocity(local = 0):
1780                 """
1781                 Gets the game object's angular velocity.
1782                 
1783                 @type local: boolean
1784                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
1785                               - True: you get the "local" velocity ie: relative to object orientation.
1786                 @rtype: list [vx, vy, vz]
1787                 @return: the object's angular velocity.
1788                 """
1789         def setAngularVelocity(velocity, local = 0):
1790                 """
1791                 Sets the game object's angular velocity.
1792                 
1793                 This requires a dynamic object.
1794                 
1795                 @type velocity: 3d vector.
1796                 @param velocity: angular velocity vector.
1797                 @type local: boolean
1798                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
1799                               - True: you get the "local" velocity ie: relative to object orientation.
1800                 """
1801         def getVelocity(point):
1802                 """
1803                 Gets the game object's velocity at the specified point.
1804                 
1805                 Gets the game object's velocity at the specified point, including angular
1806                 components.
1807                 
1808                 @type point: list [x, y, z]
1809                 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])
1810                 @rtype: list [vx, vy, vz]
1811                 @return: the velocity at the specified point.
1812                 """
1813         def getMass():
1814                 """
1815                 Gets the game object's mass.
1816                 
1817                 @deprecated: use L{mass}
1818                 @rtype: float
1819                 @return: the object's mass.
1820                 """
1821         def getReactionForce():
1822                 """
1823                 Gets the game object's reaction force.
1824                 
1825                 The reaction force is the force applied to this object over the last simulation timestep.
1826                 This also includes impulses, eg from collisions.
1827                 
1828                 (B{This is not implimented for bullet physics at the moment})
1829                 
1830                 @rtype: list [fx, fy, fz]
1831                 @return: the reaction force of this object.
1832                 """
1833         def applyImpulse(point, impulse):
1834                 """
1835                 Applies an impulse to the game object.
1836                 
1837                 This will apply the specified impulse to the game object at the specified point.
1838                 If point != getPosition(), applyImpulse will also change the object's angular momentum.
1839                 Otherwise, only linear momentum will change.
1840                 
1841                 @type point: list [x, y, z]
1842                 @param point: the point to apply the impulse to (in world coordinates)
1843                 """
1844         def suspendDynamics():
1845                 """
1846                 Suspends physics for this object.
1847                 """
1848         def restoreDynamics():
1849                 """
1850                 Resumes physics for this object.
1851                 @Note: The objects linear velocity will be applied from when the dynamics were suspended.
1852                 """
1853         def enableRigidBody():
1854                 """
1855                 Enables rigid body physics for this object.
1856                 
1857                 Rigid body physics allows the object to roll on collisions.
1858                 @Note: This is not working with bullet physics yet.
1859                 """
1860         def disableRigidBody():
1861                 """
1862                 Disables rigid body physics for this object.
1863                 @Note: This is not working with bullet physics yet. The angular is removed but rigid body physics can still rotate it later.
1864                 """
1865         def getParent():
1866                 """
1867                 Gets this object's parent.
1868                 
1869                 @deprecated: use L{parent}
1870                 @rtype: L{KX_GameObject}
1871                 @return: this object's parent object, or None if this object has no parent.
1872                 """
1873         def setParent(parent,compound,ghost):
1874                 """
1875                 Sets this object's parent. 
1876                 Control the shape status with the optional compound and ghost parameters:
1877                 compound=1: the object shape should be added to the parent compound shape (default)
1878                 compound=0: the object should keep its individual shape. 
1879                 In that case you can control if it should be ghost or not:
1880                 ghost=1 if the object should be made ghost while parented (default)
1881                 ghost=0 if the object should be solid while parented 
1882                 Note: if the object type is sensor, it stays ghost regardless of ghost parameter
1883                 
1884                 @type parent: L{KX_GameObject}
1885                 @param parent: new parent object.
1886                 @type compound: int
1887                 @param compound: whether the shape should be added to the parent compound shape
1888                 @type ghost: int
1889                 @param ghost: whether the object should be ghost while parented
1890                 """
1891         def removeParent():
1892                 """
1893                 Removes this objects parent.
1894                 """
1895         def getChildren():
1896                 """
1897                 Return a list of immediate children of this object.
1898                 @rtype: L{CListValue} of L{KX_GameObject}
1899                 @return: a list of all this objects children.
1900                 """
1901         def getChildrenRecursive():
1902                 """
1903                 Return a list of children of this object, including all their childrens children.
1904                 @rtype: L{CListValue} of L{KX_GameObject}
1905                 @return: a list of all this objects children recursivly.
1906                 """
1907         def getMesh(mesh):
1908                 """
1909                 Gets the mesh object for this object.
1910                 
1911                 @type mesh: integer
1912                 @param mesh: the mesh object to return (optional: default mesh = 0)
1913                 @rtype: L{KX_MeshProxy}
1914                 @return: the first mesh object associated with this game object, or None if this object has no meshs.
1915                 """
1916         def getPhysicsId():
1917                 """
1918                 Returns the user data object associated with this game object's physics controller.
1919                 """
1920         def getPropertyNames():
1921                 """
1922                 Gets a list of all property names.
1923                 @rtype: list
1924                 @return: All property names for this object.
1925                 """
1926         def getDistanceTo(other):
1927                 """
1928                 Returns the distance to another object or point.
1929                 
1930                 @param other: a point or another L{KX_GameObject} to measure the distance to.
1931                 @type other: L{KX_GameObject} or list [x, y, z]
1932                 @rtype: float
1933                 """
1934         def getVectTo(other):
1935                 """
1936                 Returns the vector and the distance to another object or point.
1937                 The vector is normalized unless the distance is 0, in which a NULL vector is returned.
1938                 
1939                 @param other: a point or another L{KX_GameObject} to get the vector and distance to.
1940                 @type other: L{KX_GameObject} or list [x, y, z]
1941                 @rtype: 3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z))
1942                 @return: (distance, globalVector(3), localVector(3))
1943                 """
1944         def rayCastTo(other,dist,prop):
1945                 """
1946                 Look towards another point/object and find first object hit within dist that matches prop.
1947
1948                 The ray is always casted from the center of the object, ignoring the object itself.
1949                 The ray is casted towards the center of another object or an explicit [x,y,z] point.
1950                 Use rayCast() if you need to retrieve the hit point 
1951
1952                 @param other: [x,y,z] or object towards which the ray is casted
1953                 @type other: L{KX_GameObject} or 3-tuple
1954                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
1955                 @type dist: float
1956                 @param prop: property name that object must have; can be omitted => detect any object
1957                 @type prop: string
1958                 @rtype: L{KX_GameObject}
1959                 @return: the first object hit or None if no object or object does not match prop
1960                 """
1961         def rayCast(objto,objfrom,dist,prop,face,xray,poly):
1962                 """
1963                 Look from a point/object to another point/object and find first object hit within dist that matches prop.
1964                 if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit.
1965                 if poly is 1, returns a 4-tuple with in addition a L{KX_PolyProxy} as 4th element.
1966                 
1967                 Ex::
1968                         # shoot along the axis gun-gunAim (gunAim should be collision-free)
1969                         ob,point,normal = gun.rayCast(gunAim,None,50)
1970                         if ob:
1971                                 # hit something
1972
1973                 Notes:                          
1974                 The ray ignores the object on which the method is called.
1975                 It is casted from/to object center or explicit [x,y,z] points.
1976                 
1977                 The face paremeter determines the orientation of the normal:: 
1978                   0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
1979                   1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
1980                   
1981                 The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
1982                 The prop and xray parameters interact as follow::
1983                     prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
1984                     prop off, xray on : idem.
1985                     prop on,  xray off: return closest hit if it matches prop, no hit otherwise.
1986                     prop on,  xray on : return closest hit matching prop or no hit if there is no object matching prop on the full extend of the ray.
1987                 The L{KX_PolyProxy} 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray.
1988                 If there is no hit or the hit object is not a static mesh, None is returned as 4th element. 
1989                 
1990                 The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
1991
1992                 @param objto: [x,y,z] or object to which the ray is casted
1993                 @type objto: L{KX_GameObject} or 3-tuple
1994                 @param objfrom: [x,y,z] or object from which the ray is casted; None or omitted => use self object center
1995                 @type objfrom: L{KX_GameObject} or 3-tuple or None
1996                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
1997                 @type dist: float
1998                 @param prop: property name that object must have; can be omitted or "" => detect any object
1999                 @type prop: string
2000                 @param face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
2001                 @type face: int
2002                 @param xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
2003                 @type xray: int
2004                 @param poly: polygon option: 1=>return value is a 4-tuple and the 4th element is a L{KX_PolyProxy}
2005                 @type poly: int
2006                 @rtype:    3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz))
2007                         or 4-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), L{KX_PolyProxy})
2008                 @return: (object,hitpoint,hitnormal) or (object,hitpoint,hitnormal,polygon)
2009                          If no hit, returns (None,None,None) or (None,None,None,None)
2010                          If the object hit is not a static mesh, polygon is None
2011                 """
2012         def setCollisionMargin(margin):
2013                 """
2014                 Set the objects collision margin.
2015                 
2016                 note: If this object has no physics controller (a physics ID of zero), this function will raise RuntimeError.
2017                 
2018                 @type margin: float
2019                 @param margin: the collision margin distance in blender units.
2020                 """
2021         def sendMessage(subject, body="", to=""):
2022                 """
2023                 Sends a message.
2024         
2025                 @param subject: The subject of the message
2026                 @type subject: string
2027                 @param body: The body of the message (optional)
2028                 @type body: string
2029                 @param to: The name of the object to send the message to (optional)
2030                 @type to: string
2031                 """
2032         def reinstancePhysicsMesh(gameObject, meshObject):
2033                 """
2034                 Updates the physics system with the changed mesh.
2035                 
2036                 If no arguments are given the physics mesh will be re-created from the first mesh assigned to the game object.
2037
2038                 @param gameObject: optional argument, set the physics shape from this gameObjets mesh.
2039                 @type gameObject: string, L{KX_GameObject} or None
2040                 @param meshObject: optional argument, set the physics shape from this mesh.
2041                 @type meshObject: string, L{KX_MeshProxy} or None
2042
2043                 @note: if this object has instances the other instances will be updated too.
2044                 @note: the gameObject argument has an advantage that it can convert from a mesh with modifiers applied (such as subsurf).
2045                 @warning: only triangle mesh type objects are supported currently (not convex hull)
2046                 @warning: if the object is a part of a combound object it will fail (parent or child)
2047                 @warning: rebuilding the physics mesh can be slow, running many times per second will give a performance hit.
2048                 @rtype: boolean
2049                 @return: True if reinstance succeeded, False if it failed.
2050                 """
2051                 
2052         def get(key, default=None):
2053                 """
2054                 Return the value matching key, or the default value if its not found.
2055                 @return: The key value or a default.
2056                 """
2057         def has_key(key):
2058                 """
2059                 Return True if the key is found.
2060                 @rtype: boolean
2061                 @return: The key value or a default.
2062                 """
2063
2064
2065 class KX_IpoActuator(SCA_IActuator):
2066         """
2067         IPO actuator activates an animation.
2068         
2069         @ivar frameStart: Start frame.
2070         @type frameStart: float
2071         @ivar frameEnd: End frame.
2072         @type frameEnd: float
2073         @ivar propName: Use this property to define the Ipo position
2074         @type propName: string
2075         @ivar framePropName: Assign this property this action current frame number
2076         @type framePropName: string
2077         @ivar mode: Play mode for the ipo. (In GameLogic.KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND, KX_IPOACT_FROM_PROP)
2078         @type mode: int
2079         @ivar useIpoAsForce: Apply Ipo as a global or local force depending on the local option (dynamic objects only)
2080         @type useIpoAsForce: bool
2081         @ivar useIpoAdd: Ipo is added to the current loc/rot/scale in global or local coordinate according to Local flag
2082         @type useIpoAdd: bool
2083         @ivar useIpoLocal: Let the ipo acts in local coordinates, used in Force and Add mode.
2084         @type useIpoLocal: bool
2085         @ivar useChildren: Update IPO on all children Objects as well
2086         @type useChildren: bool
2087         """
2088 #{ Deprecated
2089         def set(mode, startframe, endframe, force):
2090                 """
2091                 Sets the properties of the actuator.
2092                 
2093                 @deprecated: use other attributes.
2094                 @param mode:       "Play", "PingPong", "Flipper", "LoopStop", "LoopEnd" or "FromProp"
2095                 @type mode: string
2096                 @param startframe: first frame to use
2097                 @type startframe: integer
2098                 @param endframe: last frame to use
2099                 @type endframe: integer
2100                 @param force: special mode
2101                 @type force: integer (0=normal, 1=interpret location as force, 2=additive)
2102                 """
2103         def setProperty(property):
2104                 """
2105                 Sets the name of the property to be used in FromProp mode.
2106                 
2107                 @deprecated: use L{propName}
2108                 @type property: string
2109                 """
2110         def setStart(startframe):
2111                 """
2112                 Sets the frame from which the IPO starts playing.
2113                 
2114                 @deprecated: use L{frameStart}
2115                 @type startframe: integer
2116                 """
2117         def getStart():
2118                 """
2119                 Returns the frame from which the IPO starts playing.
2120                 
2121                 @deprecated: use L{frameStart}
2122                 @rtype: integer
2123                 """
2124         def setEnd(endframe):
2125                 """
2126                 Sets the frame at which the IPO stops playing.
2127                 
2128                 @deprecated: use L{frameEnd}
2129                 @type endframe: integer
2130                 """
2131         def getEnd():
2132                 """
2133                 Returns the frame at which the IPO stops playing.
2134                 
2135                 @deprecated: use L{frameEnd}
2136                 @rtype: integer
2137                 """
2138         def setIpoAsForce(force):
2139                 """
2140                 Set whether to interpret the ipo as a force rather than a displacement.
2141                 
2142                 @deprecated: use L{useIpoAsForce}
2143                 @type force: boolean
2144                 @param force: KX_TRUE or KX_FALSE
2145                 """
2146         def getIpoAsForce():
2147                 """
2148                 Returns whether to interpret the ipo as a force rather than a displacement.
2149                 
2150                 @deprecated: use L{useIpoAsForce}
2151                 @rtype: boolean
2152                 """
2153         def setIpoAdd(add):
2154                 """
2155                 Set whether to interpret the ipo as additive rather than absolute.
2156                 
2157                 @deprecated: use L{useIpoAdd}
2158                 @type add: boolean
2159                 @param add: KX_TRUE or KX_FALSE
2160                 """
2161         def getIpoAdd():
2162                 """
2163                 Returns whether to interpret the ipo as additive rather than absolute.
2164                 
2165                 @deprecated: use L{useIpoAdd}
2166                 @rtype: boolean
2167                 """
2168         def setType(mode):
2169                 """
2170                 Sets the operation mode of the actuator.
2171                 
2172                 @deprecated: use L{type}
2173                 @param mode: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
2174                 @type mode: string
2175                 """
2176         def getType():
2177                 """
2178                 Returns the operation mode of the actuator.
2179                 
2180                 @deprecated: use L{type}
2181                 @rtype: integer
2182                 @return: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
2183                 """
2184         def setForceIpoActsLocal(local):
2185                 """
2186                 Set whether to apply the force in the object's local
2187                 coordinates rather than the world global coordinates.
2188         
2189                 @deprecated: use L{useIpoLocal}
2190                 @param local: Apply the ipo-as-force in the object's local
2191                               coordinates? (KX_TRUE, KX_FALSE)
2192                 @type local: boolean
2193                 """
2194         def getForceIpoActsLocal():
2195                 """
2196                 Return whether to apply the force in the object's local
2197                 coordinates rather than the world global coordinates.
2198                 
2199                 @deprecated: use L{useIpoLocal}
2200                 """
2201 #}
2202
2203 class KX_LightObject(KX_GameObject):
2204         """
2205         A Light object.
2206
2207         Example:
2208         
2209         # Turn on a red alert light.
2210         import GameLogic
2211         
2212         co = GameLogic.getCurrentController()
2213         light = co.owner
2214         
2215         light.energy = 1.0
2216         light.colour = [1.0, 0.0, 0.0]
2217         
2218         @group Constants: NORMAL, SPOT, SUN
2219         @ivar SPOT:   A spot light source. See attribute 'type'
2220         @ivar SUN:    A point light source with no attenuation. See attribute 'type'
2221         @ivar NORMAL: A point light source. See attribute 'type'
2222         
2223         @ivar type:            The type of light - must be SPOT, SUN or NORMAL
2224         @ivar layer:           The layer mask that this light affects object on.
2225         @type layer:           bitfield
2226         @ivar energy:          The brightness of this light. 
2227         @type energy:          float
2228         @ivar distance:        The maximum distance this light can illuminate. (SPOT and NORMAL lights only)
2229         @type distance:        float
2230         @ivar colour:          The colour of this light. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0]
2231         @type colour:          list [r, g, b]
2232         @ivar color:           Synonym for colour.
2233         @ivar lin_attenuation: The linear component of this light's attenuation. (SPOT and NORMAL lights only)
2234         @type lin_attenuation: float
2235         @ivar quad_attenuation: The quadratic component of this light's attenuation (SPOT and NORMAL lights only)
2236         @type quad_attenuation: float
2237         @ivar spotsize:        The cone angle of the spot light, in degrees. (float) (SPOT lights only)
2238                                0.0 <= spotsize <= 180.0. Spotsize = 360.0 is also accepted. 
2239         @ivar spotblend:       Specifies the intensity distribution of the spot light. (float) (SPOT lights only)
2240                                Higher values result in a more focused light source.
2241                                0.0 <= spotblend <= 1.0.
2242         
2243         """
2244
2245 class KX_MeshProxy(SCA_IObject):
2246         """
2247         A mesh object.
2248         
2249         You can only change the vertex properties of a mesh object, not the mesh topology.
2250         
2251         To use mesh objects effectively, you should know a bit about how the game engine handles them.
2252                 1. Mesh Objects are converted from Blender at scene load.
2253                 2. The Converter groups polygons by Material.  This means they can be sent to the
2254                    renderer efficiently.  A material holds:
2255                         1. The texture.
2256                         2. The Blender material.
2257                         3. The Tile properties
2258                         4. The face properties - (From the "Texture Face" panel)
2259                         5. Transparency & z sorting
2260                         6. Light layer
2261                         7. Polygon shape (triangle/quad)
2262                         8. Game Object
2263                 3. Verticies will be split by face if necessary.  Verticies can only be shared between
2264                    faces if:
2265                         1. They are at the same position
2266                         2. UV coordinates are the same
2267                         3. Their normals are the same (both polygons are "Set Smooth")
2268                         4. They are the same colour
2269                    For example: a cube has 24 verticies: 6 faces with 4 verticies per face.
2270                    
2271         The correct method of iterating over every L{KX_VertexProxy} in a game object::
2272                 import GameLogic
2273                 
2274                 co = GameLogic.getCurrentController()
2275                 obj = co.owner
2276                 
2277                 m_i = 0
2278                 mesh = obj.getMesh(m_i) # There can be more than one mesh...
2279                 while mesh != None:
2280                         for mat in range(mesh.getNumMaterials()):
2281                                 for v_index in range(mesh.getVertexArrayLength(mat)):
2282                                         vertex = mesh.getVertex(mat, v_index)
2283                                         # Do something with vertex here...
2284                                         # ... eg: colour the vertex red.
2285                                         vertex.colour = [1.0, 0.0, 0.0, 1.0]
2286                         m_i += 1
2287                         mesh = obj.getMesh(m_i)
2288         
2289         @ivar materials: 
2290         @type materials: list of L{KX_BlenderMaterial} or L{KX_PolygonMaterial} types
2291
2292         @ivar numPolygons:
2293         @type numPolygons: integer
2294
2295         @ivar numMaterials:
2296         @type numMaterials: integer
2297         """
2298         
2299         def getNumMaterials():
2300                 """
2301                 Gets the number of materials associated with this object.
2302                 
2303                 @rtype: integer
2304                 """
2305         
2306         def getMaterialName(matid):
2307                 """
2308                 Gets the name of the specified material.
2309                 
2310                 @type matid: integer
2311                 @param matid: the specified material.
2312                 @rtype: string
2313                 @return: the attached material name.
2314                 """
2315         def getTextureName(matid):
2316                 """
2317                 Gets the name of the specified material's texture.
2318                 
2319                 @type matid: integer
2320                 @param matid: the specified material
2321                 @rtype: string
2322                 @return: the attached material's texture name.
2323                 """
2324         def getVertexArrayLength(matid):
2325                 """
2326                 Gets the length of the vertex array associated with the specified material.
2327                 
2328                 There is one vertex array for each material.
2329                 
2330                 @type matid: integer
2331                 @param matid: the specified material
2332                 @rtype: integer
2333                 @return: the number of verticies in the vertex array.
2334                 """
2335         def getVertex(matid, index):
2336                 """
2337                 Gets the specified vertex from the mesh object.
2338                 
2339                 @type matid: integer
2340                 @param matid: the specified material
2341                 @type index: integer
2342                 @param index: the index into the vertex array.
2343                 @rtype: L{KX_VertexProxy}
2344                 @return: a vertex object.
2345                 """
2346         def getNumPolygons():
2347                 """
2348                 Returns the number of polygon in the mesh.
2349                 
2350                 @rtype: integer
2351                 """
2352         def getPolygon(index):
2353                 """
2354                 Gets the specified polygon from the mesh.
2355                 
2356                 @type index: integer
2357                 @param index: polygon number
2358                 @rtype: L{KX_PolyProxy}
2359                 @return: a polygon object.
2360                 """
2361
2362 class SCA_MouseSensor(SCA_ISensor):
2363         """
2364         Mouse Sensor logic brick.
2365         
2366         Properties:
2367         
2368         @ivar position: current [x,y] coordinates of the mouse, in frame coordinates (pixels)
2369         @type position: [integer,interger]
2370         @ivar mode: sensor mode: 1=KX_MOUSESENSORMODE_LEFTBUTTON  2=KX_MOUSESENSORMODE_MIDDLEBUTTON
2371                                  3=KX_MOUSESENSORMODE_RIGHTBUTTON 4=KX_MOUSESENSORMODE_WHEELUP
2372                                  5=KX_MOUSESENSORMODE_WHEELDOWN   9=KX_MOUSESENSORMODE_MOVEMENT
2373         @type mode: integer
2374         """
2375
2376         def getXPosition():
2377                 """
2378                 Gets the x coordinate of the mouse.
2379                 
2380                 @deprecated: use the L{position} property
2381                 @rtype: integer
2382                 @return: the current x coordinate of the mouse, in frame coordinates (pixels)
2383                 """
2384         def getYPosition():
2385                 """
2386                 Gets the y coordinate of the mouse.
2387                 
2388                 @deprecated: use the L{position} property
2389                 @rtype: integer
2390                 @return: the current y coordinate of the mouse, in frame coordinates (pixels).
2391                 """     
2392         def getButtonStatus(button):
2393                 """
2394                 Get the mouse button status.
2395                 
2396                 @type button: int
2397                 @param button: value in GameLogic members KX_MOUSE_BUT_LEFT, KX_MOUSE_BUT_MIDDLE, KX_MOUSE_BUT_RIGHT
2398                 
2399                 @rtype: integer
2400                 @return: value in GameLogic members KX_INPUT_NONE, KX_INPUT_NONE, KX_INPUT_JUST_ACTIVATED, KX_INPUT_ACTIVE, KX_INPUT_JUST_RELEASED
2401                 """
2402
2403 class KX_MouseFocusSensor(SCA_MouseSensor):
2404         """
2405         The mouse focus sensor detects when the mouse is over the current game object.
2406         
2407         The mouse focus sensor works by transforming the mouse coordinates from 2d device
2408         space to 3d space then raycasting away from the camera.
2409         
2410         @ivar raySource: The worldspace source of the ray (the view position)
2411         @type raySource: list (vector of 3 floats)
2412         @ivar rayTarget: The worldspace target of the ray.
2413         @type rayTarget: list (vector of 3 floats)
2414         @ivar rayDirection: The L{rayTarget} - L{raySource} normalized.
2415         @type rayDirection: list (normalized vector of 3 floats)
2416         @ivar hitObject: the last object the mouse was over.
2417         @type hitObject: L{KX_GameObject} or None
2418         @ivar hitPosition: The worldspace position of the ray intersecton.
2419         @type hitPosition: list (vector of 3 floats)
2420         @ivar hitNormal: the worldspace normal from the face at point of intersection.
2421         @type hitNormal: list (normalized vector of 3 floats)
2422         @ivar usePulseFocus: When enabled, moving the mouse over a different object generates a pulse. (only used when the 'Mouse Over Any' sensor option is set)
2423         @type usePulseFocus: bool
2424         """
2425 #{ Deprecated
2426         def getHitNormal():
2427                 """
2428                 Returns the normal (in worldcoordinates) at the point of collision where the object was hit by this ray.
2429                 
2430                 @deprecated: use the L{hitNormal} property
2431                 @rtype: list [x, y, z]
2432                 @return: the ray collision normal.
2433                 """
2434         def getHitObject():
2435                 """
2436                 Returns the object that was hit by this ray or None.
2437                 
2438                 @deprecated: use the L{hitObject} property
2439                 @rtype: L{KX_GameObject} or None
2440                 @return: the collision object.
2441                 """
2442         def getHitPosition():
2443                 """
2444                 Returns the position (in worldcoordinates) at the point of collision where the object was hit by this ray.
2445                 
2446                 @deprecated: use the L{hitPosition} property
2447                 @rtype: list [x, y, z]
2448                 @return: the ray collision position.
2449                 """
2450         def getRayDirection():
2451                 """
2452                 Returns the normalized direction (in worldcoordinates) of the ray cast by the mouse.
2453                 
2454                 @deprecated: use the L{rayDirection} property
2455                 @rtype: list [x, y, z]
2456                 @return: the ray direction.
2457                 """
2458         def getRaySource():
2459                 """
2460                 Returns the position (in worldcoordinates) the ray was cast from by the mouse.
2461                 
2462                 @deprecated: use the L{raySource} property
2463                 @rtype: list [x, y, z]
2464                 @return: the ray source.
2465                 """
2466         def getRayTarget():
2467                 """
2468                 Returns the target of the ray (in worldcoordinates) that seeks the focus object.
2469                 
2470                 @deprecated: use the L{rayTarget} property
2471                 @rtype: list [x, y, z]
2472                 @return: the ray target.
2473                 """
2474 #}
2475
2476 class KX_TouchSensor(SCA_ISensor):
2477         """
2478         Touch sensor detects collisions between objects.
2479         
2480         @ivar propName: The property or material to collide with.
2481         @type propName: string
2482         @ivar useMaterial: Determines if the sensor is looking for a property or material.
2483                                                 KX_True = Find material; KX_False = Find property
2484         @type useMaterial: boolean
2485         @ivar usePulseCollision: When enabled, changes to the set of colliding objects generate a pulse.
2486         @type usePulseCollision: bool
2487         @ivar hitObject: The last collided object. (read-only)
2488         @type hitObject: L{KX_GameObject} or None
2489         @ivar hitObjectList: A list of colliding objects. (read-only)
2490         @type hitObjectList: L{CListValue} of L{KX_GameObject}
2491         """
2492 #{ Deprecated
2493         def setProperty(name):
2494                 """
2495                 Set the property or material to collide with. Use
2496                 setTouchMaterial() to switch between properties and
2497                 materials.
2498                 
2499                 @deprecated: use the L{property} property
2500                 @type name: string
2501                 """
2502                 
2503         def getProperty():
2504                 """
2505                 Returns the property or material to collide with. Use
2506                 getTouchMaterial() to find out whether this sensor
2507                 looks for properties or materials.
2508                 
2509                 @deprecated: use the L{property} property
2510                 @rtype: string
2511                 """
2512         def getHitObject():
2513                 """
2514                 Returns the last object hit by this touch sensor.
2515                 
2516                 @deprecated: use the L{hitObject} property
2517                 @rtype: L{KX_GameObject}
2518                 """
2519         def getHitObjectList():
2520                 """
2521                 Returns a list of all objects hit in the last frame. (B{deprecated})
2522                 
2523                 Only objects that have the requisite material/property are listed.
2524                 
2525                 @deprecated: use the L{hitObjectList} property
2526                 @rtype: L{CListValue} of L{hitObjectList}
2527                 """
2528         def getTouchMaterial():
2529                 """
2530                 Returns KX_TRUE if this sensor looks for a specific material,
2531                 KX_FALSE if it looks for a specific property. (B{deprecated})
2532                 
2533                 @deprecated: use the L{useMaterial} property
2534                 """
2535 #}
2536
2537 class KX_NearSensor(KX_TouchSensor):
2538         """
2539         A near sensor is a specialised form of touch sensor.
2540         
2541         @ivar distance: The near sensor activates when an object is within this distance.
2542         @type distance: float
2543         @ivar resetDistance: The near sensor deactivates when the object exceeds this distance.
2544         @type resetDistance: float
2545         """
2546
2547 class KX_NetworkMessageActuator(SCA_IActuator):
2548         """
2549         Message Actuator
2550         
2551         @ivar propName: Messages will only be sent to objects with the given property name.
2552         @type propName: string
2553         @ivar subject: The subject field of the message.
2554         @type subject: string
2555         @ivar body: The body of the message.
2556         @type body: string
2557         @ivar usePropBody: Send a property instead of a regular body message.
2558         @type usePropBody: boolean
2559         """
2560 #{Deprecated
2561         def setToPropName(name):
2562                 """
2563                 Messages will only be sent to objects with the given property name.
2564                 
2565                 @deprecated: Use the L{propName} attribute instead.
2566                 @type name: string
2567                 """
2568         def setSubject(subject):
2569                 """
2570                 Sets the subject field of the message.
2571                 
2572                 @deprecated: Use the L{subject} attribute instead.
2573                 @type subject: string
2574                 """
2575         def setBodyType(bodytype):
2576                 """
2577                 Sets the type of body to send.
2578                 
2579                 @deprecated: Use the L{usePropBody} attribute instead.
2580                 @type bodytype: boolean
2581                 @param bodytype: True to send the value of a property, False to send the body text.
2582                 """
2583         def setBody(body):
2584                 """
2585                 Sets the message body.
2586                 
2587                 @deprecated: Use the L{body} attribute instead.
2588                 @type body: string
2589                 @param body: if the body type is True, this is the name of the property to send.
2590                              if the body type is False, this is the text to send.
2591                 """
2592 #}
2593
2594 class KX_NetworkMessageSensor(SCA_ISensor):
2595         """
2596         The Message Sensor logic brick.
2597         
2598         Currently only loopback (local) networks are supported.
2599         
2600         @ivar subject: The subject the sensor is looking for.
2601         @type subject: string
2602         @ivar frameMessageCount: The number of messages received since the last frame.
2603                                                                 (Read-only)
2604         @type frameMessageCount: int
2605         @ivar subjects: The list of message subjects received. (Read-only)
2606         @type subjects: list of strings
2607         @ivar bodies: The list of message bodies received. (Read-only)
2608         @type bodies: list of strings
2609         """
2610 #{ Deprecated
2611         def setSubjectFilterText(subject):
2612                 """
2613                 Change the message subject text that this sensor is listening to.
2614                 
2615                 @deprecated: Use the L{subject} attribute instead.
2616                 @type subject: string
2617                 @param subject: the new message subject to listen for.
2618                 """
2619         
2620         def getFrameMessageCount():
2621                 """
2622                 Get the number of messages received since the last frame.
2623                 
2624                 @deprecated: Use the L{frameMessageCount} attribute instead.
2625                 @rtype: integer
2626                 """
2627         def getBodies():
2628                 """
2629                 Gets the list of message bodies.
2630                 
2631                 @deprecated: Use the L{bodies} attribute instead.
2632                 @rtype: list
2633                 """
2634         def getSubject():
2635                 """
2636                 Gets the message subject this sensor is listening for from the Subject: field.
2637                 
2638                 @deprecated: Use the L{subject} attribute instead.
2639                 @rtype: string
2640                 """
2641         def getSubjects():
2642                 """
2643                 Gets the list of message subjects received.
2644                 
2645                 @deprecated: Use the L{subjects} attribute instead.
2646                 @rtype: list
2647                 """
2648 #}
2649
2650 class KX_ObjectActuator(SCA_IActuator):
2651         """
2652         The object actuator ("Motion Actuator") applies force, torque, displacement, angular displacement,
2653         velocity, or angular velocity to an object.
2654         Servo control allows to regulate force to achieve a certain speed target.
2655         
2656         @ivar force: The force applied by the actuator
2657         @type force: list [x, y, z]
2658         @ivar useLocalForce: A flag specifying if the force is local
2659         @type useLocalForce: bool
2660         @ivar torque: The torque applied by the actuator
2661         @type torque: list [x, y, z]
2662         @ivar useLocalTorque: A flag specifying if the torque is local
2663         @type useLocalTorque: bool
2664         @ivar dLoc: The displacement vector applied by the actuator
2665         @type dLoc: list [x, y, z]
2666         @ivar useLocalDLoc: A flag specifying if the dLoc is local
2667         @type useLocalDLoc: bool
2668         @ivar dRot: The angular displacement vector applied by the actuator
2669                 - note: Since the displacement is applied every frame, you must adjust the displacement
2670                 based on the frame rate, or you game experience will depend on the player's computer
2671                 speed.
2672         @type dRot: list [x, y, z]
2673         @ivar useLocalDRot: A flag specifying if the dRot is local
2674         @type useLocalDRot: bool
2675         @ivar linV: The linear velocity applied by the actuator
2676         @type linV: list [x, y, z]
2677         @ivar useLocalLinV: A flag specifying if the linear velocity is local
2678                 - note: This is the target speed for servo controllers
2679         @type useLocalLinV: bool
2680         @ivar angV: The angular velocity applied by the actuator
2681         @type angV: list [x, y, z]
2682         @ivar useLocalAngV: A flag specifying if the angular velocity is local
2683         @type useLocalAngV: bool
2684         
2685         @ivar damping: The damping parameter of the servo controller
2686         @type damping: short
2687         
2688         @ivar forceLimitX: The min/max force limit along the X axis and activates or deactivates the limits in the servo controller
2689         @type forceLimitX: list [min(float), max(float), bool]
2690         @ivar forceLimitY: The min/max force limit along the Y axis and activates or deactivates the limits in the servo controller
2691         @type forceLimitY: list [min(float), max(float), bool]
2692         @ivar forceLimitZ: The min/max force limit along the Z axis and activates or deactivates the limits in the servo controller
2693         @type forceLimitZ: list [min(float), max(float), bool]
2694         
2695         @ivar pid: The PID coefficients of the servo controller
2696         @type pid: list of floats [proportional, integral, derivate]
2697         @ivar reference: The object that is used as reference to compute the velocity for the servo controller.
2698         @type reference: KX_GameObject or None
2699         
2700         @group Deprecated: getForce, setForce, getTorque, setTorque, getDLoc, setDLoc, getDRot, setDRot, getLinearVelocity, setLinearVelocity, getAngularVelocity,
2701                                                 setAngularVelocity, getDamping, setDamping, getForceLimitX, setForceLimitX, getForceLimitY, setForceLimitY, getForceLimitZ, setForceLimitZ,
2702                                                 getPID, setPID
2703         """
2704         def getForce():
2705                 """
2706                 Returns the force applied by the actuator.
2707
2708                 @deprecated: Use L{force} and L{useLocalForce} instead.
2709                 @rtype: list [fx, fy, fz, local]
2710                 @return: A four item list, containing the vector force, and a flag specifying whether the force is local.
2711                 """
2712         def setForce(fx, fy, fz, local):
2713                 """
2714                 Sets the force applied by the actuator.
2715                 
2716                 @deprecated: Use L{force} and L{useLocalForce} instead.
2717                 @type fx: float
2718                 @param fx: the x component of the force.
2719                 @type fy: float
2720                 @param fy: the z component of the force.
2721                 @type fz: float
2722                 @param fz: the z component of the force.
2723                 @type local: boolean
2724                 @param local: - False: the force is applied in world coordinates.
2725                               - True: the force is applied in local coordinates.
2726                 """
2727         def getTorque():
2728                 """
2729                 Returns the torque applied by the actuator.
2730                 
2731                 @deprecated: Use L{torque} and L{useLocalTorque} instead.
2732                 @rtype: list [S{Tau}x, S{Tau}y, S{Tau}z, local]
2733                 @return: A four item list, containing the vector torque, and a flag specifying whether
2734                          the torque is applied in local coordinates (True) or world coordinates (False)
2735                 """
2736         def setTorque(tx, ty, tz, local):
2737                 """
2738                 Sets the torque applied by the actuator.
2739                 
2740                 @deprecated: Use L{torque} and L{useLocalTorque} instead.
2741                 @type tx: float
2742                 @param tx: the x component of the torque.
2743                 @type ty: float
2744                 @param ty: the z component of the torque.
2745                 @type tz: float
2746                 @param tz: the z component of the torque.
2747                 @type local: boolean
2748                 @param local: - False: the torque is applied in world coordinates.
2749                               - True: the torque is applied in local coordinates.
2750                 """
2751         def getDLoc():
2752                 """
2753                 Returns the displacement vector applied by the actuator.
2754                 
2755                 @deprecated: Use L{dLoc} and L{useLocalDLoc} instead.
2756                 @rtype: list [dx, dy, dz, local]
2757                 @return: A four item list, containing the vector displacement, and whether
2758                          the displacement is applied in local coordinates (True) or world
2759                          coordinates (False)
2760                 """
2761         def setDLoc(dx, dy, dz, local):
2762                 """
2763                 Sets the displacement vector applied by the actuator.
2764                 
2765                 Since the displacement is applied every frame, you must adjust the displacement
2766                 based on the frame rate, or you game experience will depend on the player's computer
2767                 speed.
2768                 
2769                 @deprecated: Use L{dLoc} and L{useLocalDLoc} instead.
2770                 @type dx: float
2771                 @param dx: the x component of the displacement vector.
2772                 @type dy: float
2773                 @param dy: the z component of the displacement vector.
2774                 @type dz: float
2775                 @param dz: the z component of the displacement vector.
2776                 @type local: boolean
2777                 @param local: - False: the displacement vector is applied in world coordinates.
2778                               - True: the displacement vector is applied in local coordinates.
2779                 """
2780         def getDRot():
2781                 """
2782                 Returns the angular displacement vector applied by the actuator.
2783                 
2784                 @deprecated: Use L{dRot} and L{useLocalDRot} instead.
2785                 @rtype: list [dx, dy, dz, local]
2786                 @return: A four item list, containing the angular displacement vector, and whether
2787                          the displacement is applied in local coordinates (True) or world coordinates (False)
2788                 """
2789         def setDRot(dx, dy, dz, local):
2790                 """
2791                 Sets the angular displacement vector applied by the actuator.
2792                 
2793                 Since the displacement is applied every frame, you must adjust the displacement
2794                 based on the frame rate, or you game experience will depend on the player's computer
2795                 speed.
2796                 
2797                 @deprecated: Use L{dRot} and L{useLocalDRot} instead.
2798                 @type dx: float
2799                 @param dx: the x component of the angular displacement vector.
2800                 @type dy: float
2801                 @param dy: the z component of the angular displacement vector.
2802                 @type dz: float
2803                 @param dz: the z component of the angular displacement vector.
2804                 @type local: boolean
2805                 @param local: - False: the angular displacement vector is applied in world coordinates.
2806                               - True: the angular displacement vector is applied in local coordinates.
2807                 """
2808         def getLinearVelocity():
2809                 """
2810                 Returns the linear velocity applied by the actuator.
2811                 For the servo control actuator, this is the target speed.
2812
2813                 @deprecated: Use L{linV} and L{useLocalLinV} instead.
2814                 @rtype: list [vx, vy, vz, local]
2815                 @return: A four item list, containing the vector velocity, and whether the velocity is applied in local coordinates (True) or world coordinates (False)
2816                 """
2817         def setLinearVelocity(vx, vy, vz, local):
2818                 """
2819                 Sets the linear velocity applied by the actuator.
2820                 For the servo control actuator, sets the target speed.
2821
2822                 @deprecated: Use L{linV} and L{useLocalLinV} instead.
2823                 @type vx: float
2824                 @param vx: the x component of the velocity vector.
2825                 @type vy: float
2826                 @param vy: the z component of the velocity vector.
2827                 @type vz: float
2828                 @param vz: the z component of the velocity vector.
2829                 @type local: boolean
2830                 @param local: - False: the velocity vector is in world coordinates.
2831                               - True: the velocity vector is in local coordinates.
2832                 """
2833         def getAngularVelocity():
2834                 """
2835                 Returns the angular velocity applied by the actuator.
2836
2837                 @deprecated: Use L{angV} and L{useLocalAngV} instead.
2838                 @rtype: list [S{omega}x, S{omega}y, S{omega}z, local]
2839                 @return: A four item list, containing the vector velocity, and whether
2840                          the velocity is applied in local coordinates (True) or world
2841                          coordinates (False)
2842                 """
2843         def setAngularVelocity(wx, wy, wz, local):
2844                 """
2845                 Sets the angular velocity applied by the actuator.
2846
2847                 @deprecated: Use L{angV} and L{useLocalAngV} instead.
2848                 @type wx: float
2849                 @param wx: the x component of the velocity vector.
2850                 @type wy: float
2851                 @param wy: the z component of the velocity vector.
2852                 @type wz: float
2853                 @param wz: the z component of the velocity vector.
2854                 @type local: boolean
2855                 @param local: - False: the velocity vector is applied in world coordinates.
2856                               - True: the velocity vector is applied in local coordinates.
2857                 """
2858         def getDamping():
2859                 """
2860                 Returns the damping parameter of the servo controller.
2861
2862                 @deprecated: Use L{damping} instead.
2863                 @rtype: integer
2864                 @return: the time constant of the servo controller in frame unit.
2865                 """
2866         def setDamping(damp):
2867                 """
2868                 Sets the damping parameter of the servo controller.
2869
2870                 @deprecated: Use L{damping} instead.
2871                 @type damp: integer
2872                 @param damp: the damping parameter in frame unit.
2873                 """
2874         def getForceLimitX():
2875                 """
2876                 Returns the min/max force limit along the X axis used by the servo controller.
2877
2878                 @deprecated: Use L{forceLimitX} instead.
2879                 @rtype: list [min, max, enabled]
2880                 @return: A three item list, containing the min and max limits of the force as float
2881                          and whether the limits are active(true) or inactive(true)
2882                 """
2883         def setForceLimitX(min, max, enable):
2884                 """
2885                 Sets the min/max force limit along the X axis and activates or deactivates the limits in the servo controller.
2886
2887                 @deprecated: Use L{forceLimitX} instead.
2888                 @type min: float
2889                 @param min: the minimum value of the force along the X axis.
2890                 @type max: float
2891                 @param max: the maximum value of the force along the X axis.
2892                 @type enable: boolean
2893                 @param enable: - True: the force will be limited to the min/max
2894                                - False: the force will not be limited                          
2895                 """
2896         def getForceLimitY():
2897                 """
2898                 Returns the min/max force limit along the Y axis used by the servo controller.
2899
2900                 @deprecated: Use L{forceLimitY} instead.
2901                 @rtype: list [min, max, enabled]
2902                 @return: A three item list, containing the min and max limits of the force as float
2903                          and whether the limits are active(true) or inactive(true)
2904                 """
2905         def setForceLimitY(min, max, enable):
2906                 """
2907                 Sets the min/max force limit along the Y axis and activates or deactivates the limits in the servo controller.
2908
2909                 @deprecated: Use L{forceLimitY} instead.
2910                 @type min: float
2911                 @param min: the minimum value of the force along the Y axis.
2912                 @type max: float
2913                 @param max: the maximum value of the force along the Y axis.
2914                 @type enable: boolean
2915                 @param enable: - True: the force will be limited to the min/max
2916                                - False: the force will not be limited                          
2917                 """
2918         def getForceLimitZ():
2919                 """
2920                 Returns the min/max force limit along the Z axis used by the servo controller.
2921
2922                 @deprecated: Use L{forceLimitZ} instead.
2923                 @rtype: list [min, max, enabled]
2924                 @return: A three item list, containing the min and max limits of the force as float
2925                          and whether the limits are active(true) or inactive(true)
2926                 """
2927         def setForceLimitZ(min, max, enable):
2928                 """
2929                 Sets the min/max force limit along the Z axis and activates or deactivates the limits in the servo controller.
2930
2931                 @deprecated: Use L{forceLimitZ} instead.
2932                 @type min: float
2933                 @param min: the minimum value of the force along the Z axis.
2934                 @type max: float
2935                 @param max: the maximum value of the force along the Z axis.
2936                 @type enable: boolean
2937                 @param enable: - True: the force will be limited to the min/max
2938                                - False: the force will not be limited                          
2939                 """
2940         def getPID():
2941                 """
2942                 Returns the PID coefficient of the servo controller.
2943
2944                 @deprecated: Use L{pid} instead.
2945                 @rtype: list [P, I, D]
2946                 @return: A three item list, containing the PID coefficient as floats:
2947                          P : proportional coefficient
2948                          I : Integral coefficient
2949                          D : Derivate coefficient
2950                 """
2951         def setPID(P, I, D):
2952                 """
2953                 Sets the PID coefficients of the servo controller.
2954
2955                 @deprecated: Use L{pid} instead.
2956                 @type P: flat
2957                 @param P: proportional coefficient
2958                 @type I: float
2959                 @param I: Integral coefficient
2960                 @type D: float
2961                 @param D: Derivate coefficient
2962                 """
2963
2964 class KX_ParentActuator(SCA_IActuator):
2965         """
2966         The parent actuator can set or remove an objects parent object. 
2967         @ivar object: the object this actuator sets the parent too.
2968         @type object: KX_GameObject or None
2969         @ivar mode: The mode of this actuator
2970         @type mode: int from 0 to 1 L{GameLogic.Parent Actuator}
2971         @ivar compound: Whether the object shape should be added to the parent compound shape when parenting
2972                         Effective only if the parent is already a compound shape
2973         @type compound: bool
2974         @ivar ghost: whether the object should be made ghost when parenting
2975                      Effective only if the shape is not added to the parent compound shape
2976         @type ghost: bool
2977         
2978         """
2979         def setObject(object):
2980                 """
2981                 Sets the object to set as parent.
2982                 
2983                 Object can be either a L{KX_GameObject} or the name of the object.
2984                 
2985                 @deprecated: Use the L{object} property.
2986                 @type object: L{KX_GameObject}, string or None
2987                 """
2988         def getObject(name_only = 1):
2989                 """
2990                 Returns the name of the object to change to.
2991                 
2992                 @deprecated: Use the L{object} property.
2993                 @type name_only: bool
2994                 @param name_only: optional argument, when 0 return a KX_GameObject
2995                 @rtype: string, KX_GameObject or None if no object is set
2996                 """
2997
2998 class KX_PhysicsObjectWrapper(PyObjectPlus):
2999         """
3000         KX_PhysicsObjectWrapper
3001         
3002         """
3003         def setActive(active):
3004                 """
3005                 Set the object to be active.
3006                 
3007                 @param active: set to True to be active