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