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