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