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