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