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