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