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