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