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