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