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