add 2 new utility functions to the BGE mesh py api.
[blender.git] / doc / python_api / rst / bge.types.rst
1
2 Game Types (bge.types)
3 ======================
4
5 .. module:: bge.types
6
7 ************
8 Introduction
9 ************
10
11 This module contains the classes that appear as instances in the Game Engine. A
12 script must interact with these classes if it is to affect the behaviour of
13 objects in a game.
14
15 The following example would move an object (i.e. an instance of
16 :class:`KX_GameObject`) one unit up.
17
18 .. code-block:: python
19
20    # bge.types.SCA_PythonController
21    cont = bge.logic.getCurrentController()
22
23    # bge.types.KX_GameObject
24    obj = cont.owner
25    obj.worldPosition.z += 1
26
27 To run the code, it could be placed in a Blender text block and executed with
28 a :class:`SCA_PythonController` logic brick.
29
30 *****
31 Types
32 *****
33
34 .. class:: PyObjectPlus
35
36    PyObjectPlus base class of most other types in the Game Engine.
37
38    .. attribute:: invalid
39
40       Test if the object has been freed by the game engine and is no longer valid.
41        
42       Normally this is not a problem but when storing game engine data in the GameLogic module, 
43       KX_Scenes or other KX_GameObjects its possible to hold a reference to invalid data.
44       Calling an attribute or method on an invalid object will raise a SystemError.
45        
46       The invalid attribute allows testing for this case without exception handling.
47
48       :type: boolean
49
50 .. class:: CValue(PyObjectPlus)
51
52    This class is a basis for other classes.
53
54    .. attribute:: name
55
56       The name of this CValue derived object (read-only).
57
58       :type: string
59       
60 .. class:: CPropValue(CValue)
61
62    This class has no python functions
63
64 .. class:: SCA_ILogicBrick(CValue)
65
66    Base class for all logic bricks.
67
68    .. attribute:: executePriority
69
70       This determines the order controllers are evaluated, and actuators are activated (lower priority is executed first).
71
72       :type: executePriority: int
73
74    .. attribute:: owner
75
76       The game object this logic brick is attached to (read-only).
77       
78       :type: :class:`KX_GameObject` or None in exceptional cases.
79
80    .. attribute:: name
81
82       The name of this logic brick (read-only).
83       
84       :type: string
85
86 .. class:: SCA_PythonKeyboard(PyObjectPlus)
87
88    The current keyboard.
89
90    .. attribute:: events
91
92       A dictionary containing the status of each keyboard event or key. (read-only).
93
94       :type: dictionary {:ref:`keycode<keyboard-keys>`::ref:`status<input-status>`, ...}
95
96    .. attribute:: active_events
97
98       A dictionary containing the status of only the active keyboard events or keys. (read-only).
99
100       :type: dictionary {:ref:`keycode<keyboard-keys>`::ref:`status<input-status>`, ...}
101
102
103    .. function:: getClipboard()
104
105       Gets the clipboard text.
106
107       :rtype: string
108
109    .. function:: setClipboard(text)
110
111       Sets the clipboard text.
112
113       :arg text: New clipboard text
114       :type text: string
115
116 .. class:: SCA_PythonMouse(PyObjectPlus)
117
118    The current mouse.
119
120    .. attribute:: events
121
122       a dictionary containing the status of each mouse event. (read-only).
123
124       :type: dictionary {:ref:`keycode<mouse-keys>`::ref:`status<input-status>`, ...}
125
126    .. attribute:: active_events
127
128       a dictionary containing the status of only the active mouse events. (read-only).
129
130       :type: dictionary {:ref:`keycode<mouse-keys>`::ref:`status<input-status>`, ...}
131       
132    .. attribute:: position
133
134       The normalized x and y position of the mouse cursor.
135
136       :type: list [x, y]
137
138    .. attribute:: visible
139
140       The visibility of the mouse cursor.
141       
142       :type: boolean
143
144 .. class:: SCA_IObject(CValue)
145
146    This class has no python functions
147
148 .. class:: SCA_ISensor(SCA_ILogicBrick)
149
150    Base class for all sensor logic bricks.
151
152    .. attribute:: usePosPulseMode
153
154       Flag to turn positive pulse mode on and off.
155       
156       :type: boolean
157
158    .. attribute:: useNegPulseMode
159
160       Flag to turn negative pulse mode on and off.
161       
162       :type: boolean
163
164    .. attribute:: frequency
165
166       The frequency for pulse mode sensors.
167       
168       :type: integer
169
170    .. attribute:: level
171
172       level Option whether to detect level or edge transition when entering a state.
173       It makes a difference only in case of logic state transition (state actuator).
174       A level detector will immediately generate a pulse, negative or positive
175       depending on the sensor condition, as soon as the state is activated.
176       A edge detector will wait for a state change before generating a pulse.
177       note: mutually exclusive with :data:`tap`, enabling will disable :data:`tap`.
178
179       :type: boolean
180
181    .. attribute:: tap
182
183       When enabled only sensors that are just activated will send a positive event, 
184       after this they will be detected as negative by the controllers.
185       This will make a key thats held act as if its only tapped for an instant.
186       note: mutually exclusive with :data:`level`, enabling will disable :data:`level`.
187
188       :type: boolean
189
190    .. attribute:: invert
191
192       Flag to set if this sensor activates on positive or negative events.
193       
194       :type: boolean
195
196    .. attribute:: triggered
197
198       True if this sensor brick is in a positive state. (read-only).
199      
200       :type: boolean
201
202    .. attribute:: positive
203
204       True if this sensor brick is in a positive state. (read-only).
205       
206       :type: boolean
207
208    .. attribute:: status
209
210       The status of the sensor (read-only): can be one of :ref:`these constants<sensor-status>`.
211
212       :type: int
213
214       .. note::
215       
216          This convenient attribute combines the values of triggered and positive attributes.
217
218    .. method:: reset()
219
220       Reset sensor internal state, effect depends on the type of sensor and settings.
221
222       The sensor is put in its initial state as if it was just activated.
223
224 .. class:: SCA_IController(SCA_ILogicBrick)
225
226    Base class for all controller logic bricks.
227
228    .. attribute:: state
229
230       The controllers state bitmask. This can be used with the GameObject's state to test if the controller is active.
231       
232       :type: int bitmask
233
234    .. attribute:: sensors
235
236       A list of sensors linked to this controller.
237       
238       :type: sequence supporting index/string lookups and iteration.
239
240       .. note::
241
242          The sensors are not necessarily owned by the same object.
243
244       .. note::
245          
246          When objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
247
248    .. attribute:: actuators
249
250       A list of actuators linked to this controller.
251       
252       :type: sequence supporting index/string lookups and iteration.
253
254       .. note::
255
256          The sensors are not necessarily owned by the same object.
257
258       .. note::
259          
260          When objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
261
262    .. attribute:: useHighPriority
263
264       When set the controller executes always before all other controllers that dont have this set.
265       
266       :type: boolen
267
268       .. note::
269          
270          Order of execution between high priority controllers is not guaranteed.
271
272 .. class:: SCA_IActuator(SCA_ILogicBrick)
273
274    Base class for all actuator logic bricks.
275
276 .. class:: BL_ActionActuator(SCA_IActuator)
277
278    Action Actuators apply an action to an actor.
279
280    .. attribute:: action
281
282       The name of the action to set as the current action.
283
284       :type: string
285
286    .. attribute:: frameStart
287
288       Specifies the starting frame of the animation.
289
290       :type: float
291
292    .. attribute:: frameEnd
293
294       Specifies the ending frame of the animation.
295
296       :type: float
297
298    .. attribute:: blendIn
299
300       Specifies the number of frames of animation to generate when making transitions between actions.
301
302       :type: float
303
304    .. attribute:: priority
305
306       Sets the priority of this actuator. Actuators will lower priority numbers will override actuators with higher numbers.
307
308       :type: integer
309
310    .. attribute:: frame
311
312       Sets the current frame for the animation.
313
314       :type: float
315
316    .. attribute:: propName
317
318       Sets the property to be used in FromProp playback mode.
319
320       :type: string
321
322    .. attribute:: blendTime
323
324       Sets the internal frame timer. This property must be in the range from 0.0 to blendIn.
325
326       :type: float
327
328    .. attribute:: mode
329
330       The operation mode of the actuator. Can be one of :ref:`these constants<action-actuator>`.
331
332       :type: integer
333
334    .. attribute:: useContinue
335
336       The actions continue option, True or False. When True, the action will always play from where last left off,
337       otherwise negative events to this actuator will reset it to its start frame.
338
339       :type: boolean
340
341    .. attribute:: framePropName
342
343       The name of the property that is set to the current frame number.
344
345       :type: string
346
347 .. class:: BL_Shader(PyObjectPlus)
348
349    BL_Shader GLSL shaders.
350
351    TODO - Description
352
353    .. method:: setUniformfv(name, fList)
354
355       Set a uniform with a list of float values
356
357       :arg name: the uniform name
358       :type name: string
359       :arg fList: a list (2, 3 or 4 elements) of float values
360       :type fList: list[float]
361
362    .. method:: delSource()
363
364       Clear the shader. Use this method before the source is changed with :data:`setSource`.
365
366    .. method:: getFragmentProg()
367
368       Returns the fragment program.
369
370       :return: The fragment program.
371       :rtype: string
372
373    .. method:: getVertexProg()
374
375       Get the vertex program.
376
377       :return: The vertex program.
378       :rtype: string
379
380    .. method:: isValid()
381
382       Check if the shader is valid.
383
384       :return: True if the shader is valid
385       :rtype: boolean
386
387    .. method:: setAttrib(enum)
388
389       Set attribute location. (The parameter is ignored a.t.m. and the value of "tangent" is always used.)
390
391       :arg enum: attribute location value
392       :type enum: integer
393
394    .. method:: setNumberOfPasses( max_pass )
395
396       Set the maximum number of passes. Not used a.t.m.
397
398       :arg max_pass: the maximum number of passes
399       :type max_pass: integer
400
401    .. method:: setSampler(name, index)
402
403       Set uniform texture sample index.
404
405       :arg name: Uniform name
406       :type name: string
407       :arg index: Texture sample index.
408       :type index: integer
409
410    .. method:: setSource(vertexProgram, fragmentProgram)
411
412       Set the vertex and fragment programs
413
414       :arg vertexProgram: Vertex program
415       :type vertexProgram: string
416       :arg fragmentProgram: Fragment program
417       :type fragmentProgram: string
418
419    .. method:: setUniform1f(name, fx)
420
421       Set a uniform with 1 float value.
422
423       :arg name: the uniform name
424       :type name: string
425       :arg fx: Uniform value
426       :type fx: float
427
428    .. method:: setUniform1i(name, ix)
429
430       Set a uniform with an integer value.
431
432       :arg name: the uniform name
433       :type name: string
434       :arg ix: the uniform value
435       :type ix: integer
436
437    .. method:: setUniform2f(name, fx, fy)
438
439       Set a uniform with 2 float values
440
441       :arg name: the uniform name
442       :type name: string
443       :arg fx: first float value
444       :type fx: float
445
446       :arg fy: second float value
447       :type fy: float
448
449    .. method:: setUniform2i(name, ix, iy)
450
451       Set a uniform with 2 integer values
452
453       :arg name: the uniform name
454       :type name: string
455       :arg ix: first integer value
456       :type ix: integer
457       :arg iy: second integer value
458       :type iy: integer
459
460    .. method:: setUniform3f(name, fx, fy, fz)
461
462       Set a uniform with 3 float values.
463
464       :arg name: the uniform name
465       :type name: string
466       :arg fx: first float value
467       :type fx: float
468       :arg fy: second float value
469       :type fy: float
470       :arg fz: third float value
471       :type fz: float
472
473    .. method:: setUniform3i(name, ix, iy, iz)
474
475       Set a uniform with 3 integer values
476
477       :arg name: the uniform name
478       :type name: string
479       :arg ix: first integer value
480       :type ix: integer
481       :arg iy: second integer value
482       :type iy: integer
483       :arg iz: third integer value
484       :type iz: integer
485
486    .. method:: setUniform4f(name, fx, fy, fz, fw)
487
488       Set a uniform with 4 float values.
489
490       :arg name: the uniform name
491       :type name: string
492       :arg fx: first float value
493       :type fx: float
494       :arg fy: second float value
495       :type fy: float
496       :arg fz: third float value
497       :type fz: float
498       :arg fw: fourth float value
499       :type fw: float
500
501    .. method:: setUniform4i(name, ix, iy, iz, iw)
502
503       Set a uniform with 4 integer values
504
505       :arg name: the uniform name
506       :type name: string
507       :arg ix: first integer value
508       :type ix: integer
509       :arg iy: second integer value
510       :type iy: integer
511       :arg iz: third integer value
512       :type iz: integer
513       :arg iw: fourth integer value
514       :type iw: integer
515
516    .. method:: setUniformDef(name, type)
517
518       Define a new uniform
519
520       :arg name: the uniform name
521       :type name: string
522       :arg type: uniform type
523       :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
524
525    .. method:: setUniformMatrix3(name, mat, transpose)
526
527       Set a uniform with a 3x3 matrix value
528
529       :arg name: the uniform name
530       :type name: string
531       :arg mat: A 3x3 matrix [[f, f, f], [f, f, f], [f, f, f]]
532       :type mat: 3x3 matrix
533       :arg transpose: set to True to transpose the matrix
534       :type transpose: boolean
535
536    .. method:: setUniformMatrix4(name, mat, transpose)
537
538       Set a uniform with a 4x4 matrix value
539
540       :arg name: the uniform name
541       :type name: string
542       :arg mat: A 4x4 matrix [[f, f, f, f], [f, f, f, f], [f, f, f, f], [f, f, f, f]]
543       :type mat: 4x4 matrix
544       :arg transpose: set to True to transpose the matrix
545       :type transpose: boolean
546
547    .. method:: setUniformiv(name, iList)
548
549       Set a uniform with a list of integer values
550
551       :arg name: the uniform name
552       :type name: string
553       :arg iList: a list (2, 3 or 4 elements) of integer values
554       :type iList: list[integer]
555
556    .. method:: validate()
557
558       Validate the shader object.
559
560 .. class:: BL_ShapeActionActuator(SCA_IActuator)
561
562    ShapeAction Actuators apply an shape action to an mesh object.
563
564    .. attribute:: action
565
566       The name of the action to set as the current shape action.
567
568       :type: string
569
570    .. attribute:: frameStart
571
572       Specifies the starting frame of the shape animation.
573
574       :type: float
575
576    .. attribute:: frameEnd
577
578       Specifies the ending frame of the shape animation.
579
580       :type: float
581
582    .. attribute:: blendIn
583
584       Specifies the number of frames of animation to generate when making transitions between actions.
585
586       :type: float
587
588    .. attribute:: priority
589
590       Sets the priority of this actuator. Actuators will lower priority numbers will override actuators with higher numbers.
591
592       :type: integer
593
594    .. attribute:: frame
595
596       Sets the current frame for the animation.
597
598       :type: float
599
600    .. attribute:: propName
601
602       Sets the property to be used in FromProp playback mode.
603
604       :type: string
605
606    .. attribute:: blendTime
607
608       Sets the internal frame timer. This property must be in the range from 0.0 to blendin.
609
610       :type: float
611
612    .. attribute:: mode
613
614       The operation mode of the actuator. Can be one of :ref:`these constants<shape-action-actuator>`.
615
616       :type: integer
617
618    .. attribute:: framePropName
619
620       The name of the property that is set to the current frame number.
621
622       :type: string
623
624 .. class:: CListValue(CPropValue)
625
626    This is a list like object used in the game engine internally that behaves similar to a python list in most ways.
627
628    As well as the normal index lookup (``val= clist[i]``), CListValue supports string lookups (``val= scene.objects["Cube"]``)
629
630    Other operations such as ``len(clist)``, ``list(clist)``, ``clist[0:10]`` are also supported.
631
632    .. method:: append(val)
633
634       Add an item to the list (like pythons append)
635
636       .. warning::
637       
638          Appending values to the list can cause crashes when the list is used internally by the game engine.
639
640    .. method:: count(val)
641
642       Count the number of instances of a value in the list.
643
644       :return: number of instances
645       :rtype: integer
646
647    .. method:: index(val)
648
649       Return the index of a value in the list.
650
651       :return: The index of the value in the list.
652       :rtype: integer
653
654    .. method:: reverse()
655
656       Reverse the order of the list.
657
658    .. method:: get(key, default=None)
659
660       Return the value matching key, or the default value if its not found.
661
662       :return: The key value or a default.
663
664    .. method:: from_id(id)
665
666       This is a funtion especially for the game engine to return a value with a spesific id.
667
668       Since object names are not always unique, the id of an object can be used to get an object from the CValueList.
669
670       Example:
671
672       .. code-block:: python
673         
674          myObID=id(gameObject)
675          ob= scene.objects.from_id(myObID)
676
677       Where ``myObID`` is an int or long from the id function.
678
679       This has the advantage that you can store the id in places you could not store a gameObject.
680
681       .. warning::
682
683          The id is derived from a memory location and will be different each time the game engine starts.
684
685 .. class:: KX_BlenderMaterial(PyObjectPlus)
686
687    KX_BlenderMaterial
688
689    .. method:: getShader()
690
691       Returns the material's shader.
692
693       :return: the material's shader
694       :rtype: :class:`BL_Shader`
695
696    .. method:: setBlending(src, dest)
697
698       Set the pixel color arithmetic functions.
699
700       :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed.
701       :type src: Value in...
702
703          * GL_ZERO,
704          * GL_ONE, 
705          * GL_SRC_COLOR, 
706          * GL_ONE_MINUS_SRC_COLOR, 
707          * GL_DST_COLOR, 
708          * GL_ONE_MINUS_DST_COLOR, 
709          * GL_SRC_ALPHA, 
710          * GL_ONE_MINUS_SRC_ALPHA, 
711          * GL_DST_ALPHA, 
712          * GL_ONE_MINUS_DST_ALPHA, 
713          * GL_SRC_ALPHA_SATURATE
714
715       :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed.
716       :type dest: Value in...
717
718          * GL_ZERO
719          * GL_ONE
720          * GL_SRC_COLOR
721          * GL_ONE_MINUS_SRC_COLOR
722          * GL_DST_COLOR
723          * GL_ONE_MINUS_DST_COLOR
724          * GL_SRC_ALPHA
725          * GL_ONE_MINUS_SRC_ALPHA
726          * GL_DST_ALPHA
727          * GL_ONE_MINUS_DST_ALPHA
728          * GL_SRC_ALPHA_SATURATE
729
730    .. method:: getMaterialIndex()
731
732       Returns the material's index.
733
734       :return: the material's index
735       :rtype: integer
736
737 .. class:: KX_CameraActuator(SCA_IActuator)
738
739    Applies changes to a camera.
740
741    .. attribute:: damping
742
743       strength of of the camera following movement.
744
745       :type: float
746    
747    .. attribute:: min
748
749       minimum distance to the target object maintained by the actuator.
750
751       :type: float
752
753    .. attribute:: max
754
755       maximum distance to stay from the target object.
756
757       :type: float
758
759    .. attribute:: height
760
761       height to stay above the target object.
762
763       :type: float
764
765    .. attribute:: useXY
766
767       axis this actuator is tracking, True=X, False=Y.
768
769       :type: boolean
770
771    .. attribute:: object
772
773       the object this actuator tracks.
774
775       :type: :class:`KX_GameObject` or None
776
777 .. class:: KX_ConstraintActuator(SCA_IActuator)
778
779    A constraint actuator limits the position, rotation, distance or orientation of an object.
780
781    .. attribute:: damp
782
783       Time constant of the constraint expressed in frame (not use by Force field constraint).
784
785       :type: integer
786
787    .. attribute:: rotDamp
788
789       Time constant for the rotation expressed in frame (only for the distance constraint), 0 = use damp for rotation as well.
790
791       :type: integer
792
793    .. attribute:: direction
794
795       The reference direction in world coordinate for the orientation constraint.
796
797       :type: 3-tuple of float: (x, y, z)
798
799    .. attribute:: option
800
801       Binary combination of :ref:`these constants <constraint-actuator-option>`
802
803       :type: integer
804
805    .. attribute:: time
806
807       activation time of the actuator. The actuator disables itself after this many frame. If set to 0, the actuator is not limited in time.
808
809       :type: integer
810
811    .. attribute:: propName
812
813       the name of the property or material for the ray detection of the distance constraint.
814
815       :type: string
816
817    .. attribute:: min
818
819       The lower bound of the constraint. For the rotation and orientation constraint, it represents radiant.
820
821       :type: float
822
823    .. attribute:: distance
824
825       the target distance of the distance constraint.
826
827       :type: float
828
829    .. attribute:: max
830
831       the upper bound of the constraint. For rotation and orientation constraints, it represents radiant.
832
833       :type: float
834
835    .. attribute:: rayLength
836
837       the length of the ray of the distance constraint.
838
839       :type: float
840
841    .. attribute:: limit
842
843       type of constraint. Use one of the :ref:`these constants <constraint-actuator-limit>`
844
845       :type: integer.
846
847       
848 .. class:: KX_ConstraintWrapper(PyObjectPlus)
849
850    KX_ConstraintWrapper
851
852    .. method:: getConstraintId(val)
853
854       Returns the contraint's ID
855
856       :return: the constraint's ID
857       :rtype: integer
858
859 .. class:: KX_GameActuator(SCA_IActuator)
860
861    The game actuator loads a new .blend file, restarts the current .blend file or quits the game.
862
863    .. attribute:: fileName
864
865       the new .blend file to load.
866
867       :type: string
868
869    .. attribute:: mode
870
871       The mode of this actuator. Can be on of :ref:`these constants <game-actuator>`
872
873       :type: Int
874
875 .. class:: KX_GameObject(SCA_IObject)
876
877    All game objects are derived from this class.
878
879    Properties assigned to game objects are accessible as attributes of this class.
880
881    .. note::
882       
883       Calling ANY method or attribute on an object that has been removed from a scene will raise a SystemError,
884       if an object may have been removed since last accessing it use the :data:`invalid` attribute to check.
885
886    KX_GameObject can be subclassed to extend functionality. For example:
887
888    .. code-block:: python
889
890         import bge
891
892         class CustomGameObject(bge.types.KX_GameObject):
893             RATE = 0.05
894
895             def __init__(self, old_owner):
896                 # "old_owner" can just be ignored. At this point, "self" is
897                 # already the object in the scene, and "old_owner" has been
898                 # destroyed.
899
900                 # New attributes can be defined - but we could also use a game
901                 # property, like "self['rate']".
902                 self.rate = CustomGameObject.RATE
903
904             def update(self):
905                 self.worldPosition.z += self.rate
906
907                 # switch direction
908                 if self.worldPosition.z > 1.0:
909                     self.rate = -CustomGameObject.RATE
910                 elif self.worldPosition.z < 0.0:
911                     self.rate = CustomGameObject.RATE
912
913         # Called first
914         def mutate(cont):
915             old_object = cont.owner
916             mutated_object = CustomGameObject(cont.owner)
917
918             # After calling the constructor above, references to the old object
919             # should not be used.
920             assert(old_object is not mutated_object)
921             assert(old_object.invalid)
922             assert(mutated_object is cont.owner)
923
924         # Called later - note we are now working with the mutated object.
925         def update(cont):
926             cont.owner.update()
927
928    When subclassing objects other than empties and meshes, the specific type
929    should be used - e.g. inherit from :class:`BL_ArmatureObject` when the object
930    to mutate is an armature.
931
932    .. attribute:: name
933
934       The object's name. (read-only).
935
936       :type: string
937
938    .. attribute:: mass
939
940       The object's mass
941
942       :type: float
943
944       .. note::
945          
946          The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0.
947       
948    .. attribute:: linVelocityMin
949
950       Enforces the object keeps moving at a minimum velocity.
951
952       :type: float
953       
954       .. note::
955       
956          Applies to dynamic and rigid body objects only.
957
958       .. note::
959          
960          A value of 0.0 disables this option.
961
962       .. note::
963       
964          While objects are stationary the minimum velocity will not be applied.
965
966    .. attribute:: linVelocityMax
967
968       Clamp the maximum linear velocity to prevent objects moving beyond a set speed.
969
970       :type: float
971       
972       .. note::
973          
974          Applies to dynamic and rigid body objects only.
975
976       .. note::
977
978          A value of 0.0 disables this option (rather then setting it stationary).
979
980    .. attribute:: localInertia
981
982       the object's inertia vector in local coordinates. Read only.
983
984       :type: list [ix, iy, iz]
985
986    .. attribute:: parent
987
988       The object's parent object. (read-only).
989
990       :type: :class:`KX_GameObject` or None
991           
992    .. attribute:: group_children
993
994       Returns the list of group members if the object is a group object, otherwise None is returned.
995
996       :type: :class:`CListValue` of :class:`KX_GameObject` or None
997
998    .. attribute:: group_parent
999
1000       Returns the group object that the object belongs to or None if the object is not part of a group.
1001
1002       :type: :class:`KX_GameObject` or None
1003
1004    .. attribute:: scene
1005
1006       The object's scene. (read-only).
1007
1008       :type: :class:`KX_Scene` or None
1009
1010    .. attribute:: visible
1011
1012       visibility flag.
1013
1014       :type: boolean
1015       
1016       .. note::
1017       
1018          Game logic will still run for invisible objects.
1019
1020    .. attribute:: color
1021
1022       The object color of the object. [r, g, b, a]
1023
1024       :type: :class:`mathutils.Vector`
1025
1026    .. attribute:: occlusion
1027
1028       occlusion capability flag.
1029
1030       :type: boolean
1031
1032    .. attribute:: position
1033
1034       The object's position. [x, y, z] On write: local position, on read: world position
1035
1036       .. deprecated:: use :data:`localPosition` and :data:`worldPosition`.
1037
1038       :type: :class:`mathutils.Vector`
1039
1040    .. attribute:: orientation
1041
1042       The object's orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector. On write: local orientation, on read: world orientation
1043
1044       .. deprecated:: use :data:`localOrientation` and :data:`worldOrientation`.
1045
1046       :type: :class:`mathutils.Matrix`
1047
1048    .. attribute:: scaling
1049
1050       The object's scaling factor. [sx, sy, sz] On write: local scaling, on read: world scaling
1051
1052       .. deprecated:: use :data:`localScale` and :data:`worldScale`.
1053
1054       :type: :class:`mathutils.Vector`
1055
1056    .. attribute:: localOrientation
1057
1058       The object's local orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.
1059
1060       :type: :class:`mathutils.Matrix`
1061
1062    .. attribute:: worldOrientation
1063
1064       The object's world orientation. 3x3 Matrix.
1065
1066       :type: :class:`mathutils.Matrix`
1067
1068    .. attribute:: localScale
1069
1070       The object's local scaling factor. [sx, sy, sz]
1071
1072       :type: :class:`mathutils.Vector`
1073
1074    .. attribute:: worldScale
1075
1076       The object's world scaling factor. [sx, sy, sz]
1077
1078       :type: :class:`mathutils.Vector`
1079
1080    .. attribute:: localPosition
1081
1082       The object's local position. [x, y, z]
1083
1084       :type: :class:`mathutils.Vector`
1085
1086    .. attribute:: worldPosition
1087
1088       The object's world position. [x, y, z]
1089
1090       :type: :class:`mathutils.Vector`
1091
1092    .. attribute:: localTransform
1093
1094       The object's local space transform matrix. 4x4 Matrix.
1095
1096       :type: :class:`mathutils.Matrix`
1097
1098    .. attribute:: worldTransform
1099
1100       The object's world space transform matrix. 4x4 Matrix.
1101
1102       :type: :class:`mathutils.Matrix`
1103           
1104    .. attribute:: localLinearVelocity
1105       
1106           The object's local linear velocity. [x, y, z]
1107           
1108           :type: :class:`mathutils.Vector`
1109           
1110    .. attribute:: worldLinearVelocity
1111    
1112       The object's world linear velocity. [x, y, z]
1113           
1114           :type: :class:`mathutils.Vector`
1115           
1116    .. attribute:: localAngularVelocity
1117    
1118       The object's local angular velocity. [x, y, z]
1119           
1120           :type: :class:`mathutils.Vector`
1121           
1122    .. attribute:: worldAngularVelocity
1123    
1124       The object's world angular velocity. [x, y, z]
1125           
1126           :type: :class:`mathutils.Vector`
1127
1128    .. attribute:: timeOffset
1129
1130       adjust the slowparent delay at runtime.
1131
1132       :type: float
1133
1134    .. attribute:: state
1135
1136       the game object's state bitmask, using the first 30 bits, one bit must always be set.
1137
1138       :type: int
1139
1140    .. attribute:: meshes
1141
1142       a list meshes for this object.
1143
1144       :type: list of :class:`KX_MeshProxy`
1145       
1146       .. note::
1147          
1148          Most objects use only 1 mesh.
1149
1150       .. note::
1151          
1152          Changes to this list will not update the KX_GameObject.
1153
1154    .. attribute:: sensors
1155
1156       a sequence of :class:`SCA_ISensor` objects with string/index lookups and iterator support.
1157
1158       :type: list
1159       
1160       .. note::
1161          
1162          This attribute is experemental and may be removed (but probably wont be).
1163
1164       .. note::
1165       
1166          Changes to this list will not update the KX_GameObject.
1167
1168    .. attribute:: controllers
1169
1170       a sequence of :class:`SCA_IController` objects with string/index lookups and iterator support.
1171
1172       :type: list of :class:`SCA_ISensor`
1173       
1174       .. note::
1175          
1176          This attribute is experemental and may be removed (but probably wont be).
1177
1178       .. note::
1179          
1180          Changes to this list will not update the KX_GameObject.
1181
1182    .. attribute:: actuators
1183
1184       a list of :class:`SCA_IActuator` with string/index lookups and iterator support.
1185
1186       :type: list
1187       
1188       .. note::
1189
1190          This attribute is experemental and may be removed (but probably wont be).
1191
1192       .. note::
1193
1194          Changes to this list will not update the KX_GameObject.
1195
1196    .. attribute:: attrDict
1197
1198       get the objects internal python attribute dictionary for direct (faster) access.
1199
1200       :type: dict
1201
1202    .. attribute:: children
1203
1204       direct children of this object, (read-only).
1205
1206       :type: :class:`CListValue` of :class:`KX_GameObject`'s
1207
1208    .. attribute:: childrenRecursive
1209
1210       all children of this object including childrens children, (read-only).
1211
1212       :type: :class:`CListValue` of :class:`KX_GameObject`'s
1213
1214    .. method:: endObject()
1215
1216       Delete this object, can be used in place of the EndObject Actuator.
1217
1218       The actual removal of the object from the scene is delayed.
1219
1220    .. method:: replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)
1221
1222       Replace the mesh of this object with a new mesh. This works the same was as the actuator.
1223
1224       :arg mesh: mesh to replace or the meshes name.
1225       :type mesh: :class:`MeshProxy` or string
1226       :arg useDisplayMesh: when enabled the display mesh will be replaced (optional argument).
1227       :type useDisplayMesh: boolean
1228       :arg usePhysicsMesh: when enabled the physics mesh will be replaced (optional argument).
1229       :type usePhysicsMesh: boolean
1230
1231    .. method:: setVisible(visible, recursive)
1232
1233       Sets the game object's visible flag.
1234
1235       :arg visible: the visible state to set.
1236       :type visible: boolean
1237       :arg recursive: optional argument to set all childrens visibility flag too.
1238       :type recursive: boolean
1239
1240    .. method:: setOcclusion(occlusion, recursive)
1241
1242       Sets the game object's occlusion capability.
1243
1244       :arg occlusion: the state to set the occlusion to.
1245       :type occlusion: boolean
1246       :arg recursive: optional argument to set all childrens occlusion flag too.
1247       :type recursive: boolean
1248
1249    .. method:: alignAxisToVect(vect, axis=2, factor=1.0)
1250
1251       Aligns any of the game object's axis along the given vector.
1252
1253
1254       :arg vect: a vector to align the axis.
1255       :type vect: 3D vector
1256       :arg axis: The axis you want to align
1257
1258          * 0: X axis
1259          * 1: Y axis
1260          * 2: Z axis
1261
1262       :type axis: integer
1263       :arg factor: Only rotate a feaction of the distance to the target vector (0.0 - 1.0)
1264       :type factor: float
1265
1266    .. method:: getAxisVect(vect)
1267
1268       Returns the axis vector rotates by the objects worldspace orientation.
1269       This is the equivalent of multiplying the vector by the orientation matrix.
1270
1271       :arg vect: a vector to align the axis.
1272       :type vect: 3D Vector
1273       :return: The vector in relation to the objects rotation.
1274       :rtype: 3d vector.
1275
1276    .. method:: applyMovement(movement, local=False)
1277
1278       Sets the game object's movement.
1279
1280       :arg movement: movement vector.
1281       :type movement: 3D Vector
1282       :arg local:
1283          * False: you get the "global" movement ie: relative to world orientation.
1284          * True: you get the "local" movement ie: relative to object orientation.
1285       :arg local: boolean
1286
1287    .. method:: applyRotation(rotation, local=False)
1288
1289       Sets the game object's rotation.
1290
1291       :arg rotation: rotation vector.
1292       :type rotation: 3D Vector
1293       :arg local:
1294          * False: you get the "global" rotation ie: relative to world orientation.
1295          * True: you get the "local" rotation ie: relative to object orientation.
1296       :arg local: boolean
1297
1298    .. method:: applyForce(force, local=False)
1299
1300       Sets the game object's force.
1301
1302       This requires a dynamic object.
1303
1304       :arg force: force vector.
1305       :type force: 3D Vector
1306       :arg local:
1307          * False: you get the "global" force ie: relative to world orientation.
1308          * True: you get the "local" force ie: relative to object orientation.
1309       :type local: boolean
1310
1311    .. method:: applyTorque(torque, local=False)
1312
1313       Sets the game object's torque.
1314
1315       This requires a dynamic object.
1316
1317       :arg torque: torque vector.
1318       :type torque: 3D Vector
1319       :arg local:
1320          * False: you get the "global" torque ie: relative to world orientation.
1321          * True: you get the "local" torque ie: relative to object orientation.
1322       :type local: boolean
1323
1324    .. method:: getLinearVelocity(local=False)
1325
1326       Gets the game object's linear velocity.
1327
1328       This method returns the game object's velocity through it's centre of mass, ie no angular velocity component.
1329
1330       :arg local:
1331          * False: you get the "global" velocity ie: relative to world orientation.
1332          * True: you get the "local" velocity ie: relative to object orientation.
1333       :type local: boolean
1334       :return: the object's linear velocity.
1335       :rtype: list [vx, vy, vz]
1336
1337    .. method:: setLinearVelocity(velocity, local=False)
1338
1339       Sets the game object's linear velocity.
1340
1341       This method sets game object's velocity through it's centre of mass, 
1342       ie no angular velocity component.
1343
1344       This requires a dynamic object.
1345
1346       :arg velocity: linear velocity vector.
1347       :type velocity: 3D Vector
1348       :arg local:
1349          * False: you get the "global" velocity ie: relative to world orientation.
1350          * True: you get the "local" velocity ie: relative to object orientation.
1351       :type local: boolean
1352
1353    .. method:: getAngularVelocity(local=False)
1354
1355       Gets the game object's angular velocity.
1356
1357       :arg local:
1358          * False: you get the "global" velocity ie: relative to world orientation.
1359          * True: you get the "local" velocity ie: relative to object orientation.
1360       :type local: boolean
1361       :return: the object's angular velocity.
1362       :rtype: list [vx, vy, vz]
1363
1364    .. method:: setAngularVelocity(velocity, local=False)
1365
1366       Sets the game object's angular velocity.
1367
1368       This requires a dynamic object.
1369
1370       :arg velocity: angular velocity vector.
1371       :type velocity: boolean
1372       :arg local:
1373          * False: you get the "global" velocity ie: relative to world orientation.
1374          * True: you get the "local" velocity ie: relative to object orientation.
1375
1376    .. method:: getVelocity(point=(0, 0, 0))
1377
1378       Gets the game object's velocity at the specified point.
1379
1380       Gets the game object's velocity at the specified point, including angular
1381       components.
1382
1383       :arg point: optional point to return the velocity for, in local coordinates.
1384       :type point: 3D Vector
1385       :return: the velocity at the specified point.
1386       :rtype: list [vx, vy, vz]
1387
1388    .. method:: getReactionForce()
1389
1390       Gets the game object's reaction force.
1391
1392       The reaction force is the force applied to this object over the last simulation timestep.
1393       This also includes impulses, eg from collisions.
1394
1395       :return: the reaction force of this object.
1396       :rtype: list [fx, fy, fz]
1397
1398       .. note::
1399
1400          This is not implimented at the moment.
1401
1402    .. method:: applyImpulse(point, impulse)
1403
1404       Applies an impulse to the game object.
1405
1406       This will apply the specified impulse to the game object at the specified point.
1407       If point != position, applyImpulse will also change the object's angular momentum.
1408       Otherwise, only linear momentum will change.
1409
1410       :arg point: the point to apply the impulse to (in world coordinates)
1411       :type point: the point to apply the impulse to (in world coordinates)
1412
1413    .. method:: suspendDynamics()
1414
1415       Suspends physics for this object.
1416
1417    .. method:: restoreDynamics()
1418
1419       Resumes physics for this object.
1420
1421       .. note::
1422          
1423          The objects linear velocity will be applied from when the dynamics were suspended.
1424
1425    .. method:: enableRigidBody()
1426
1427       Enables rigid body physics for this object.
1428
1429       Rigid body physics allows the object to roll on collisions.
1430
1431    .. method:: disableRigidBody()
1432
1433       Disables rigid body physics for this object.
1434
1435    .. method:: setParent(parent, compound=True, ghost=True)
1436
1437       Sets this object's parent.
1438       Control the shape status with the optional compound and ghost parameters:
1439
1440       In that case you can control if it should be ghost or not:
1441
1442       :arg parent: new parent object.
1443       :type parent: :class:`KX_GameObject`
1444       :arg compound: whether the shape should be added to the parent compound shape.
1445
1446          * True: the object shape should be added to the parent compound shape.
1447          * False: the object should keep its individual shape.
1448
1449       :type compound: boolean
1450       :arg ghost: whether the object should be ghost while parented.
1451
1452          * True: if the object should be made ghost while parented.
1453          * False: if the object should be solid while parented.
1454
1455       :type ghost: boolean
1456
1457       .. note::
1458       
1459          If the object type is sensor, it stays ghost regardless of ghost parameter
1460
1461    .. method:: removeParent()
1462
1463       Removes this objects parent.
1464
1465    .. method:: getPhysicsId()
1466
1467       Returns the user data object associated with this game object's physics controller.
1468
1469    .. method:: getPropertyNames()
1470
1471       Gets a list of all property names.
1472
1473       :return: All property names for this object.
1474       :rtype: list
1475
1476    .. method:: getDistanceTo(other)
1477
1478       :arg other: a point or another :class:`KX_GameObject` to measure the distance to.
1479       :type other: :class:`KX_GameObject` or list [x, y, z]
1480       :return: distance to another object or point.
1481       :rtype: float
1482
1483    .. method:: getVectTo(other)
1484
1485       Returns the vector and the distance to another object or point.
1486       The vector is normalized unless the distance is 0, in which a zero length vector is returned.
1487
1488       :arg other: a point or another :class:`KX_GameObject` to get the vector and distance to.
1489       :type other: :class:`KX_GameObject` or list [x, y, z]
1490       :return: (distance, globalVector(3), localVector(3))
1491       :rtype: 3-tuple (float, 3-tuple (x, y, z), 3-tuple (x, y, z))
1492
1493    .. method:: rayCastTo(other, dist, prop)
1494
1495       Look towards another point/object and find first object hit within dist that matches prop.
1496
1497       The ray is always casted from the center of the object, ignoring the object itself.
1498       The ray is casted towards the center of another object or an explicit [x, y, z] point.
1499       Use rayCast() if you need to retrieve the hit point
1500
1501       :arg other: [x, y, z] or object towards which the ray is casted
1502       :type other: :class:`KX_GameObject` or 3-tuple
1503       :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
1504       :type dist: float
1505       :arg prop: property name that object must have; can be omitted => detect any object
1506       :type prop: string
1507       :return: the first object hit or None if no object or object does not match prop
1508       :rtype: :class:`KX_GameObject`
1509
1510    .. method:: rayCast(objto, objfrom, dist, prop, face, xray, poly)
1511
1512       Look from a point/object to another point/object and find first object hit within dist that matches prop.
1513       if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None, None, None) if no hit.
1514       if poly is 1, returns a 4-tuple with in addition a :class:`KX_PolyProxy` as 4th element.
1515       if poly is 2, returns a 5-tuple with in addition a 2D vector with the UV mapping of the hit point as 5th element.
1516
1517       .. code-block:: python
1518
1519          # shoot along the axis gun-gunAim (gunAim should be collision-free)
1520          obj, point, normal = gun.rayCast(gunAim, None, 50)
1521          if obj:
1522             # do something
1523             pass
1524
1525       The face paremeter determines the orientation of the normal.
1526
1527       * 0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
1528       * 1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
1529
1530       The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
1531       The prop and xray parameters interact as follow.
1532
1533       * prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
1534       * prop off, xray on : idem.
1535       * prop on, xray off: return closest hit if it matches prop, no hit otherwise.
1536       * 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.
1537
1538       The :class:`KX_PolyProxy` 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray.
1539       If there is no hit or the hit object is not a static mesh, None is returned as 4th element.
1540
1541       The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
1542
1543       :arg objto: [x, y, z] or object to which the ray is casted
1544       :type objto: :class:`KX_GameObject` or 3-tuple
1545       :arg objfrom: [x, y, z] or object from which the ray is casted; None or omitted => use self object center
1546       :type objfrom: :class:`KX_GameObject` or 3-tuple or None
1547       :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
1548       :type dist: float
1549       :arg prop: property name that object must have; can be omitted or "" => detect any object
1550       :type prop: string
1551       :arg face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
1552       :type face: integer
1553       :arg xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
1554       :type xray: integer
1555       :arg poly: polygon option: 0, 1 or 2 to return a 3-, 4- or 5-tuple with information on the face hit.
1556
1557          * 0 or omitted: return value is a 3-tuple (object, hitpoint, hitnormal) or (None, None, None) if no hit
1558          * 1: return value is a 4-tuple and the 4th element is a :class:`KX_PolyProxy` or None if no hit or the object doesn't use a mesh collision shape.
1559          * 2: return value is a 5-tuple and the 5th element is a 2-tuple (u, v) with the UV mapping of the hit point or None if no hit, or the object doesn't use a mesh collision shape, or doesn't have a UV mapping.
1560
1561       :type poly: integer
1562       :return: (object, hitpoint, hitnormal) or (object, hitpoint, hitnormal, polygon) or (object, hitpoint, hitnormal, polygon, hituv).
1563
1564          * object, hitpoint and hitnormal are None if no hit.
1565          * polygon is valid only if the object is valid and is a static object, a dynamic object using mesh collision shape or a soft body object, otherwise it is None
1566          * hituv is valid only if polygon is valid and the object has a UV mapping, otherwise it is None
1567
1568       :rtype:
1569
1570          * 3-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz))
1571          * or 4-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz), :class:`PolyProxy`)
1572          * or 5-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz), :class:`PolyProxy`, 2-tuple (u, v))
1573
1574       .. note::
1575       
1576          The ray ignores the object on which the method is called. It is casted from/to object center or explicit [x, y, z] points.
1577
1578    .. method:: setCollisionMargin(margin)
1579
1580       Set the objects collision margin.
1581
1582       :arg margin: the collision margin distance in blender units.
1583       :type margin: float
1584
1585       .. note::
1586       
1587          If this object has no physics controller (a physics ID of zero), this function will raise RuntimeError.
1588
1589    .. method:: sendMessage(subject, body="", to="")
1590
1591       Sends a message.
1592
1593       :arg subject: The subject of the message
1594       :type subject: string
1595       :arg body: The body of the message (optional)
1596       :type body: string
1597       :arg to: The name of the object to send the message to (optional)
1598       :type to: string
1599
1600    .. method:: reinstancePhysicsMesh(gameObject, meshObject)
1601
1602       Updates the physics system with the changed mesh.
1603
1604       If no arguments are given the physics mesh will be re-created from the first mesh assigned to the game object.
1605
1606       :arg gameObject: optional argument, set the physics shape from this gameObjets mesh.
1607       :type gameObject: string, :class:`KX_GameObject` or None
1608       :arg meshObject: optional argument, set the physics shape from this mesh.
1609       :type meshObject: string, :class:`MeshProxy` or None
1610
1611       :return: True if reinstance succeeded, False if it failed.
1612       :rtype: boolean
1613
1614       .. note::
1615
1616          If this object has instances the other instances will be updated too.
1617       
1618       .. note::
1619
1620          The gameObject argument has an advantage that it can convert from a mesh with modifiers applied (such as subsurf).
1621       
1622       .. warning::
1623
1624          Only triangle mesh type objects are supported currently (not convex hull)
1625
1626       .. warning::
1627
1628          If the object is a part of a combound object it will fail (parent or child)
1629
1630       .. warning::
1631
1632          Rebuilding the physics mesh can be slow, running many times per second will give a performance hit.
1633
1634    .. method:: get(key, default=None)
1635
1636       Return the value matching key, or the default value if its not found.
1637       :return: The key value or a default.
1638
1639    .. method:: playAction(name, start_frame, end_frame, layer=0, priority=0, blendin=0, play_mode=ACT_MODE_PLAY, layer_weight=0.0, ipo_flags=0, speed=1.0)
1640
1641       Plays an action.
1642       
1643       :arg name: the name of the action
1644       :type name: string
1645       :arg start: the start frame of the action
1646       :type start: float
1647       :arg end: the end frame of the action
1648       :type end: float
1649       :arg layer: the layer the action will play in (actions in different layers are added/blended together)
1650       :type layer: integer
1651       :arg priority: only play this action if there isn't an action currently playing in this layer with a higher (lower number) priority
1652       :type priority: integer
1653       :arg blendin: the amount of blending between this animation and the previous one on this layer
1654       :type blendin: float
1655       :arg play_mode: the play mode
1656       :type play_mode: KX_ACTION_MODE_PLAY, KX_ACTION_MODE_LOOP, or KX_ACTION_MODE_PING_PONG
1657       :arg layer_weight: how much of the previous layer to use for blending (0 = add)
1658       :type layer_weight: float
1659       :arg ipo_flags: flags for the old IPO behaviors (force, etc)
1660       :type ipo_flags: int bitfield
1661       :arg speed: the playback speed of the action as a factor (1.0 = normal speed, 2.0 = 2x speed, etc)
1662       :type speed: float
1663
1664    .. method:: stopAction(layer=0)
1665       
1666       Stop playing the action on the given layer.
1667       
1668       :arg layer: The layer to stop playing.
1669       :type layer: integer
1670       
1671    .. method:: getActionFrame(layer=0)
1672    
1673       Gets the current frame of the action playing in the supplied layer.
1674       
1675       :arg layer: The layer that you want to get the frame from.
1676       :type layer: integer
1677       
1678       :return: The current frame of the action
1679       :rtype: float
1680       
1681    .. method:: setActionFrame(frame, layer=0)
1682    
1683       Set the current frame of the action playing in the supplied layer.
1684       
1685       :arg layer: The layer where you want to set the frame
1686       :type layer: integer
1687       :arg frame: The frame to set the action to
1688       :type frame: float
1689
1690    .. method:: isPlayingAction(layer=0)
1691    
1692        Checks to see if there is an action playing in the given layer.
1693        
1694        :arg layer: The layer to check for a playing action.
1695        :type layer: integer
1696        
1697        :return: Whether or not the action is playing
1698        :rtype: boolean
1699
1700 .. class:: KX_IpoActuator(SCA_IActuator)
1701
1702    IPO actuator activates an animation.
1703
1704    .. attribute:: frameStart
1705
1706       Start frame.
1707
1708       :type: float
1709
1710    .. attribute:: frameEnd
1711
1712       End frame.
1713
1714       :type: float
1715
1716    .. attribute:: propName
1717
1718       Use this property to define the Ipo position.
1719
1720       :type: string
1721
1722    .. attribute:: framePropName
1723
1724       Assign this property this action current frame number.
1725
1726       :type: string
1727
1728    .. attribute:: mode
1729
1730       Play mode for the ipo. Can be on of :ref:`these constants <ipo-actuator>`
1731
1732       :type: integer
1733
1734    .. attribute:: useIpoAsForce
1735
1736       Apply Ipo as a global or local force depending on the local option (dynamic objects only).
1737
1738       :type: boolean
1739
1740    .. attribute:: useIpoAdd
1741
1742       Ipo is added to the current loc/rot/scale in global or local coordinate according to Local flag.
1743
1744       :type: boolean
1745
1746    .. attribute:: useIpoLocal
1747
1748       Let the ipo acts in local coordinates, used in Force and Add mode.
1749
1750       :type: boolean
1751
1752    .. attribute:: useChildren
1753
1754       Update IPO on all children Objects as well.
1755
1756       :type: boolean
1757
1758 .. class:: KX_LightObject(KX_GameObject)
1759
1760    A Light object.
1761
1762    .. code-block:: python
1763
1764       # Turn on a red alert light.
1765       import bge
1766
1767       co = bge.logic.getCurrentController()
1768       light = co.owner
1769
1770       light.energy = 1.0
1771       light.color = [1.0, 0.0, 0.0]
1772
1773    .. data:: SPOT
1774
1775       A spot light source. See attribute :data:`type`
1776
1777    .. data:: SUN
1778
1779       A point light source with no attenuation. See attribute :data:`type`
1780
1781    .. data:: NORMAL
1782
1783       A point light source. See attribute :data:`type`
1784
1785    .. attribute:: type
1786
1787       The type of light - must be SPOT, SUN or NORMAL
1788
1789    .. attribute:: layer
1790
1791       The layer mask that this light affects object on.
1792
1793       :type: bitfield
1794
1795    .. attribute:: energy
1796
1797       The brightness of this light.
1798
1799       :type: float
1800
1801    .. attribute:: distance
1802
1803       The maximum distance this light can illuminate. (SPOT and NORMAL lights only).
1804
1805       :type: float
1806
1807    .. attribute:: color
1808
1809       The color of this light. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0].
1810
1811       :type: list [r, g, b]
1812
1813    .. attribute:: colour
1814
1815       Synonym for color.
1816
1817    .. attribute:: lin_attenuation
1818
1819       The linear component of this light's attenuation. (SPOT and NORMAL lights only).
1820
1821       :type: float
1822
1823    .. attribute:: quad_attenuation
1824
1825       The quadratic component of this light's attenuation (SPOT and NORMAL lights only).
1826
1827       :type: float
1828
1829    .. attribute:: spotsize
1830
1831       The cone angle of the spot light, in degrees (SPOT lights only).
1832
1833       :type: float in [0 - 180].
1834
1835    .. attribute:: spotblend
1836
1837       Specifies the intensity distribution of the spot light (SPOT lights only).
1838
1839       :type: float in [0 - 1]
1840
1841       .. note::
1842          
1843          Higher values result in a more focused light source.
1844
1845 .. class:: KX_MeshProxy(SCA_IObject)
1846
1847    A mesh object.
1848
1849    You can only change the vertex properties of a mesh object, not the mesh topology.
1850
1851    To use mesh objects effectively, you should know a bit about how the game engine handles them.
1852
1853    #. Mesh Objects are converted from Blender at scene load.
1854    #. The Converter groups polygons by Material.  This means they can be sent to the renderer efficiently.  A material holds:
1855
1856       #. The texture.
1857       #. The Blender material.
1858       #. The Tile properties
1859       #. The face properties - (From the "Texture Face" panel)
1860       #. Transparency & z sorting
1861       #. Light layer
1862       #. Polygon shape (triangle/quad)
1863       #. Game Object
1864
1865    #. Vertices will be split by face if necessary.  Vertices can only be shared between faces if:
1866
1867       #. They are at the same position
1868       #. UV coordinates are the same
1869       #. Their normals are the same (both polygons are "Set Smooth")
1870       #. They are the same color, for example: a cube has 24 vertices: 6 faces with 4 vertices per face.
1871
1872    The correct method of iterating over every :class:`KX_VertexProxy` in a game object
1873    
1874    .. code-block:: python
1875
1876       from bge import logic
1877
1878       cont = logic.getCurrentController()
1879       object = cont.owner
1880
1881       for mesh in object.meshes:
1882          for m_index in range(len(mesh.materials)):
1883             for v_index in range(mesh.getVertexArrayLength(m_index)):
1884                vertex = mesh.getVertex(m_index, v_index)
1885                # Do something with vertex here...
1886                # ... eg: color the vertex red.
1887                vertex.color = [1.0, 0.0, 0.0, 1.0]
1888
1889    .. attribute:: materials
1890
1891       :type: list of :class:`KX_BlenderMaterial` or :class:`KX_PolygonMaterial` types
1892
1893    .. attribute:: numPolygons
1894
1895       :type: integer
1896
1897    .. attribute:: numMaterials
1898
1899       :type: integer
1900
1901    .. method:: getNumMaterials()
1902
1903       :return: number of materials associated with this object
1904       :rtype: integer
1905
1906    .. method:: getMaterialName(matid)
1907
1908       Gets the name of the specified material.
1909
1910       :arg matid: the specified material.
1911       :type matid: integer
1912       :return: the attached material name.
1913       :rtype: string
1914
1915    .. method:: getTextureName(matid)
1916
1917       Gets the name of the specified material's texture.
1918
1919       :arg matid: the specified material
1920       :type matid: integer
1921       :return: the attached material's texture name.
1922       :rtype: string
1923
1924    .. method:: getVertexArrayLength(matid)
1925
1926       Gets the length of the vertex array associated with the specified material.
1927
1928       There is one vertex array for each material.
1929
1930       :arg matid: the specified material
1931       :type matid: integer
1932       :return: the number of verticies in the vertex array.
1933       :rtype: integer
1934
1935    .. method:: getVertex(matid, index)
1936
1937       Gets the specified vertex from the mesh object.
1938
1939       :arg matid: the specified material
1940       :type matid: integer
1941       :arg index: the index into the vertex array.
1942       :type index: integer
1943       :return: a vertex object.
1944       :rtype: :class:`KX_VertexProxy`
1945
1946    .. method:: getNumPolygons()
1947
1948       :return: The number of polygon in the mesh.
1949       :rtype: integer
1950
1951    .. method:: getPolygon(index)
1952
1953       Gets the specified polygon from the mesh.
1954
1955       :arg index: polygon number
1956       :type index: integer
1957       :return: a polygon object.
1958       :rtype: :class:`PolyProxy`
1959
1960    .. method:: transform(matid, matrix)
1961
1962       Transforms the vertices of a mesh.
1963
1964       :arg matid: material index, -1 transforms all.
1965       :type matid: integer
1966       :arg matrix: transformation matrix.
1967       :type matrix: 4x4 matrix [[float]]
1968
1969    .. method:: transform_uv(matid, matrix, uv_index=-1)
1970
1971       Transforms the vertices UV's of a mesh.
1972
1973       :arg matid: material index, -1 transforms all.
1974       :type matid: integer
1975       :arg matrix: transformation matrix.
1976       :type matrix: 4x4 matrix [[float]]
1977       :arg matid: optional uv index, -1 for all, otherwise 0 or 1.
1978       :type matid: integer
1979
1980 .. class:: SCA_MouseSensor(SCA_ISensor)
1981
1982    Mouse Sensor logic brick.
1983
1984    .. attribute:: position
1985
1986       current [x, y] coordinates of the mouse, in frame coordinates (pixels).
1987
1988       :type: [integer, interger]
1989
1990    .. attribute:: mode
1991
1992       sensor mode.
1993
1994       :type: integer
1995
1996          * KX_MOUSESENSORMODE_LEFTBUTTON(1)
1997          * KX_MOUSESENSORMODE_MIDDLEBUTTON(2)
1998          * KX_MOUSESENSORMODE_RIGHTBUTTON(3)
1999          * KX_MOUSESENSORMODE_WHEELUP(4)
2000          * KX_MOUSESENSORMODE_WHEELDOWN(5)
2001          * KX_MOUSESENSORMODE_MOVEMENT(6)
2002
2003    .. method:: getButtonStatus(button)
2004
2005       Get the mouse button status.
2006  
2007       :arg button: The code that represents the key you want to get the state of, use one of :ref:`these constants<mouse-keys>`
2008       :type button: int
2009       :return: The state of the given key, can be one of :ref:`these constants<input-status>`
2010       :rtype: int
2011
2012 .. class:: KX_MouseFocusSensor(SCA_MouseSensor)
2013
2014    The mouse focus sensor detects when the mouse is over the current game object.
2015
2016    The mouse focus sensor works by transforming the mouse coordinates from 2d device
2017    space to 3d space then raycasting away from the camera.
2018
2019    .. attribute:: raySource
2020
2021       The worldspace source of the ray (the view position).
2022
2023       :type: list (vector of 3 floats)
2024
2025    .. attribute:: rayTarget
2026
2027       The worldspace target of the ray.
2028
2029       :type: list (vector of 3 floats)
2030
2031    .. attribute:: rayDirection
2032
2033       The :data:`rayTarget` - :class:`raySource` normalized.
2034
2035       :type: list (normalized vector of 3 floats)
2036
2037    .. attribute:: hitObject
2038
2039       the last object the mouse was over.
2040
2041       :type: :class:`KX_GameObject` or None
2042
2043    .. attribute:: hitPosition
2044
2045       The worldspace position of the ray intersecton.
2046
2047       :type: list (vector of 3 floats)
2048
2049    .. attribute:: hitNormal
2050
2051       the worldspace normal from the face at point of intersection.
2052
2053       :type: list (normalized vector of 3 floats)
2054
2055    .. attribute:: hitUV
2056
2057       the UV coordinates at the point of intersection.
2058
2059       :type: list (vector of 2 floats)
2060
2061       If the object has no UV mapping, it returns [0, 0].
2062
2063       The UV coordinates are not normalized, they can be < 0 or > 1 depending on the UV mapping.
2064
2065    .. attribute:: usePulseFocus
2066
2067       When enabled, moving the mouse over a different object generates a pulse. (only used when the 'Mouse Over Any' sensor option is set).
2068
2069       :type: boolean
2070
2071 .. class:: KX_TouchSensor(SCA_ISensor)
2072
2073    Touch sensor detects collisions between objects.
2074
2075    .. attribute:: propName
2076
2077       The property or material to collide with.
2078
2079       :type: string
2080
2081    .. attribute:: useMaterial
2082
2083       Determines if the sensor is looking for a property or material. KX_True = Find material; KX_False = Find property.
2084
2085       :type: boolean
2086
2087    .. attribute:: usePulseCollision
2088
2089       When enabled, changes to the set of colliding objects generate a pulse.
2090
2091       :type: boolean
2092
2093    .. attribute:: hitObject
2094
2095       The last collided object. (read-only).
2096
2097       :type: :class:`KX_GameObject` or None
2098
2099    .. attribute:: hitObjectList
2100
2101       A list of colliding objects. (read-only).
2102
2103       :type: :class:`CListValue` of :class:`KX_GameObject`
2104
2105 .. class:: KX_NearSensor(KX_TouchSensor)
2106
2107    A near sensor is a specialised form of touch sensor.
2108
2109    .. attribute:: distance
2110
2111       The near sensor activates when an object is within this distance.
2112
2113       :type: float
2114
2115    .. attribute:: resetDistance
2116
2117       The near sensor deactivates when the object exceeds this distance.
2118
2119       :type: float
2120
2121 .. class:: KX_NetworkMessageActuator(SCA_IActuator)
2122
2123    Message Actuator
2124
2125    .. attribute:: propName
2126
2127       Messages will only be sent to objects with the given property name.
2128
2129       :type: string
2130
2131    .. attribute:: subject
2132
2133       The subject field of the message.
2134
2135       :type: string
2136
2137    .. attribute:: body
2138
2139       The body of the message.
2140
2141       :type: string
2142
2143    .. attribute:: usePropBody
2144
2145       Send a property instead of a regular body message.
2146
2147       :type: boolean
2148
2149 .. class:: KX_NetworkMessageSensor(SCA_ISensor)
2150
2151    The Message Sensor logic brick.
2152
2153    Currently only loopback (local) networks are supported.
2154
2155    .. attribute:: subject
2156
2157       The subject the sensor is looking for.
2158
2159       :type: string
2160
2161    .. attribute:: frameMessageCount
2162
2163       The number of messages received since the last frame. (read-only).
2164
2165       :type: integer
2166
2167    .. attribute:: subjects
2168
2169       The list of message subjects received. (read-only).
2170
2171       :type: list of strings
2172
2173    .. attribute:: bodies
2174
2175       The list of message bodies received. (read-only).
2176
2177       :type: list of strings
2178
2179 .. class:: KX_ObjectActuator(SCA_IActuator)
2180
2181    The object actuator ("Motion Actuator") applies force, torque, displacement, angular displacement, 
2182    velocity, or angular velocity to an object.
2183    Servo control allows to regulate force to achieve a certain speed target.
2184
2185    .. attribute:: force
2186
2187       The force applied by the actuator.
2188
2189       :type: list [x, y, z]
2190
2191    .. attribute:: useLocalForce
2192
2193       A flag specifying if the force is local.
2194
2195       :type: boolean
2196
2197    .. attribute:: torque
2198
2199       The torque applied by the actuator.
2200
2201       :type: list [x, y, z]
2202
2203    .. attribute:: useLocalTorque
2204
2205       A flag specifying if the torque is local.
2206
2207       :type: boolean
2208
2209    .. attribute:: dLoc
2210
2211       The displacement vector applied by the actuator.
2212
2213       :type: list [x, y, z]
2214
2215    .. attribute:: useLocalDLoc
2216
2217       A flag specifying if the dLoc is local.
2218
2219       :type: boolean
2220
2221    .. attribute:: dRot
2222
2223       The angular displacement vector applied by the actuator
2224
2225       :type: list [x, y, z]
2226       
2227       .. note::
2228       
2229          Since the displacement is applied every frame, you must adjust the displacement based on the frame rate, or you game experience will depend on the player's computer speed.
2230
2231    .. attribute:: useLocalDRot
2232
2233       A flag specifying if the dRot is local.
2234
2235       :type: boolean
2236
2237    .. attribute:: linV
2238
2239       The linear velocity applied by the actuator.
2240
2241       :type: list [x, y, z]
2242
2243    .. attribute:: useLocalLinV
2244
2245       A flag specifying if the linear velocity is local.
2246
2247       :type: boolean
2248       
2249       .. note::
2250       
2251          This is the target speed for servo controllers.
2252
2253    .. attribute:: angV
2254
2255       The angular velocity applied by the actuator.
2256
2257       :type: list [x, y, z]
2258
2259    .. attribute:: useLocalAngV
2260
2261       A flag specifying if the angular velocity is local.
2262
2263       :type: boolean
2264
2265    .. attribute:: damping
2266
2267       The damping parameter of the servo controller.
2268
2269       :type: short
2270
2271    .. attribute:: forceLimitX
2272
2273       The min/max force limit along the X axis and activates or deactivates the limits in the servo controller.
2274
2275       :type: list [min(float), max(float), bool]
2276
2277    .. attribute:: forceLimitY
2278
2279       The min/max force limit along the Y axis and activates or deactivates the limits in the servo controller.
2280
2281       :type: list [min(float), max(float), bool]
2282
2283    .. attribute:: forceLimitZ
2284
2285       The min/max force limit along the Z axis and activates or deactivates the limits in the servo controller.
2286
2287       :type: list [min(float), max(float), bool]
2288
2289    .. attribute:: pid
2290
2291       The PID coefficients of the servo controller.
2292
2293       :type: list of floats [proportional, integral, derivate]
2294
2295    .. attribute:: reference
2296
2297       The object that is used as reference to compute the velocity for the servo controller.
2298
2299       :type: :class:`KX_GameObject` or None
2300
2301 .. class:: KX_ParentActuator(SCA_IActuator)
2302
2303    The parent actuator can set or remove an objects parent object.
2304
2305    .. attribute:: object
2306
2307       the object this actuator sets the parent too.
2308
2309       :type: :class:`KX_GameObject` or None
2310
2311    .. attribute:: mode
2312
2313       The mode of this actuator.
2314
2315       :type: integer from 0 to 1.
2316
2317    .. attribute:: compound
2318
2319       Whether the object shape should be added to the parent compound shape when parenting.
2320
2321       Effective only if the parent is already a compound shape.
2322
2323       :type: boolean
2324
2325    .. attribute:: ghost
2326
2327       Whether the object should be made ghost when parenting
2328       Effective only if the shape is not added to the parent compound shape.
2329
2330       :type: boolean
2331
2332 .. class:: KX_PhysicsObjectWrapper(PyObjectPlus)
2333
2334    KX_PhysicsObjectWrapper
2335
2336    .. method:: setActive(active)
2337
2338       Set the object to be active.
2339
2340       :arg active: set to True to be active
2341       :type active: boolean
2342
2343    .. method:: setAngularVelocity(x, y, z, local)
2344
2345       Set the angular velocity of the object.
2346
2347       :arg x: angular velocity for the x-axis
2348       :type x: float
2349
2350       :arg y: angular velocity for the y-axis
2351       :type y: float
2352
2353       :arg z: angular velocity for the z-axis
2354       :type z: float
2355
2356       :arg local: set to True for local axis
2357       :type local: boolean
2358
2359    .. method:: setLinearVelocity(x, y, z, local)
2360
2361       Set the linear velocity of the object.
2362
2363       :arg x: linear velocity for the x-axis
2364       :type x: float
2365
2366       :arg y: linear velocity for the y-axis
2367       :type y: float
2368
2369       :arg z: linear velocity for the z-axis
2370       :type z: float
2371
2372       :arg local: set to True for local axis
2373       :type local: boolean
2374
2375 .. class:: KX_PolyProxy(SCA_IObject)
2376
2377    A polygon holds the index of the vertex forming the poylgon.
2378
2379    Note:
2380    The polygon attributes are read-only, you need to retrieve the vertex proxy if you want
2381    to change the vertex settings.
2382
2383    .. attribute:: matname
2384
2385       The name of polygon material, empty if no material.
2386
2387       :type: string
2388
2389    .. attribute:: material
2390
2391       The material of the polygon.
2392
2393       :type: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial`
2394
2395    .. attribute:: texture
2396
2397       The texture name of the polygon.
2398
2399       :type: string
2400
2401    .. attribute:: matid
2402
2403       The material index of the polygon, use this to retrieve vertex proxy from mesh proxy.
2404
2405       :type: integer
2406
2407    .. attribute:: v1
2408
2409       vertex index of the first vertex of the polygon, use this to retrieve vertex proxy from mesh proxy.
2410
2411       :type: integer
2412
2413    .. attribute:: v2
2414
2415       vertex index of the second vertex of the polygon, use this to retrieve vertex proxy from mesh proxy.
2416
2417       :type: integer
2418
2419    .. attribute:: v3
2420
2421       vertex index of the third vertex of the polygon, use this to retrieve vertex proxy from mesh proxy.
2422
2423       :type: integer
2424
2425    .. attribute:: v4
2426
2427       Vertex index of the fourth vertex of the polygon, 0 if polygon has only 3 vertex
2428       Use this to retrieve vertex proxy from mesh proxy.
2429
2430       :type: integer
2431
2432    .. attribute:: visible
2433
2434       visible state of the polygon: 1=visible, 0=invisible.
2435
2436       :type: integer
2437
2438    .. attribute:: collide
2439
2440       collide state of the polygon: 1=receives collision, 0=collision free.
2441
2442       :type: integer
2443
2444    .. method:: getMaterialName()
2445
2446       Returns the polygon material name with MA prefix
2447
2448       :return: material name
2449       :rtype: string
2450
2451    .. method:: getMaterial()
2452
2453       :return: The polygon material
2454       :rtype: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial`
2455
2456    .. method:: getTextureName()
2457
2458       :return: The texture name
2459       :rtype: string
2460
2461    .. method:: getMaterialIndex()
2462
2463       Returns the material bucket index of the polygon.
2464       This index and the ones returned by getVertexIndex() are needed to retrieve the vertex proxy from :class:`MeshProxy`.
2465
2466       :return: the material index in the mesh
2467       :rtype: integer
2468
2469    .. method:: getNumVertex()
2470
2471       Returns the number of vertex of the polygon.
2472
2473       :return: number of vertex, 3 or 4.
2474       :rtype: integer
2475
2476    .. method:: isVisible()
2477
2478       Returns whether the polygon is visible or not
2479
2480       :return: 0=invisible, 1=visible
2481       :rtype: boolean
2482
2483    .. method:: isCollider()
2484
2485       Returns whether the polygon is receives collision or not
2486
2487       :return: 0=collision free, 1=receives collision
2488       :rtype: integer
2489
2490    .. method:: getVertexIndex(vertex)
2491
2492       Returns the mesh vertex index of a polygon vertex
2493       This index and the one returned by getMaterialIndex() are needed to retrieve the vertex proxy from :class:`MeshProxy`.
2494
2495       :arg vertex: index of the vertex in the polygon: 0->3
2496       :arg vertex: integer
2497       :return: mesh vertex index
2498       :rtype: integer
2499
2500    .. method:: getMesh()
2501
2502       Returns a mesh proxy
2503
2504       :return: mesh proxy
2505       :rtype: :class:`MeshProxy`
2506
2507 .. class:: KX_PolygonMaterial(PyObjectPlus)
2508
2509    This is the interface to materials in the game engine.
2510
2511    Materials define the render state to be applied to mesh objects.
2512
2513    .. warning::
2514
2515       Some of the methods/variables are CObjects.  If you mix these up, you will crash blender.
2516
2517    .. code-block:: python
2518
2519       from bge import logic
2520       
2521       vertex_shader = """
2522       
2523       void main(void)
2524       {
2525          // original vertex position, no changes
2526          gl_Position = ftransform();
2527          // coordinate of the 1st texture channel
2528          gl_TexCoord[0] = gl_MultiTexCoord0;
2529          // coordinate of the 2nd texture channel
2530          gl_TexCoord[1] = gl_MultiTexCoord1;
2531       }
2532       """
2533       
2534       fragment_shader ="""
2535
2536       uniform sampler2D color_0;
2537       uniform sampler2D color_1;
2538       uniform float factor;
2539
2540       void main(void)
2541       {
2542          vec4 color_0 = texture2D(color_0, gl_TexCoord[0].st);
2543          vec4 color_1 = texture2D(color_1, gl_TexCoord[1].st);
2544          gl_FragColor = mix(color_0, color_1, factor);
2545       }
2546       """
2547
2548       object = logic.getCurrentController().owner
2549       object = cont.owner
2550       for mesh in object.meshes:
2551           for material in mesh.materials:
2552               shader = material.getShader()
2553               if shader != None:
2554                   if not shader.isValid():
2555                       shader.setSource(vertex_shader, fragment_shader, True)
2556
2557                   # get the first texture channel of the material
2558                   shader.setSampler('color_0', 0)
2559                   # get the second texture channel of the material
2560                   shader.setSampler('color_1', 1)
2561                   # pass another uniform to the shader
2562                   shader.setUniform1f('factor', 0.3)
2563
2564
2565    .. attribute:: texture
2566
2567       Texture name.
2568
2569       :type: string (read-only)
2570
2571    .. attribute:: gl_texture
2572
2573       OpenGL texture handle (eg for glBindTexture(GL_TEXTURE_2D, gl_texture).
2574
2575       :type: integer (read-only)
2576
2577    .. attribute:: material
2578
2579       Material name.
2580
2581       :type: string (read-only)
2582
2583    .. attribute:: tface
2584
2585       Texture face properties.
2586
2587       :type: CObject (read-only)
2588
2589    .. attribute:: tile
2590
2591       Texture is tiling.
2592
2593       :type: boolean
2594
2595    .. attribute:: tilexrep
2596
2597       Number of tile repetitions in x direction.
2598
2599       :type: integer
2600
2601    .. attribute:: tileyrep
2602
2603       Number of tile repetitions in y direction.
2604
2605       :type: integer
2606
2607    .. attribute:: drawingmode
2608
2609       Drawing mode for the material.
2610       - 2  (drawingmode & 4)     Textured
2611       - 4  (drawingmode & 16)    Light
2612       - 14 (drawingmode & 16384) 3d Polygon Text.
2613
2614       :type: bitfield
2615
2616    .. attribute:: transparent
2617
2618       This material is transparent. All meshes with this
2619       material will be rendered after non transparent meshes from back
2620       to front.
2621
2622       :type: boolean
2623
2624    .. attribute:: zsort
2625
2626       Transparent polygons in meshes with this material will be sorted back to
2627       front before rendering.
2628       Non-Transparent polygons will be sorted front to back before rendering.
2629
2630       :type: boolean
2631
2632    .. attribute:: lightlayer
2633
2634       Light layers this material affects.
2635
2636       :type: bitfield.
2637
2638    .. attribute:: triangle
2639
2640       Mesh data with this material is triangles. It's probably not safe to change this.
2641
2642       :type: boolean
2643
2644    .. attribute:: diffuse
2645
2646       The diffuse color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0].
2647
2648       :type: list [r, g, b]
2649
2650    .. attribute:: specular
2651
2652       The specular color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0].
2653
2654       :type: list [r, g, b]
2655
2656    .. attribute:: shininess
2657
2658       The shininess (specular exponent) of the material. 0.0 <= shininess <= 128.0.
2659
2660       :type: float
2661
2662    .. attribute:: specularity
2663
2664       The amount of specular of the material. 0.0 <= specularity <= 1.0.
2665
2666       :type: float
2667
2668    .. method:: updateTexture(tface, rasty)
2669
2670       Updates a realtime animation.
2671
2672       :arg tface: Texture face (eg mat.tface)
2673       :type tface: CObject
2674       :arg rasty: Rasterizer
2675       :type rasty: CObject
2676
2677    .. method:: setTexture(tface)
2678
2679       Sets texture render state.
2680
2681       :arg tface: Texture face
2682       :type tface: CObject
2683
2684       .. code-block:: python
2685
2686          mat.setTexture(mat.tface)
2687          
2688    .. method:: activate(rasty, cachingInfo)
2689
2690       Sets material parameters for this object for rendering.
2691
2692       Material Parameters set:
2693
2694       #. Texture
2695       #. Backface culling
2696       #. Line drawing
2697       #. Specular Colour
2698       #. Shininess
2699       #. Diffuse Colour
2700       #. Polygon Offset.
2701
2702       :arg rasty: Rasterizer instance.
2703       :type rasty: CObject
2704       :arg cachingInfo: Material cache instance.
2705       :type cachingInfo: CObject
2706
2707    .. method:: setCustomMaterial(material)
2708
2709       Sets the material state setup object.
2710
2711       Using this method, you can extend or completely replace the gameengine material
2712       to do your own advanced multipass effects.
2713
2714       Use this method to register your material class.  Instead of the normal material, 
2715       your class's activate method will be called just before rendering the mesh.
2716       This should setup the texture, material, and any other state you would like.
2717       It should return True to render the mesh, or False if you are finished.  You should
2718       clean up any state Blender does not set before returning False.
2719
2720       Activate Method Definition:
2721
2722       .. code-block:: python
2723       
2724          def activate(self, rasty, cachingInfo, material):
2725
2726       :arg material: The material object.
2727       :type material: instance
2728
2729       .. code-block:: python
2730
2731          class PyMaterial:
2732            def __init__(self):
2733              self.pass_no = -1
2734            
2735            def activate(self, rasty, cachingInfo, material):
2736              # Activate the material here.
2737              #
2738              # The activate method will be called until it returns False.
2739              # Every time the activate method returns True the mesh will
2740              # be rendered.
2741              #
2742              # rasty is a CObject for passing to material.updateTexture() 
2743              #       and material.activate()
2744              # cachingInfo is a CObject for passing to material.activate()
2745              # material is the KX_PolygonMaterial instance this material
2746              #          was added to
2747              
2748              # default material properties:
2749              self.pass_no += 1
2750              if self.pass_no == 0:
2751                material.activate(rasty, cachingInfo)
2752                # Return True to do this pass
2753                return True
2754              
2755              # clean up and return False to finish.
2756              self.pass_no = -1
2757              return False
2758          
2759          # Create a new Python Material and pass it to the renderer.
2760          mat.setCustomMaterial(PyMaterial())
2761          
2762 .. class:: KX_RadarSensor(KX_NearSensor)
2763
2764    Radar sensor is a near sensor with a conical sensor object.
2765
2766    .. attribute:: coneOrigin
2767
2768       The origin of the cone with which to test. The origin is in the middle of the cone. (read-only).
2769
2770       :type: list of floats [x, y, z]
2771
2772    .. attribute:: coneTarget
2773
2774       The center of the bottom face of the cone with which to test. (read-only).
2775
2776       :type: list of floats [x, y, z]
2777
2778    .. attribute:: distance
2779
2780       The height of the cone with which to test.
2781
2782       :type: float
2783
2784    .. attribute:: angle
2785
2786       The angle of the cone (in degrees) with which to test.
2787
2788       :type: float
2789
2790    .. attribute:: axis
2791
2792       The axis on which the radar cone is cast.
2793
2794       :type: integer from 0 to 5
2795
2796       KX_RADAR_AXIS_POS_X, KX_RADAR_AXIS_POS_Y, KX_RADAR_AXIS_POS_Z, 
2797       KX_RADAR_AXIS_NEG_X, KX_RADAR_AXIS_NEG_Y, KX_RADAR_AXIS_NEG_Z
2798
2799 .. class:: KX_RaySensor(SCA_ISensor)
2800
2801    A ray sensor detects the first object in a given direction.
2802
2803    .. attribute:: propName
2804
2805       The property the ray is looking for.
2806
2807       :type: string
2808
2809    .. attribute:: range
2810
2811       The distance of the ray.
2812
2813       :type: float
2814
2815    .. attribute:: useMaterial
2816
2817       Whether or not to look for a material (false = property).
2818
2819       :type: boolean
2820
2821    .. attribute:: useXRay
2822
2823       Whether or not to use XRay.
2824
2825       :type: boolean
2826
2827    .. attribute:: hitObject
2828
2829       The game object that was hit by the ray. (read-only).
2830
2831       :type: :class:`KX_GameObject`
2832
2833    .. attribute:: hitPosition
2834
2835       The position (in worldcoordinates) where the object was hit by the ray. (read-only).
2836
2837       :type: list [x, y, z]
2838
2839    .. attribute:: hitNormal
2840
2841       The normal (in worldcoordinates) of the object at the location where the object was hit by the ray. (read-only).
2842
2843       :type: list [x, y, z]
2844
2845    .. attribute:: rayDirection
2846
2847       The direction from the ray (in worldcoordinates). (read-only).
2848
2849       :type: list [x, y, z]
2850
2851    .. attribute:: axis
2852
2853       The axis the ray is pointing on.
2854
2855       :type: integer from 0 to 5
2856
2857       * KX_RAY_AXIS_POS_X
2858       * KX_RAY_AXIS_POS_Y
2859       * KX_RAY_AXIS_POS_Z
2860       * KX_RAY_AXIS_NEG_X
2861       * KX_RAY_AXIS_NEG_Y
2862       * KX_RAY_AXIS_NEG_Z
2863
2864 .. class:: KX_SCA_AddObjectActuator(SCA_IActuator)
2865
2866    Edit Object Actuator (in Add Object Mode)
2867
2868    .. warning::
2869
2870       An Add Object actuator will be ignored if at game start, the linked object doesn't exist (or is empty) or the linked object is in an active layer.
2871
2872       .. code-block:: none
2873
2874          Error: GameObject 'Name' has a AddObjectActuator 'ActuatorName' without object (in 'nonactive' layer) 
2875       
2876    .. attribute:: object
2877
2878       the object this actuator adds.
2879
2880       :type: :class:`KX_GameObject` or None
2881
2882    .. attribute:: objectLastCreated
2883
2884       the last added object from this actuator (read-only).
2885
2886       :type: :class:`KX_GameObject` or None
2887
2888    .. attribute:: time
2889
2890       the lifetime of added objects, in frames. Set to 0 to disable automatic deletion.
2891
2892       :type: integer
2893
2894    .. attribute:: linearVelocity
2895
2896       the initial linear velocity of added objects.
2897
2898       :type: list [vx, vy, vz]
2899
2900    .. attribute:: angularVelocity
2901
2902       the initial angular velocity of added objects.
2903
2904       :type: list [vx, vy, vz]
2905
2906    .. method:: instantAddObject()
2907
2908       adds the object without needing to calling SCA_PythonController.activate()
2909           
2910           .. note:: Use objectLastCreated to get the newly created object.
2911
2912 .. class:: KX_SCA_DynamicActuator(SCA_IActuator)
2913
2914    Dynamic Actuator.
2915
2916    .. attribute:: mode
2917
2918       :type: integer
2919
2920       the type of operation of the actuator, 0-4
2921
2922       * KX_DYN_RESTORE_DYNAMICS(0)
2923       * KX_DYN_DISABLE_DYNAMICS(1)
2924       * KX_DYN_ENABLE_RIGID_BODY(2)
2925       * KX_DYN_DISABLE_RIGID_BODY(3)
2926       * KX_DYN_SET_MASS(4)
2927
2928    .. attribute:: mass
2929
2930       the mass value for the KX_DYN_SET_MASS operation.
2931
2932       :type: float
2933
2934 .. class:: KX_SCA_EndObjectActuator(SCA_IActuator)
2935
2936    Edit Object Actuator (in End Object mode)
2937
2938    This actuator has no python methods.
2939
2940 .. class:: KX_SCA_ReplaceMeshActuator(SCA_IActuator)
2941
2942    Edit Object actuator, in Replace Mesh mode.
2943
2944    .. warning::
2945
2946       Replace mesh actuators will be ignored if at game start, the named mesh doesn't exist.
2947
2948       This will generate a warning in the console
2949
2950       .. code-block:: none
2951       
2952          Error: GameObject 'Name' ReplaceMeshActuator 'ActuatorName' without object
2953
2954    .. code-block:: python
2955
2956       # Level-of-detail
2957       # Switch a game object's mesh based on its depth in the camera view.
2958       # +----------+     +-----------+     +-------------------------------------+
2959       # | Always   +-----+ Python    +-----+ Edit Object (Replace Mesh) LOD.Mesh |
2960       # +----------+     +-----------+     +-------------------------------------+
2961       from bge import logic
2962
2963       # List detail meshes here
2964       # Mesh (name, near, far)
2965       # Meshes overlap so that they don't 'pop' when on the edge of the distance.
2966       meshes = ((".Hi", 0.0, -20.0),
2967             (".Med", -15.0, -50.0),
2968             (".Lo", -40.0, -100.0)
2969           )
2970       
2971       cont = logic.getCurrentController()
2972       object = cont.owner
2973       actuator = cont.actuators["LOD." + obj.name]
2974       camera = logic.getCurrentScene().active_camera
2975       
2976       def Depth(pos, plane):
2977         return pos[0]*plane[0] + pos[1]*plane[1] + pos[2]*plane[2] + plane[3]
2978       
2979       # Depth is negative and decreasing further from the camera
2980       depth = Depth(object.position, camera.world_to_camera[2])
2981       
2982       newmesh = None
2983       curmesh = None
2984       # Find the lowest detail mesh for depth
2985       for mesh in meshes:
2986         if depth < mesh[1] and depth > mesh[2]:
2987           newmesh = mesh
2988         if "ME" + object.name + mesh[0] == actuator.getMesh():
2989             curmesh = mesh
2990       
2991       if newmesh != None and "ME" + object.name + newmesh[0] != actuator.mesh:
2992         # The mesh is a different mesh - switch it.
2993         # Check the current mesh is not a better fit.
2994         if curmesh == None or curmesh[1] < depth or curmesh[2] > depth:
2995           actuator.mesh = object.name + newmesh[0]
2996           cont.activate(actuator)
2997
2998    .. attribute:: mesh
2999
3000       :class:`MeshProxy` or the name of the mesh that will replace the current one.
3001    
3002       Set to None to disable actuator.
3003
3004       :type: :class:`MeshProxy` or None if no mesh is set
3005
3006    .. attribute:: useDisplayMesh
3007
3008       when true the displayed mesh is replaced.
3009
3010       :type: boolean
3011
3012    .. attribute:: usePhysicsMesh
3013
3014       when true the physics mesh is replaced.
3015
3016       :type: boolean
3017
3018    .. method:: instantReplaceMesh()
3019
3020       Immediately replace mesh without delay.
3021
3022 .. class:: KX_Scene(PyObjectPlus)
3023
3024    An active scene that gives access to objects, cameras, lights and scene attributes.
3025
3026    The activity culling stuff is supposed to disable logic bricks when their owner gets too far
3027    from the active camera.  It was taken from some code lurking at the back of KX_Scene - who knows
3028    what it does!
3029
3030    .. code-block:: python
3031
3032       from bge import logic
3033
3034       # get the scene
3035       scene = logic.getCurrentScene()
3036
3037       # print all the objects in the scene
3038       for object in scene.objects:
3039          print(object.name)
3040
3041       # get an object named 'Cube'
3042       object = scene.objects["Cube"]
3043
3044       # get the first object in the scene.
3045       object = scene.objects[0]
3046
3047    .. code-block:: python
3048
3049       # Get the depth of an object in the camera view.
3050       from bge import logic
3051
3052       object = logic.getCurrentController().owner
3053       cam = logic.getCurrentScene().active_camera
3054
3055       # Depth is negative and decreasing further from the camera
3056       depth = object.position[0]*cam.world_to_camera[2][0] + object.position[1]*cam.world_to_camera[2][1] + object.position[2]*cam.world_to_camera[2][2] + cam.world_to_camera[2][3]
3057
3058    @bug: All attributes are read only at the moment.
3059
3060    .. attribute:: name
3061
3062       The scene's name, (read-only).
3063
3064       :type: string
3065
3066    .. attribute:: objects
3067
3068       A list of objects in the scene, (read-only).
3069
3070       :type: :class:`CListValue` of :class:`KX_GameObject`
3071
3072    .. attribute:: objectsInactive
3073
3074       A list of objects on background layers (used for the addObject actuator), (read-only).
3075
3076       :type: :class:`CListValue` of :class:`KX_GameObject`
3077
3078    .. attribute:: lights
3079
3080       A list of lights in the scene, (read-only).
3081
3082       :type: :class:`CListValue` of :class:`KX_LightObject`
3083
3084    .. attribute:: cameras
3085
3086       A list of cameras in the scene, (read-only).
3087
3088       :type: :class:`CListValue` of :class:`KX_Camera`
3089
3090    .. attribute:: active_camera
3091
3092       The current active camera.
3093
3094       :type: :class:`KX_Camera`
3095       
3096       .. note::
3097          
3098          This can be set directly from python to avoid using the :class:`KX_SceneActuator`.
3099
3100    .. attribute:: suspended
3101
3102       True if the scene is suspended, (read-only).
3103
3104       :type: boolean
3105
3106    .. attribute:: activity_culling
3107
3108       True if the scene is activity culling.
3109
3110       :type: boolean
3111
3112    .. attribute:: activity_culling_radius
3113
3114       The distance outside which to do activity culling. Measured in manhattan distance.
3115
3116       :type: float
3117
3118    .. attribute:: dbvt_culling
3119
3120       True when Dynamic Bounding box Volume Tree is set (read-only).
3121
3122       :type: boolean
3123
3124    .. attribute:: pre_draw
3125
3126       A list of callables to be run before the render step.
3127
3128       :type: list
3129
3130    .. attribute:: post_draw
3131
3132       A list of callables to be run after the render step.
3133
3134       :type: list
3135
3136    .. attribute:: gravity
3137
3138       The scene gravity using the world x, y and z axis.
3139
3140       :type: list [fx, fy, fz]
3141
3142    .. method:: addObject(object, other, time=0)
3143
3144       Adds an object to the scene like the Add Object Actuator would.
3145
3146       :arg object: The object to add
3147       :type object: :class:`KX_GameObject` or string
3148       :arg other: The object's center to use when adding the object
3149       :type other: :class:`KX_GameObject` or string
3150       :arg time: The lifetime of the added object, in frames. A time of 0 means the object will last forever.
3151       :type time: integer
3152       :return: The newly added object.
3153       :rtype: :class:`KX_GameObject`
3154
3155    .. method:: end()
3156
3157       Removes the scene from the game.
3158
3159    .. method:: restart()
3160
3161       Restarts the scene.
3162
3163    .. method:: replace(scene)
3164
3165       Replaces this scene with another one.
3166
3167       :arg scene: The name of the scene to replace this scene with.
3168       :type scene: string
3169
3170    .. method:: suspend()
3171
3172       Suspends this scene.
3173
3174    .. method:: resume()
3175
3176       Resume this scene.
3177
3178    .. method:: get(key, default=None)
3179
3180       Return the value matching key, or the default value if its not found.
3181       :return: The key value or a default.
3182
3183 .. class:: KX_SceneActuator(SCA_IActuator)
3184
3185    Scene Actuator logic brick.
3186
3187    .. warning::
3188
3189       Scene actuators that use a scene name will be ignored if at game start, the named scene doesn't exist or is empty
3190
3191       This will generate a warning in the console:
3192
3193       .. code-block:: none
3194       
3195          Error: GameObject 'Name' has a SceneActuator 'ActuatorName' (SetScene) without scene
3196
3197    .. attribute:: scene
3198
3199       the name of the scene to change to/overlay/underlay/remove/suspend/resume.
3200
3201       :type: string
3202
3203    .. attribute:: camera
3204
3205       the camera to change to.
3206
3207       :type: :class:`KX_Camera` on read, string or :class:`KX_Camera` on write
3208       
3209       .. note::
3210          
3211          When setting the attribute, you can use either a :class:`KX_Camera` or the name of the camera.
3212
3213    .. attribute:: useRestart
3214
3215       Set flag to True to restart the sene.
3216
3217       :type: boolean
3218
3219    .. attribute:: mode
3220
3221       The mode of the actuator.
3222
3223       :type: integer from 0 to 5.
3224
3225 .. class:: KX_SoundActuator(SCA_IActuator)
3226
3227    Sound Actuator.
3228
3229    The :data:`startSound`, :data:`pauseSound` and :data:`stopSound` do not requirethe actuator to be activated - they act instantly provided that the actuator has been activated once at least.
3230
3231    .. attribute:: fileName
3232
3233       The filename of the sound this actuator plays.
3234
3235       :type: string
3236
3237    .. attribute:: volume
3238
3239       The volume (gain) of the sound.
3240
3241       :type: float
3242
3243    .. attribute:: pitch
3244
3245       The pitch of the sound.
3246
3247       :type: float
3248
3249    .. attribute:: rollOffFactor
3250
3251       The roll off factor. Rolloff defines the rate of attenuation as the sound gets further away.
3252
3253       :type: float
3254
3255    .. attribute:: looping
3256
3257       The loop mode of the actuator.
3258
3259       :type: integer
3260
3261    .. attribute:: position
3262
3263       The position of the sound as a list: [x, y, z].
3264
3265       :type: float array
3266
3267    .. attribute:: velocity
3268
3269       The velocity of the emitter as a list: [x, y, z]. The relative velocity to the observer determines the pitch. List of 3 floats: [x, y, z].
3270
3271       :type: float array
3272
3273    .. attribute:: orientation
3274
3275       The orientation of the sound. When setting the orientation you can also use quaternion [float, float, float, float] or euler angles [float, float, float].
3276
3277       :type: 3x3 matrix [[float]]
3278
3279    .. attribute:: mode
3280
3281       The operation mode of the actuator. Can be one of :ref:`these constants<logic-sound-actuator>`
3282
3283       :type: integer
3284
3285 .. class:: KX_StateActuator(SCA_IActuator)
3286
3287    State actuator changes the state mask of parent object.
3288
3289    .. attribute:: operation
3290
3291       Type of bit operation to be applied on object state mask.
3292       
3293       You can use one of :ref:`these constants <state-actuator-operation>`
3294
3295       :type: integer
3296
3297    .. attribute:: mask
3298
3299       Value that defines the bits that will be modified by the operation.
3300
3301       The bits that are 1 in the mask will be updated in the object state.
3302
3303       The bits that are 0 are will be left unmodified expect for the Copy operation which copies the mask to the object state.
3304
3305       :type: integer
3306
3307 .. class:: KX_TrackToActuator(SCA_IActuator)
3308
3309    Edit Object actuator in Track To mode.
3310
3311    .. warning::
3312    
3313       Track To Actuators will be ignored if at game start, the object to track to is invalid.
3314
3315       This will generate a warning in the console:
3316
3317       .. code-block:: none
3318
3319          GameObject 'Name' no object in EditObjectActuator 'ActuatorName'
3320
3321    .. attribute:: object
3322
3323       the object this actuator tracks.
3324
3325       :type: :class:`KX_GameObject` or None
3326
3327    .. attribute:: time
3328
3329       the time in frames with which to delay the tracking motion.
3330
3331       :type: integer
3332
3333    .. attribute:: use3D
3334
3335       the tracking motion to use 3D.
3336
3337       :type: boolean
3338
3339 .. class:: KX_VehicleWrapper(PyObjectPlus)
3340
3341    KX_VehicleWrapper
3342
3343    TODO - description
3344
3345    .. method:: addWheel(wheel, attachPos, attachDir, axleDir, suspensionRestLength, wheelRadius, hasSteering)
3346
3347       Add a wheel to the vehicle
3348
3349       :arg wheel: The object to use as a wheel.
3350       :type wheel: :class:`KX_GameObject` or a KX_GameObject name
3351       :arg attachPos: The position that this wheel will attach to.
3352       :type attachPos: vector of 3 floats
3353       :arg attachDir: The direction this wheel points.
3354       :type attachDir: vector of 3 floats
3355       :arg axleDir: The direction of this wheels axle.
3356       :type axleDir: vector of 3 floats
3357       :arg suspensionRestLength: TODO - Description
3358       :type suspensionRestLength: float
3359       :arg wheelRadius: The size of the wheel.
3360       :type wheelRadius: float
3361
3362    .. method:: applyBraking(force, wheelIndex)
3363
3364       Apply a braking force to the specified wheel
3365
3366       :arg force: the brake force
3367       :type force: float
3368
3369       :arg wheelIndex: index of the wheel where the force needs to be applied
3370       :type wheelIndex: integer
3371
3372    .. method:: applyEngineForce(force, wheelIndex)
3373
3374       Apply an engine force to the specified wheel
3375
3376       :arg force: the engine force
3377       :type force: float
3378
3379       :arg wheelIndex: index of the wheel where the force needs to be applied
3380       :type wheelIndex: integer
3381
3382    .. method:: getConstraintId()
3383
3384       Get the constraint ID
3385
3386       :return: the constraint id
3387       :rtype: integer
3388
3389    .. method:: getConstraintType()
3390
3391       Returns the constraint type.
3392
3393       :return: constraint type
3394       :rtype: integer
3395
3396    .. method:: getNumWheels()
3397
3398       Returns the number of wheels.
3399
3400       :return: the number of wheels for this vehicle
3401       :rtype: integer
3402
3403    .. method:: getWheelOrientationQuaternion(wheelIndex)
3404
3405       Returns the wheel orientation as a quaternion.
3406
3407       :arg wheelIndex: the wheel index
3408       :type wheelIndex: integer
3409
3410       :return: TODO Description
3411       :rtype: TODO - type should be quat as per method name but from the code it looks like a matrix
3412
3413    .. method:: getWheelPosition(wheelIndex)
3414
3415       Returns the position of the specified wheel
3416
3417       :arg wheelIndex: the wheel index
3418       :type wheelIndex: integer
3419       :return: position vector
3420       :rtype: list[x, y, z]
3421
3422    .. method:: getWheelRotation(wheelIndex)
3423
3424       Returns the rotation of the specified wheel
3425
3426       :arg wheelIndex: the wheel index
3427       :type wheelIndex: integer
3428
3429       :return: the wheel rotation
3430       :rtype: float
3431
3432    .. method:: setRollInfluence(rollInfluece, wheelIndex)
3433
3434       Set the specified wheel's roll influence.
3435       The higher the roll influence the more the vehicle will tend to roll over in corners.
3436
3437       :arg rollInfluece: the wheel roll influence
3438       :type rollInfluece: float
3439
3440       :arg wheelIndex: the wheel index
3441       :type wheelIndex: integer
3442
3443    .. method:: setSteeringValue(steering, wheelIndex)
3444
3445       Set the specified wheel's steering
3446
3447       :arg steering: the wheel steering
3448       :type steering: float
3449
3450       :arg wheelIndex: the wheel index
3451       :type wheelIndex: integer
3452
3453    .. method:: setSuspensionCompression(compression, wheelIndex)
3454
3455       Set the specified wheel's compression
3456
3457       :arg compression: the wheel compression
3458       :type compression: float
3459
3460       :arg wheelIndex: the wheel index
3461       :type wheelIndex: integer
3462
3463    .. method:: setSuspensionDamping(damping, wheelIndex)
3464
3465       Set the specified wheel's damping
3466
3467       :arg damping: the wheel damping
3468       :type damping: float
3469
3470       :arg wheelIndex: the wheel index
3471       :type wheelIndex: integer
3472
3473    .. method:: setSuspensionStiffness(stiffness, wheelIndex)
3474
3475       Set the specified wheel's stiffness
3476
3477       :arg stiffness: the wheel stiffness
3478       :type stiffness: float
3479
3480       :arg wheelIndex: the wheel index
3481       :type wheelIndex: integer
3482
3483    .. method:: setTyreFriction(friction, wheelIndex)
3484
3485       Set the specified wheel's tyre friction
3486
3487       :arg friction: the tyre friction
3488       :type friction: float
3489
3490       :arg wheelIndex: the wheel index
3491       :type wheelIndex: integer
3492
3493 .. class:: KX_CharacterWrapper(PyObjectPlus)
3494
3495    A wrapper to expose character physics options.
3496
3497    .. attribute:: onGround
3498
3499       Whether or not the character is on the ground. (read-only)
3500
3501           :type: boolean
3502
3503    .. attribute:: gravity
3504
3505       The gravity value used for the character.
3506
3507       :type: float
3508
3509    .. method:: jump()
3510
3511       The character jumps based on it's jump speed.
3512
3513 .. class:: KX_VertexProxy(SCA_IObject)
3514
3515    A vertex holds position, UV, color and normal information.
3516
3517    Note:
3518    The physics simulation is NOT currently updated - physics will not respond
3519    to changes in the vertex position.
3520
3521    .. attribute:: XYZ
3522
3523       The position of the vertex.
3524
3525       :type: list [x, y, z]
3526
3527    .. attribute:: UV
3528
3529       The texture coordinates of the vertex.
3530
3531       :type: list [u, v]
3532
3533    .. attribute:: normal
3534
3535       The normal of the vertex.
3536
3537       :type: list [nx, ny, nz]
3538
3539    .. attribute:: color
3540
3541       The color of the vertex.
3542
3543       :type: list [r, g, b, a]
3544
3545       Black = [0.0, 0.0, 0.0, 1.0], White = [1.0, 1.0, 1.0, 1.0]
3546
3547    .. attribute:: colour
3548
3549       Synonym for color.
3550
3551    .. attribute:: x
3552
3553       The x coordinate of the vertex.
3554
3555       :type: float
3556
3557    .. attribute:: y
3558
3559       The y coordinate of the vertex.
3560
3561       :type: float
3562
3563    .. attribute:: z
3564
3565       The z coordinate of the vertex.
3566
3567       :type: float
3568
3569    .. attribute:: u
3570
3571       The u texture coordinate of the vertex.
3572
3573       :type: float
3574
3575    .. attribute:: v
3576
3577       The v texture coordinate of the vertex.
3578
3579       :type: float
3580
3581    .. attribute:: u2
3582
3583       The second u texture coordinate of the vertex.
3584
3585       :type: float
3586
3587    .. attribute:: v2
3588
3589       The second v texture coordinate of the vertex.
3590
3591       :type: float
3592
3593    .. attribute:: r
3594
3595       The red component of the vertex color. 0.0 <= r <= 1.0.
3596
3597       :type: float
3598
3599    .. attribute:: g
3600
3601       The green component of the vertex color. 0.0 <= g <= 1.0.
3602
3603       :type: float
3604
3605    .. attribute:: b
3606
3607       The blue component of the vertex color. 0.0 <= b <= 1.0.
3608
3609       :type: float
3610
3611    .. attribute:: a
3612
3613       The alpha component of the vertex color. 0.0 <= a <= 1.0.
3614
3615       :type: float
3616
3617    .. method:: getXYZ()
3618
3619       Gets the position of this vertex.
3620
3621       :return: this vertexes position in local coordinates.
3622       :rtype: list [x, y, z]
3623
3624    .. method:: setXYZ(pos)
3625
3626       Sets the position of this vertex.
3627
3628       :type:  list [x, y, z]
3629
3630       :arg pos: the new position for this vertex in local coordinates.
3631
3632    .. method:: getUV()
3633
3634       Gets the UV (texture) coordinates of this vertex.
3635
3636       :return: this vertexes UV (texture) coordinates.
3637       :rtype: list [u, v]
3638
3639    .. method:: setUV(uv)
3640
3641       Sets the UV (texture) coordinates of this vertex.
3642
3643       :type:  list [u, v]
3644
3645    .. method:: getUV2()
3646
3647       Gets the 2nd UV (texture) coordinates of this vertex.
3648
3649       :return: this vertexes UV (texture) coordinates.
3650       :rtype: list [u, v]
3651
3652    .. method:: setUV2(uv, unit)
3653
3654       Sets the 2nd UV (texture) coordinates of this vertex.
3655
3656       :type:  list [u, v]
3657
3658       :arg unit: optional argument, FLAT==1, SECOND_UV==2, defaults to SECOND_UV
3659       :arg unit:  integer
3660
3661    .. method:: getRGBA()
3662
3663       Gets the color of this vertex.
3664
3665       The color is represented as four bytes packed into an integer value.  The color is
3666       packed as RGBA.
3667
3668       Since Python offers no way to get each byte without shifting, you must use the struct module to
3669       access color in an machine independent way.
3670
3671       Because of this, it is suggested you use the r, g, b and a attributes or the color attribute instead.
3672
3673       .. code-block:: python
3674
3675          import struct;
3676          col = struct.unpack('4B', struct.pack('I', v.getRGBA()))
3677          # col = (r, g, b, a)
3678          # black = (  0, 0, 0, 255)
3679          # white = (255, 255, 255, 255)
3680
3681       :return: packed color. 4 byte integer with one byte per color channel in RGBA format.
3682       :rtype: integer
3683
3684    .. method:: setRGBA(col)
3685
3686       Sets the color of this vertex.
3687
3688       See getRGBA() for the format of col, and its relevant problems.  Use the r, g, b and a attributes
3689       or the color attribute instead.
3690
3691       setRGBA() also accepts a four component list as argument col.  The list represents the color as [r, g, b, a]
3692       with black = [0.0, 0.0, 0.0, 1.0] and white = [1.0, 1.0, 1.0, 1.0]
3693
3694       .. code-block:: python
3695
3696          v.setRGBA(0xff0000ff) # Red
3697          v.setRGBA(0xff00ff00) # Green on little endian, transparent purple on big endian
3698          v.setRGBA([1.0, 0.0, 0.0, 1.0]) # Red
3699          v.setRGBA([0.0, 1.0, 0.0, 1.0]) # Green on all platforms.
3700
3701       :arg col: the new color of this vertex in packed RGBA format.
3702       :type col: integer or list [r, g, b, a]
3703
3704    .. method:: getNormal()
3705
3706       Gets the normal vector of this vertex.
3707
3708       :return: normalized normal vector.
3709       :rtype: list [nx, ny, nz]
3710
3711    .. method:: setNormal(normal)
3712
3713       Sets the normal vector of this vertex.
3714
3715       :type:  sequence of floats [r, g, b]
3716
3717       :arg normal: the new normal of this vertex.
3718
3719 .. class:: KX_VisibilityActuator(SCA_IActuator)
3720
3721    Visibility Actuator.
3722
3723    .. attribute:: visibility
3724
3725       whether the actuator makes its parent object visible or invisible.
3726
3727       :type: boolean
3728
3729    .. attribute:: useOcclusion
3730
3731       whether the actuator makes its parent object an occluder or not.
3732
3733       :type: boolean
3734
3735    .. attribute:: useRecursion
3736
3737       whether the visibility/occlusion should be propagated to all children of the object.
3738
3739       :type: boolean
3740
3741 .. class:: SCA_2DFilterActuator(SCA_IActuator)
3742
3743    Create, enable and disable 2D filters
3744
3745    The following properties don't have an immediate effect.
3746    You must active the actuator to get the result.
3747    The actuator is not persistent: it automatically stops itself after setting up the filter
3748    but the filter remains active. To stop a filter you must activate the actuator with 'type'
3749    set to :data:`~bge.logic.RAS_2DFILTER_DISABLED` or :data:`~bge.logic.RAS_2DFILTER_NOFILTER`.
3750
3751    .. attribute:: shaderText
3752
3753       shader source code for custom shader.
3754
3755       :type: string
3756
3757    .. attribute:: disableMotionBlur
3758
3759       action on motion blur: 0=enable, 1=disable.
3760
3761       :type: integer
3762
3763    .. attribute:: mode
3764
3765       Type of 2D filter, use one of :ref:`these constants <Two-D-FilterActuator-mode>`
3766
3767       :type: integer
3768
3769    .. attribute:: passNumber
3770
3771       order number of filter in the stack of 2D filters. Filters are executed in increasing order of passNb.
3772
3773       Only be one filter can be defined per passNb.
3774
3775       :type: integer (0-100)
3776
3777    .. attribute:: value
3778
3779       argument for motion blur filter.
3780
3781       :type: float (0.0-100.0)
3782
3783 .. class:: SCA_ANDController(SCA_IController)
3784
3785    An AND controller activates only when all linked sensors are activated.
3786
3787    There are no special python methods for this controller.
3788
3789 .. class:: SCA_ActuatorSensor(SCA_ISensor)
3790
3791    Actuator sensor detect change in actuator state of the parent object.
3792    It generates a positive pulse if the corresponding actuator is activated
3793    and a negative pulse if the actuator is deactivated.
3794
3795    .. attribute:: actuator
3796
3797       the name of the actuator that the sensor is monitoring.
3798
3799       :type: string
3800
3801 .. class:: SCA_AlwaysSensor(SCA_ISensor)
3802
3803    This sensor is always activated.
3804
3805 .. class:: SCA_DelaySensor(SCA_ISensor)
3806
3807    The Delay sensor generates positive and negative triggers at precise time, 
3808    expressed in number of frames. The delay parameter defines the length of the initial OFF period. A positive trigger is generated at the end of this period.
3809
3810    The duration parameter defines the length of the ON period following the OFF period.
3811    There is a negative trigger at the end of the ON period. If duration is 0, the sensor stays ON and there is no negative trigger.
3812
3813    The sensor runs the OFF-ON cycle once unless the repeat option is set: the OFF-ON cycle repeats indefinately (or the OFF cycle if duration is 0).
3814
3815    Use :class:`SCA_ISensor.reset` at any time to restart sensor.
3816
3817    .. attribute:: delay
3818
3819       length of the initial OFF period as number of frame, 0 for immediate trigger.
3820
3821       :type: integer.
3822
3823    .. attribute:: duration
3824
3825       length of the ON period in number of frame after the initial OFF period.
3826
3827       If duration is greater than 0, a negative trigger is sent at the end of the ON pulse.
3828
3829       :type: integer
3830
3831    .. attribute:: repeat
3832
3833       1 if the OFF-ON cycle should be repeated indefinately, 0 if it should run once.
3834
3835       :type: integer
3836
3837 .. class:: SCA_JoystickSensor(SCA_ISensor)
3838
3839    This sensor detects player joystick events.
3840
3841    .. attribute:: axisValues
3842
3843       The state of the joysticks axis as a list of values :data:`numAxis` long. (read-only).
3844
3845       :type: list of ints.
3846
3847       Each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing.
3848       The first 2 values are used by most joysticks and gamepads for directional control. 3rd and 4th values are only on some joysticks and can be used for arbitary controls.
3849
3850       * left:[-32767, 0, ...]
3851       * right:[32767, 0, ...]
3852       * up:[0, -32767, ...]
3853       * down:[0, 32767, ...]
3854
3855    .. attribute:: axisSingle
3856
3857       like :data:`axisValues` but returns a single axis value that is set by the sensor. (read-only).
3858
3859       :type: integer
3860
3861       .. note::
3862          
3863          Only use this for "Single Axis" type sensors otherwise it will raise an error.
3864
3865    .. attribute:: hatValues
3866
3867       The state of the joysticks hats as a list of values :data:`numHats` long. (read-only).
3868
3869       :type: list of ints
3870
3871       Each spesifying the direction of the hat from 1 to 12, 0 when inactive.
3872
3873       Hat directions are as follows...
3874
3875       * 0:None
3876       * 1:Up
3877       * 2:Right
3878       * 4:Down
3879       * 8:Left
3880       * 3:Up - Right
3881       * 6:Down - Right
3882       * 12:Down - Left
3883       * 9:Up - Left
3884
3885    .. attribute:: hatSingle
3886
3887       Like :data:`hatValues` but returns a single hat direction value that is set by the sensor. (read-only).
3888
3889       :type: integer
3890
3891    .. attribute:: numAxis
3892
3893       The number of axes for the joystick at this index. (read-only).
3894
3895       :type: integer
3896
3897    .. attribute:: numButtons
3898
3899       The number of buttons for the joystick at this index. (read-only).
3900
3901       :type: integer
3902
3903    .. attribute:: numHats
3904
3905       The number of hats for the joystick at this index. (read-only).
3906
3907       :type: integer
3908
3909    .. attribute:: connected
3910
3911       True if a joystick is connected at this joysticks index. (read-only).
3912
3913       :type: boolean
3914
3915    .. attribute:: index
3916
3917       The joystick index to use (from 0 to 7). The first joystick is always 0.
3918
3919       :type: integer
3920
3921    .. attribute:: threshold
3922
3923       Axis threshold. Joystick axis motion below this threshold wont trigger an event. Use values between (0 and 32767), lower values are more sensitive.
3924
3925       :type: integer
3926
3927    .. attribute:: button
3928
3929       The button index the sensor reacts to (first button = 0). When the "All Events" toggle is set, this option has no effect.
3930
3931       :type: integer
3932
3933    .. at