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