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