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