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