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