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