11 This module contains the classes that appear as instances in the Game Engine. A
12 script must interact with these classes if it is to affect the behaviour of
15 The following example would move an object (i.e. an instance of
16 :class:`KX_GameObject`) one unit up.
18 .. code-block:: python
20 # bge.types.SCA_PythonController
21 cont = bge.logic.getCurrentController()
23 # bge.types.KX_GameObject
25 obj.worldPosition.z += 1
27 To run the code, it could be placed in a Blender text block and executed with
28 a :class:`SCA_PythonController` logic brick.
34 .. class:: PyObjectPlus
36 PyObjectPlus base class of most other types in the Game Engine.
38 .. attribute:: invalid
40 Test if the object has been freed by the game engine and is no longer valid.
42 Normally this is not a problem but when storing game engine data in the GameLogic module,
43 KX_Scenes or other KX_GameObjects its possible to hold a reference to invalid data.
44 Calling an attribute or method on an invalid object will raise a SystemError.
46 The invalid attribute allows testing for this case without exception handling.
50 .. class:: CValue(PyObjectPlus)
52 This class is a basis for other classes.
56 The name of this CValue derived object (read-only).
60 .. class:: CPropValue(CValue)
62 This class has no python functions
64 .. class:: SCA_ILogicBrick(CValue)
66 Base class for all logic bricks.
68 .. attribute:: executePriority
70 This determines the order controllers are evaluated, and actuators are activated (lower priority is executed first).
72 :type: executePriority: int
76 The game object this logic brick is attached to (read-only).
78 :type: :class:`KX_GameObject` or None in exceptional cases.
82 The name of this logic brick (read-only).
86 .. class:: SCA_PythonKeyboard(PyObjectPlus)
92 A dictionary containing the status of each keyboard event or key. (read-only).
94 :type: dictionary {:ref:`keycode<keyboard-keys>`::ref:`status<input-status>`, ...}
96 .. attribute:: active_events
98 A dictionary containing the status of only the active keyboard events or keys. (read-only).
100 :type: dictionary {:ref:`keycode<keyboard-keys>`::ref:`status<input-status>`, ...}
103 .. function:: getClipboard()
105 Gets the clipboard text.
109 .. function:: setClipboard(text)
111 Sets the clipboard text.
113 :arg text: New clipboard text
116 .. class:: SCA_PythonMouse(PyObjectPlus)
120 .. attribute:: events
122 a dictionary containing the status of each mouse event. (read-only).
124 :type: dictionary {:ref:`keycode<mouse-keys>`::ref:`status<input-status>`, ...}
126 .. attribute:: active_events
128 a dictionary containing the status of only the active mouse events. (read-only).
130 :type: dictionary {:ref:`keycode<mouse-keys>`::ref:`status<input-status>`, ...}
132 .. attribute:: position
134 The normalized x and y position of the mouse cursor.
138 .. attribute:: visible
140 The visibility of the mouse cursor.
144 .. class:: SCA_IObject(CValue)
146 This class has no python functions
148 .. class:: SCA_ISensor(SCA_ILogicBrick)
150 Base class for all sensor logic bricks.
152 .. attribute:: usePosPulseMode
154 Flag to turn positive pulse mode on and off.
158 .. attribute:: useNegPulseMode
160 Flag to turn negative pulse mode on and off.
164 .. attribute:: frequency
166 The frequency for pulse mode sensors.
172 level Option whether to detect level or edge transition when entering a state.
173 It makes a difference only in case of logic state transition (state actuator).
174 A level detector will immediately generate a pulse, negative or positive
175 depending on the sensor condition, as soon as the state is activated.
176 A edge detector will wait for a state change before generating a pulse.
177 note: mutually exclusive with :data:`tap`, enabling will disable :data:`tap`.
183 When enabled only sensors that are just activated will send a positive event,
184 after this they will be detected as negative by the controllers.
185 This will make a key thats held act as if its only tapped for an instant.
186 note: mutually exclusive with :data:`level`, enabling will disable :data:`level`.
190 .. attribute:: invert
192 Flag to set if this sensor activates on positive or negative events.
196 .. attribute:: triggered
198 True if this sensor brick is in a positive state. (read-only).
202 .. attribute:: positive
204 True if this sensor brick is in a positive state. (read-only).
208 .. attribute:: status
210 The status of the sensor (read-only): can be one of :ref:`these constants<sensor-status>`.
216 This convenient attribute combines the values of triggered and positive attributes.
220 Reset sensor internal state, effect depends on the type of sensor and settings.
222 The sensor is put in its initial state as if it was just activated.
224 .. class:: SCA_IController(SCA_ILogicBrick)
226 Base class for all controller logic bricks.
230 The controllers state bitmask. This can be used with the GameObject's state to test if the controller is active.
234 .. attribute:: sensors
236 A list of sensors linked to this controller.
238 :type: sequence supporting index/string lookups and iteration.
242 The sensors are not necessarily owned by the same object.
246 When objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
248 .. attribute:: actuators
250 A list of actuators linked to this controller.
252 :type: sequence supporting index/string lookups and iteration.
256 The sensors are not necessarily owned by the same object.
260 When objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
262 .. attribute:: useHighPriority
264 When set the controller executes always before all other controllers that dont have this set.
270 Order of execution between high priority controllers is not guaranteed.
272 .. class:: SCA_IActuator(SCA_ILogicBrick)
274 Base class for all actuator logic bricks.
276 .. class:: BL_ActionActuator(SCA_IActuator)
278 Action Actuators apply an action to an actor.
280 .. attribute:: action
282 The name of the action to set as the current action.
286 .. attribute:: frameStart
288 Specifies the starting frame of the animation.
292 .. attribute:: frameEnd
294 Specifies the ending frame of the animation.
298 .. attribute:: blendIn
300 Specifies the number of frames of animation to generate when making transitions between actions.
304 .. attribute:: priority
306 Sets the priority of this actuator. Actuators will lower priority numbers will override actuators with higher numbers.
312 Sets the current frame for the animation.
316 .. attribute:: propName
318 Sets the property to be used in FromProp playback mode.
322 .. attribute:: blendTime
324 Sets the internal frame timer. This property must be in the range from 0.0 to blendIn.
330 The operation mode of the actuator. Can be one of :ref:`these constants<action-actuator>`.
334 .. attribute:: useContinue
336 The actions continue option, True or False. When True, the action will always play from where last left off,
337 otherwise negative events to this actuator will reset it to its start frame.
341 .. attribute:: framePropName
343 The name of the property that is set to the current frame number.
347 .. class:: BL_Shader(PyObjectPlus)
349 BL_Shader GLSL shaders.
353 .. method:: setUniformfv(name, fList)
355 Set a uniform with a list of float values
357 :arg name: the uniform name
359 :arg fList: a list (2, 3 or 4 elements) of float values
360 :type fList: list[float]
362 .. method:: delSource()
364 Clear the shader. Use this method before the source is changed with :data:`setSource`.
366 .. method:: getFragmentProg()
368 Returns the fragment program.
370 :return: The fragment program.
373 .. method:: getVertexProg()
375 Get the vertex program.
377 :return: The vertex program.
380 .. method:: isValid()
382 Check if the shader is valid.
384 :return: True if the shader is valid
387 .. method:: setAttrib(enum)
389 Set attribute location. (The parameter is ignored a.t.m. and the value of "tangent" is always used.)
391 :arg enum: attribute location value
394 .. method:: setNumberOfPasses( max_pass )
396 Set the maximum number of passes. Not used a.t.m.
398 :arg max_pass: the maximum number of passes
399 :type max_pass: integer
401 .. method:: setSampler(name, index)
403 Set uniform texture sample index.
405 :arg name: Uniform name
407 :arg index: Texture sample index.
410 .. method:: setSource(vertexProgram, fragmentProgram)
412 Set the vertex and fragment programs
414 :arg vertexProgram: Vertex program
415 :type vertexProgram: string
416 :arg fragmentProgram: Fragment program
417 :type fragmentProgram: string
419 .. method:: setUniform1f(name, fx)
421 Set a uniform with 1 float value.
423 :arg name: the uniform name
425 :arg fx: Uniform value
428 .. method:: setUniform1i(name, ix)
430 Set a uniform with an integer value.
432 :arg name: the uniform name
434 :arg ix: the uniform value
437 .. method:: setUniform2f(name, fx, fy)
439 Set a uniform with 2 float values
441 :arg name: the uniform name
443 :arg fx: first float value
446 :arg fy: second float value
449 .. method:: setUniform2i(name, ix, iy)
451 Set a uniform with 2 integer values
453 :arg name: the uniform name
455 :arg ix: first integer value
457 :arg iy: second integer value
460 .. method:: setUniform3f(name, fx, fy, fz)
462 Set a uniform with 3 float values.
464 :arg name: the uniform name
466 :arg fx: first float value
468 :arg fy: second float value
470 :arg fz: third float value
473 .. method:: setUniform3i(name, ix, iy, iz)
475 Set a uniform with 3 integer values
477 :arg name: the uniform name
479 :arg ix: first integer value
481 :arg iy: second integer value
483 :arg iz: third integer value
486 .. method:: setUniform4f(name, fx, fy, fz, fw)
488 Set a uniform with 4 float values.
490 :arg name: the uniform name
492 :arg fx: first float value
494 :arg fy: second float value
496 :arg fz: third float value
498 :arg fw: fourth float value
501 .. method:: setUniform4i(name, ix, iy, iz, iw)
503 Set a uniform with 4 integer values
505 :arg name: the uniform name
507 :arg ix: first integer value
509 :arg iy: second integer value
511 :arg iz: third integer value
513 :arg iw: fourth integer value
516 .. method:: setUniformDef(name, type)
520 :arg name: the uniform name
522 :arg type: uniform type
523 :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
525 .. method:: setUniformMatrix3(name, mat, transpose)
527 Set a uniform with a 3x3 matrix value
529 :arg name: the uniform name
531 :arg mat: A 3x3 matrix [[f, f, f], [f, f, f], [f, f, f]]
532 :type mat: 3x3 matrix
533 :arg transpose: set to True to transpose the matrix
534 :type transpose: boolean
536 .. method:: setUniformMatrix4(name, mat, transpose)
538 Set a uniform with a 4x4 matrix value
540 :arg name: the uniform name
542 :arg mat: A 4x4 matrix [[f, f, f, f], [f, f, f, f], [f, f, f, f], [f, f, f, f]]
543 :type mat: 4x4 matrix
544 :arg transpose: set to True to transpose the matrix
545 :type transpose: boolean
547 .. method:: setUniformiv(name, iList)
549 Set a uniform with a list of integer values
551 :arg name: the uniform name
553 :arg iList: a list (2, 3 or 4 elements) of integer values
554 :type iList: list[integer]
556 .. method:: validate()
558 Validate the shader object.
560 .. class:: BL_ShapeActionActuator(SCA_IActuator)
562 ShapeAction Actuators apply an shape action to an mesh object.
564 .. attribute:: action
566 The name of the action to set as the current shape action.
570 .. attribute:: frameStart
572 Specifies the starting frame of the shape animation.
576 .. attribute:: frameEnd
578 Specifies the ending frame of the shape animation.
582 .. attribute:: blendIn
584 Specifies the number of frames of animation to generate when making transitions between actions.
588 .. attribute:: priority
590 Sets the priority of this actuator. Actuators will lower priority numbers will override actuators with higher numbers.
596 Sets the current frame for the animation.
600 .. attribute:: propName
602 Sets the property to be used in FromProp playback mode.
606 .. attribute:: blendTime
608 Sets the internal frame timer. This property must be in the range from 0.0 to blendin.
614 The operation mode of the actuator. Can be one of :ref:`these constants<shape-action-actuator>`.
618 .. attribute:: framePropName
620 The name of the property that is set to the current frame number.
624 .. class:: CListValue(CPropValue)
626 This is a list like object used in the game engine internally that behaves similar to a python list in most ways.
628 As well as the normal index lookup (``val= clist[i]``), CListValue supports string lookups (``val= scene.objects["Cube"]``)
630 Other operations such as ``len(clist)``, ``list(clist)``, ``clist[0:10]`` are also supported.
632 .. method:: append(val)
634 Add an item to the list (like pythons append)
638 Appending values to the list can cause crashes when the list is used internally by the game engine.
640 .. method:: count(val)
642 Count the number of instances of a value in the list.
644 :return: number of instances
647 .. method:: index(val)
649 Return the index of a value in the list.
651 :return: The index of the value in the list.
654 .. method:: reverse()
656 Reverse the order of the list.
658 .. method:: get(key, default=None)
660 Return the value matching key, or the default value if its not found.
662 :return: The key value or a default.
664 .. method:: from_id(id)
666 This is a funtion especially for the game engine to return a value with a spesific id.
668 Since object names are not always unique, the id of an object can be used to get an object from the CValueList.
672 .. code-block:: python
674 myObID=id(gameObject)
675 ob= scene.objects.from_id(myObID)
677 Where ``myObID`` is an int or long from the id function.
679 This has the advantage that you can store the id in places you could not store a gameObject.
683 The id is derived from a memory location and will be different each time the game engine starts.
685 .. class:: KX_BlenderMaterial(PyObjectPlus)
689 .. method:: getShader()
691 Returns the material's shader.
693 :return: the material's shader
694 :rtype: :class:`BL_Shader`
696 .. method:: setBlending(src, dest)
698 Set the pixel color arithmetic functions.
700 :arg src: Specifies how the red, green, blue, and alpha source blending factors are computed.
701 :type src: Value in...
706 * GL_ONE_MINUS_SRC_COLOR,
708 * GL_ONE_MINUS_DST_COLOR,
710 * GL_ONE_MINUS_SRC_ALPHA,
712 * GL_ONE_MINUS_DST_ALPHA,
713 * GL_SRC_ALPHA_SATURATE
715 :arg dest: Specifies how the red, green, blue, and alpha destination blending factors are computed.
716 :type dest: Value in...
721 * GL_ONE_MINUS_SRC_COLOR
723 * GL_ONE_MINUS_DST_COLOR
725 * GL_ONE_MINUS_SRC_ALPHA
727 * GL_ONE_MINUS_DST_ALPHA
728 * GL_SRC_ALPHA_SATURATE
730 .. method:: getMaterialIndex()
732 Returns the material's index.
734 :return: the material's index
737 .. class:: KX_CameraActuator(SCA_IActuator)
739 Applies changes to a camera.
741 .. attribute:: damping
743 strength of of the camera following movement.
749 minimum distance to the target object maintained by the actuator.
755 maximum distance to stay from the target object.
759 .. attribute:: height
761 height to stay above the target object.
767 axis this actuator is tracking, True=X, False=Y.
771 .. attribute:: object
773 the object this actuator tracks.
775 :type: :class:`KX_GameObject` or None
777 .. class:: KX_ConstraintActuator(SCA_IActuator)
779 A constraint actuator limits the position, rotation, distance or orientation of an object.
783 Time constant of the constraint expressed in frame (not use by Force field constraint).
787 .. attribute:: rotDamp
789 Time constant for the rotation expressed in frame (only for the distance constraint), 0 = use damp for rotation as well.
793 .. attribute:: direction
795 The reference direction in world coordinate for the orientation constraint.
797 :type: 3-tuple of float: (x, y, z)
799 .. attribute:: option
801 Binary combination of :ref:`these constants <constraint-actuator-option>`
807 activation time of the actuator. The actuator disables itself after this many frame. If set to 0, the actuator is not limited in time.
811 .. attribute:: propName
813 the name of the property or material for the ray detection of the distance constraint.
819 The lower bound of the constraint. For the rotation and orientation constraint, it represents radiant.
823 .. attribute:: distance
825 the target distance of the distance constraint.
831 the upper bound of the constraint. For rotation and orientation constraints, it represents radiant.
835 .. attribute:: rayLength
837 the length of the ray of the distance constraint.
843 type of constraint. Use one of the :ref:`these constants <constraint-actuator-limit>`
848 .. class:: KX_ConstraintWrapper(PyObjectPlus)
852 .. method:: getConstraintId(val)
854 Returns the contraint's ID
856 :return: the constraint's ID
859 .. class:: KX_GameActuator(SCA_IActuator)
861 The game actuator loads a new .blend file, restarts the current .blend file or quits the game.
863 .. attribute:: fileName
865 the new .blend file to load.
871 The mode of this actuator. Can be on of :ref:`these constants <game-actuator>`
875 .. class:: KX_GameObject(SCA_IObject)
877 All game objects are derived from this class.
879 Properties assigned to game objects are accessible as attributes of this class.
883 Calling ANY method or attribute on an object that has been removed from a scene will raise a SystemError,
884 if an object may have been removed since last accessing it use the :data:`invalid` attribute to check.
886 KX_GameObject can be subclassed to extend functionality. For example:
888 .. code-block:: python
892 class CustomGameObject(bge.types.KX_GameObject):
895 def __init__(self, old_owner):
896 # "old_owner" can just be ignored. At this point, "self" is
897 # already the object in the scene, and "old_owner" has been
900 # New attributes can be defined - but we could also use a game
901 # property, like "self['rate']".
902 self.rate = CustomGameObject.RATE
905 self.worldPosition.z += self.rate
908 if self.worldPosition.z > 1.0:
909 self.rate = -CustomGameObject.RATE
910 elif self.worldPosition.z < 0.0:
911 self.rate = CustomGameObject.RATE
915 old_object = cont.owner
916 mutated_object = CustomGameObject(cont.owner)
918 # After calling the constructor above, references to the old object
919 # should not be used.
920 assert(old_object is not mutated_object)
921 assert(old_object.invalid)
922 assert(mutated_object is cont.owner)
924 # Called later - note we are now working with the mutated object.
928 When subclassing objects other than empties and meshes, the specific type
929 should be used - e.g. inherit from :class:`BL_ArmatureObject` when the object
930 to mutate is an armature.
934 The object's name. (read-only).
946 The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0.
948 .. attribute:: linVelocityMin
950 Enforces the object keeps moving at a minimum velocity.
956 Applies to dynamic and rigid body objects only.
960 A value of 0.0 disables this option.
964 While objects are stationary the minimum velocity will not be applied.
966 .. attribute:: linVelocityMax
968 Clamp the maximum linear velocity to prevent objects moving beyond a set speed.
974 Applies to dynamic and rigid body objects only.
978 A value of 0.0 disables this option (rather then setting it stationary).
980 .. attribute:: localInertia
982 the object's inertia vector in local coordinates. Read only.
984 :type: list [ix, iy, iz]
986 .. attribute:: parent
988 The object's parent object. (read-only).
990 :type: :class:`KX_GameObject` or None
992 .. attribute:: group_children
994 Returns the list of group members if the object is a group object, otherwise None is returned.
996 :type: :class:`CListValue` of :class:`KX_GameObject` or None
998 .. attribute:: group_parent
1000 Returns the group object that the object belongs to or None if the object is not part of a group.
1002 :type: :class:`KX_GameObject` or None
1004 .. attribute:: scene
1006 The object's scene. (read-only).
1008 :type: :class:`KX_Scene` or None
1010 .. attribute:: visible
1018 Game logic will still run for invisible objects.
1020 .. attribute:: color
1022 The object color of the object. [r, g, b, a]
1024 :type: :class:`mathutils.Vector`
1026 .. attribute:: occlusion
1028 occlusion capability flag.
1032 .. attribute:: position
1034 The object's position. [x, y, z] On write: local position, on read: world position
1036 .. deprecated:: use :data:`localPosition` and :data:`worldPosition`.
1038 :type: :class:`mathutils.Vector`
1040 .. attribute:: orientation
1042 The object's orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector. On write: local orientation, on read: world orientation
1044 .. deprecated:: use :data:`localOrientation` and :data:`worldOrientation`.
1046 :type: :class:`mathutils.Matrix`
1048 .. attribute:: scaling
1050 The object's scaling factor. [sx, sy, sz] On write: local scaling, on read: world scaling
1052 .. deprecated:: use :data:`localScale` and :data:`worldScale`.
1054 :type: :class:`mathutils.Vector`
1056 .. attribute:: localOrientation
1058 The object's local orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.
1060 :type: :class:`mathutils.Matrix`
1062 .. attribute:: worldOrientation
1064 The object's world orientation. 3x3 Matrix.
1066 :type: :class:`mathutils.Matrix`
1068 .. attribute:: localScale
1070 The object's local scaling factor. [sx, sy, sz]
1072 :type: :class:`mathutils.Vector`
1074 .. attribute:: worldScale
1076 The object's world scaling factor. [sx, sy, sz]
1078 :type: :class:`mathutils.Vector`
1080 .. attribute:: localPosition
1082 The object's local position. [x, y, z]
1084 :type: :class:`mathutils.Vector`
1086 .. attribute:: worldPosition
1088 The object's world position. [x, y, z]
1090 :type: :class:`mathutils.Vector`
1092 .. attribute:: localTransform
1094 The object's local space transform matrix. 4x4 Matrix.
1096 :type: :class:`mathutils.Matrix`
1098 .. attribute:: worldTransform
1100 The object's world space transform matrix. 4x4 Matrix.
1102 :type: :class:`mathutils.Matrix`
1104 .. attribute:: localLinearVelocity
1106 The object's local linear velocity. [x, y, z]
1108 :type: :class:`mathutils.Vector`
1110 .. attribute:: worldLinearVelocity
1112 The object's world linear velocity. [x, y, z]
1114 :type: :class:`mathutils.Vector`
1116 .. attribute:: localAngularVelocity
1118 The object's local angular velocity. [x, y, z]
1120 :type: :class:`mathutils.Vector`
1122 .. attribute:: worldAngularVelocity
1124 The object's world angular velocity. [x, y, z]
1126 :type: :class:`mathutils.Vector`
1128 .. attribute:: timeOffset
1130 adjust the slowparent delay at runtime.
1134 .. attribute:: state
1136 the game object's state bitmask, using the first 30 bits, one bit must always be set.
1140 .. attribute:: meshes
1142 a list meshes for this object.
1144 :type: list of :class:`KX_MeshProxy`
1148 Most objects use only 1 mesh.
1152 Changes to this list will not update the KX_GameObject.
1154 .. attribute:: sensors
1156 a sequence of :class:`SCA_ISensor` objects with string/index lookups and iterator support.
1162 This attribute is experemental and may be removed (but probably wont be).
1166 Changes to this list will not update the KX_GameObject.
1168 .. attribute:: controllers
1170 a sequence of :class:`SCA_IController` objects with string/index lookups and iterator support.
1172 :type: list of :class:`SCA_ISensor`
1176 This attribute is experemental and may be removed (but probably wont be).
1180 Changes to this list will not update the KX_GameObject.
1182 .. attribute:: actuators
1184 a list of :class:`SCA_IActuator` with string/index lookups and iterator support.
1190 This attribute is experemental and may be removed (but probably wont be).
1194 Changes to this list will not update the KX_GameObject.
1196 .. attribute:: attrDict
1198 get the objects internal python attribute dictionary for direct (faster) access.
1202 .. attribute:: children
1204 direct children of this object, (read-only).
1206 :type: :class:`CListValue` of :class:`KX_GameObject`'s
1208 .. attribute:: childrenRecursive
1210 all children of this object including childrens children, (read-only).
1212 :type: :class:`CListValue` of :class:`KX_GameObject`'s
1214 .. method:: endObject()
1216 Delete this object, can be used in place of the EndObject Actuator.
1218 The actual removal of the object from the scene is delayed.
1220 .. method:: replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)
1222 Replace the mesh of this object with a new mesh. This works the same was as the actuator.
1224 :arg mesh: mesh to replace or the meshes name.
1225 :type mesh: :class:`MeshProxy` or string
1226 :arg useDisplayMesh: when enabled the display mesh will be replaced (optional argument).
1227 :type useDisplayMesh: boolean
1228 :arg usePhysicsMesh: when enabled the physics mesh will be replaced (optional argument).
1229 :type usePhysicsMesh: boolean
1231 .. method:: setVisible(visible, recursive)
1233 Sets the game object's visible flag.
1235 :arg visible: the visible state to set.
1236 :type visible: boolean
1237 :arg recursive: optional argument to set all childrens visibility flag too.
1238 :type recursive: boolean
1240 .. method:: setOcclusion(occlusion, recursive)
1242 Sets the game object's occlusion capability.
1244 :arg occlusion: the state to set the occlusion to.
1245 :type occlusion: boolean
1246 :arg recursive: optional argument to set all childrens occlusion flag too.
1247 :type recursive: boolean
1249 .. method:: alignAxisToVect(vect, axis=2, factor=1.0)
1251 Aligns any of the game object's axis along the given vector.
1254 :arg vect: a vector to align the axis.
1255 :type vect: 3D vector
1256 :arg axis: The axis you want to align
1263 :arg factor: Only rotate a feaction of the distance to the target vector (0.0 - 1.0)
1266 .. method:: getAxisVect(vect)
1268 Returns the axis vector rotates by the objects worldspace orientation.
1269 This is the equivalent of multiplying the vector by the orientation matrix.
1271 :arg vect: a vector to align the axis.
1272 :type vect: 3D Vector
1273 :return: The vector in relation to the objects rotation.
1276 .. method:: applyMovement(movement, local=False)
1278 Sets the game object's movement.
1280 :arg movement: movement vector.
1281 :type movement: 3D Vector
1283 * False: you get the "global" movement ie: relative to world orientation.
1284 * True: you get the "local" movement ie: relative to object orientation.
1287 .. method:: applyRotation(rotation, local=False)
1289 Sets the game object's rotation.
1291 :arg rotation: rotation vector.
1292 :type rotation: 3D Vector
1294 * False: you get the "global" rotation ie: relative to world orientation.
1295 * True: you get the "local" rotation ie: relative to object orientation.
1298 .. method:: applyForce(force, local=False)
1300 Sets the game object's force.
1302 This requires a dynamic object.
1304 :arg force: force vector.
1305 :type force: 3D Vector
1307 * False: you get the "global" force ie: relative to world orientation.
1308 * True: you get the "local" force ie: relative to object orientation.
1309 :type local: boolean
1311 .. method:: applyTorque(torque, local=False)
1313 Sets the game object's torque.
1315 This requires a dynamic object.
1317 :arg torque: torque vector.
1318 :type torque: 3D Vector
1320 * False: you get the "global" torque ie: relative to world orientation.
1321 * True: you get the "local" torque ie: relative to object orientation.
1322 :type local: boolean
1324 .. method:: getLinearVelocity(local=False)
1326 Gets the game object's linear velocity.
1328 This method returns the game object's velocity through it's centre of mass, ie no angular velocity component.
1331 * False: you get the "global" velocity ie: relative to world orientation.
1332 * True: you get the "local" velocity ie: relative to object orientation.
1333 :type local: boolean
1334 :return: the object's linear velocity.
1335 :rtype: list [vx, vy, vz]
1337 .. method:: setLinearVelocity(velocity, local=False)
1339 Sets the game object's linear velocity.
1341 This method sets game object's velocity through it's centre of mass,
1342 ie no angular velocity component.
1344 This requires a dynamic object.
1346 :arg velocity: linear velocity vector.
1347 :type velocity: 3D Vector
1349 * False: you get the "global" velocity ie: relative to world orientation.
1350 * True: you get the "local" velocity ie: relative to object orientation.
1351 :type local: boolean
1353 .. method:: getAngularVelocity(local=False)
1355 Gets the game object's angular velocity.
1358 * False: you get the "global" velocity ie: relative to world orientation.
1359 * True: you get the "local" velocity ie: relative to object orientation.
1360 :type local: boolean
1361 :return: the object's angular velocity.
1362 :rtype: list [vx, vy, vz]
1364 .. method:: setAngularVelocity(velocity, local=False)
1366 Sets the game object's angular velocity.
1368 This requires a dynamic object.
1370 :arg velocity: angular velocity vector.
1371 :type velocity: boolean
1373 * False: you get the "global" velocity ie: relative to world orientation.
1374 * True: you get the "local" velocity ie: relative to object orientation.
1376 .. method:: getVelocity(point=(0, 0, 0))
1378 Gets the game object's velocity at the specified point.
1380 Gets the game object's velocity at the specified point, including angular
1383 :arg point: optional point to return the velocity for, in local coordinates.
1384 :type point: 3D Vector
1385 :return: the velocity at the specified point.
1386 :rtype: list [vx, vy, vz]
1388 .. method:: getReactionForce()
1390 Gets the game object's reaction force.
1392 The reaction force is the force applied to this object over the last simulation timestep.
1393 This also includes impulses, eg from collisions.
1395 :return: the reaction force of this object.
1396 :rtype: list [fx, fy, fz]
1400 This is not implimented at the moment.
1402 .. method:: applyImpulse(point, impulse)
1404 Applies an impulse to the game object.
1406 This will apply the specified impulse to the game object at the specified point.
1407 If point != position, applyImpulse will also change the object's angular momentum.
1408 Otherwise, only linear momentum will change.
1410 :arg point: the point to apply the impulse to (in world coordinates)
1411 :type point: the point to apply the impulse to (in world coordinates)
1413 .. method:: suspendDynamics()
1415 Suspends physics for this object.
1417 .. method:: restoreDynamics()
1419 Resumes physics for this object.
1423 The objects linear velocity will be applied from when the dynamics were suspended.
1425 .. method:: enableRigidBody()
1427 Enables rigid body physics for this object.
1429 Rigid body physics allows the object to roll on collisions.
1431 .. method:: disableRigidBody()
1433 Disables rigid body physics for this object.
1435 .. method:: setParent(parent, compound=True, ghost=True)
1437 Sets this object's parent.
1438 Control the shape status with the optional compound and ghost parameters:
1440 In that case you can control if it should be ghost or not:
1442 :arg parent: new parent object.
1443 :type parent: :class:`KX_GameObject`
1444 :arg compound: whether the shape should be added to the parent compound shape.
1446 * True: the object shape should be added to the parent compound shape.
1447 * False: the object should keep its individual shape.
1449 :type compound: boolean
1450 :arg ghost: whether the object should be ghost while parented.
1452 * True: if the object should be made ghost while parented.
1453 * False: if the object should be solid while parented.
1455 :type ghost: boolean
1459 If the object type is sensor, it stays ghost regardless of ghost parameter
1461 .. method:: removeParent()
1463 Removes this objects parent.
1465 .. method:: getPhysicsId()
1467 Returns the user data object associated with this game object's physics controller.
1469 .. method:: getPropertyNames()
1471 Gets a list of all property names.
1473 :return: All property names for this object.
1476 .. method:: getDistanceTo(other)
1478 :arg other: a point or another :class:`KX_GameObject` to measure the distance to.
1479 :type other: :class:`KX_GameObject` or list [x, y, z]
1480 :return: distance to another object or point.
1483 .. method:: getVectTo(other)
1485 Returns the vector and the distance to another object or point.
1486 The vector is normalized unless the distance is 0, in which a zero length vector is returned.
1488 :arg other: a point or another :class:`KX_GameObject` to get the vector and distance to.
1489 :type other: :class:`KX_GameObject` or list [x, y, z]
1490 :return: (distance, globalVector(3), localVector(3))
1491 :rtype: 3-tuple (float, 3-tuple (x, y, z), 3-tuple (x, y, z))
1493 .. method:: rayCastTo(other, dist, prop)
1495 Look towards another point/object and find first object hit within dist that matches prop.
1497 The ray is always casted from the center of the object, ignoring the object itself.
1498 The ray is casted towards the center of another object or an explicit [x, y, z] point.
1499 Use rayCast() if you need to retrieve the hit point
1501 :arg other: [x, y, z] or object towards which the ray is casted
1502 :type other: :class:`KX_GameObject` or 3-tuple
1503 :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
1505 :arg prop: property name that object must have; can be omitted => detect any object
1507 :return: the first object hit or None if no object or object does not match prop
1508 :rtype: :class:`KX_GameObject`
1510 .. method:: rayCast(objto, objfrom, dist, prop, face, xray, poly)
1512 Look from a point/object to another point/object and find first object hit within dist that matches prop.
1513 if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None, None, None) if no hit.
1514 if poly is 1, returns a 4-tuple with in addition a :class:`KX_PolyProxy` as 4th element.
1515 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.
1517 .. code-block:: python
1519 # shoot along the axis gun-gunAim (gunAim should be collision-free)
1520 obj, point, normal = gun.rayCast(gunAim, None, 50)
1525 The face paremeter determines the orientation of the normal.
1527 * 0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
1528 * 1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
1530 The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
1531 The prop and xray parameters interact as follow.
1533 * prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
1534 * prop off, xray on : idem.
1535 * prop on, xray off: return closest hit if it matches prop, no hit otherwise.
1536 * 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.
1538 The :class:`KX_PolyProxy` 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray.
1539 If there is no hit or the hit object is not a static mesh, None is returned as 4th element.
1541 The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
1543 :arg objto: [x, y, z] or object to which the ray is casted
1544 :type objto: :class:`KX_GameObject` or 3-tuple
1545 :arg objfrom: [x, y, z] or object from which the ray is casted; None or omitted => use self object center
1546 :type objfrom: :class:`KX_GameObject` or 3-tuple or None
1547 :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
1549 :arg prop: property name that object must have; can be omitted or "" => detect any object
1551 :arg face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
1553 :arg xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
1555 :arg poly: polygon option: 0, 1 or 2 to return a 3-, 4- or 5-tuple with information on the face hit.
1557 * 0 or omitted: return value is a 3-tuple (object, hitpoint, hitnormal) or (None, None, None) if no hit
1558 * 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.
1559 * 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.
1562 :return: (object, hitpoint, hitnormal) or (object, hitpoint, hitnormal, polygon) or (object, hitpoint, hitnormal, polygon, hituv).
1564 * object, hitpoint and hitnormal are None if no hit.
1565 * 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
1566 * hituv is valid only if polygon is valid and the object has a UV mapping, otherwise it is None
1570 * 3-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz))
1571 * or 4-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz), :class:`PolyProxy`)
1572 * or 5-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz), :class:`PolyProxy`, 2-tuple (u, v))
1576 The ray ignores the object on which the method is called. It is casted from/to object center or explicit [x, y, z] points.
1578 .. method:: setCollisionMargin(margin)
1580 Set the objects collision margin.
1582 :arg margin: the collision margin distance in blender units.
1587 If this object has no physics controller (a physics ID of zero), this function will raise RuntimeError.
1589 .. method:: sendMessage(subject, body="", to="")
1593 :arg subject: The subject of the message
1594 :type subject: string
1595 :arg body: The body of the message (optional)
1597 :arg to: The name of the object to send the message to (optional)
1600 .. method:: reinstancePhysicsMesh(gameObject, meshObject)
1602 Updates the physics system with the changed mesh.
1604 If no arguments are given the physics mesh will be re-created from the first mesh assigned to the game object.
1606 :arg gameObject: optional argument, set the physics shape from this gameObjets mesh.
1607 :type gameObject: string, :class:`KX_GameObject` or None
1608 :arg meshObject: optional argument, set the physics shape from this mesh.
1609 :type meshObject: string, :class:`MeshProxy` or None
1611 :return: True if reinstance succeeded, False if it failed.
1616 If this object has instances the other instances will be updated too.
1620 The gameObject argument has an advantage that it can convert from a mesh with modifiers applied (such as subsurf).
1624 Only triangle mesh type objects are supported currently (not convex hull)
1628 If the object is a part of a combound object it will fail (parent or child)
1632 Rebuilding the physics mesh can be slow, running many times per second will give a performance hit.
1634 .. method:: get(key, default=None)
1636 Return the value matching key, or the default value if its not found.
1637 :return: The key value or a default.
1639 .. method:: playAction(name, start_frame, end_frame, layer=0, priority=0, blendin=0, play_mode=ACT_MODE_PLAY, layer_weight=0.0, ipo_flags=0, speed=1.0)
1643 :arg name: the name of the action
1645 :arg start: the start frame of the action
1647 :arg end: the end frame of the action
1649 :arg layer: the layer the action will play in (actions in different layers are added/blended together)
1650 :type layer: integer
1651 :arg priority: only play this action if there isn't an action currently playing in this layer with a higher (lower number) priority
1652 :type priority: integer
1653 :arg blendin: the amount of blending between this animation and the previous one on this layer
1654 :type blendin: float
1655 :arg play_mode: the play mode
1656 :type play_mode: KX_ACTION_MODE_PLAY, KX_ACTION_MODE_LOOP, or KX_ACTION_MODE_PING_PONG
1657 :arg layer_weight: how much of the previous layer to use for blending (0 = add)
1658 :type layer_weight: float
1659 :arg ipo_flags: flags for the old IPO behaviors (force, etc)
1660 :type ipo_flags: int bitfield
1661 :arg speed: the playback speed of the action as a factor (1.0 = normal speed, 2.0 = 2x speed, etc)
1664 .. method:: stopAction(layer=0)
1666 Stop playing the action on the given layer.
1668 :arg layer: The layer to stop playing.
1669 :type layer: integer
1671 .. method:: getActionFrame(layer=0)
1673 Gets the current frame of the action playing in the supplied layer.
1675 :arg layer: The layer that you want to get the frame from.
1676 :type layer: integer
1678 :return: The current frame of the action
1681 .. method:: setActionFrame(frame, layer=0)
1683 Set the current frame of the action playing in the supplied layer.
1685 :arg layer: The layer where you want to set the frame
1686 :type layer: integer
1687 :arg frame: The frame to set the action to
1690 .. method:: isPlayingAction(layer=0)
1692 Checks to see if there is an action playing in the given layer.
1694 :arg layer: The layer to check for a playing action.
1695 :type layer: integer
1697 :return: Whether or not the action is playing
1700 .. class:: KX_IpoActuator(SCA_IActuator)
1702 IPO actuator activates an animation.
1704 .. attribute:: frameStart
1710 .. attribute:: frameEnd
1716 .. attribute:: propName
1718 Use this property to define the Ipo position.
1722 .. attribute:: framePropName
1724 Assign this property this action current frame number.
1730 Play mode for the ipo. Can be on of :ref:`these constants <ipo-actuator>`
1734 .. attribute:: useIpoAsForce
1736 Apply Ipo as a global or local force depending on the local option (dynamic objects only).
1740 .. attribute:: useIpoAdd
1742 Ipo is added to the current loc/rot/scale in global or local coordinate according to Local flag.
1746 .. attribute:: useIpoLocal
1748 Let the ipo acts in local coordinates, used in Force and Add mode.
1752 .. attribute:: useChildren
1754 Update IPO on all children Objects as well.
1758 .. class:: KX_LightObject(KX_GameObject)
1762 .. code-block:: python
1764 # Turn on a red alert light.
1767 co = bge.logic.getCurrentController()
1771 light.color = [1.0, 0.0, 0.0]
1775 A spot light source. See attribute :data:`type`
1779 A point light source with no attenuation. See attribute :data:`type`
1783 A point light source. See attribute :data:`type`
1787 The type of light - must be SPOT, SUN or NORMAL
1789 .. attribute:: layer
1791 The layer mask that this light affects object on.
1795 .. attribute:: energy
1797 The brightness of this light.
1801 .. attribute:: distance
1803 The maximum distance this light can illuminate. (SPOT and NORMAL lights only).
1807 .. attribute:: color
1809 The color of this light. Black = [0.0, 0.0, 0.0], White = [1.0, 1.0, 1.0].
1811 :type: list [r, g, b]
1813 .. attribute:: colour
1817 .. attribute:: lin_attenuation
1819 The linear component of this light's attenuation. (SPOT and NORMAL lights only).
1823 .. attribute:: quad_attenuation
1825 The quadratic component of this light's attenuation (SPOT and NORMAL lights only).
1829 .. attribute:: spotsize
1831 The cone angle of the spot light, in degrees (SPOT lights only).
1833 :type: float in [0 - 180].
1835 .. attribute:: spotblend
1837 Specifies the intensity distribution of the spot light (SPOT lights only).
1839 :type: float in [0 - 1]
1843 Higher values result in a more focused light source.
1845 .. class:: KX_MeshProxy(SCA_IObject)
1849 You can only change the vertex properties of a mesh object, not the mesh topology.
1851 To use mesh objects effectively, you should know a bit about how the game engine handles them.
1853 #. Mesh Objects are converted from Blender at scene load.
1854 #. The Converter groups polygons by Material. This means they can be sent to the renderer efficiently. A material holds:
1857 #. The Blender material.
1858 #. The Tile properties
1859 #. The face properties - (From the "Texture Face" panel)
1860 #. Transparency & z sorting
1862 #. Polygon shape (triangle/quad)
1865 #. Vertices will be split by face if necessary. Vertices can only be shared between faces if:
1867 #. They are at the same position
1868 #. UV coordinates are the same
1869 #. Their normals are the same (both polygons are "Set Smooth")
1870 #. They are the same color, for example: a cube has 24 vertices: 6 faces with 4 vertices per face.
1872 The correct method of iterating over every :class:`KX_VertexProxy` in a game object
1874 .. code-block:: python
1876 from bge import logic
1878 cont = logic.getCurrentController()
1881 for mesh in object.meshes:
1882 for m_index in range(len(mesh.materials)):
1883 for v_index in range(mesh.getVertexArrayLength(m_index)):
1884 vertex = mesh.getVertex(m_index, v_index)
1885 # Do something with vertex here...
1886 # ... eg: color the vertex red.
1887 vertex.color = [1.0, 0.0, 0.0, 1.0]
1889 .. attribute:: materials
1891 :type: list of :class:`KX_BlenderMaterial` or :class:`KX_PolygonMaterial` types
1893 .. attribute:: numPolygons
1897 .. attribute:: numMaterials
1901 .. method:: getNumMaterials()
1903 :return: number of materials associated with this object
1906 .. method:: getMaterialName(matid)
1908 Gets the name of the specified material.
1910 :arg matid: the specified material.
1911 :type matid: integer
1912 :return: the attached material name.
1915 .. method:: getTextureName(matid)
1917 Gets the name of the specified material's texture.
1919 :arg matid: the specified material
1920 :type matid: integer
1921 :return: the attached material's texture name.
1924 .. method:: getVertexArrayLength(matid)
1926 Gets the length of the vertex array associated with the specified material.
1928 There is one vertex array for each material.
1930 :arg matid: the specified material
1931 :type matid: integer
1932 :return: the number of verticies in the vertex array.
1935 .. method:: getVertex(matid, index)
1937 Gets the specified vertex from the mesh object.
1939 :arg matid: the specified material
1940 :type matid: integer
1941 :arg index: the index into the vertex array.
1942 :type index: integer
1943 :return: a vertex object.
1944 :rtype: :class:`KX_VertexProxy`
1946 .. method:: getNumPolygons()
1948 :return: The number of polygon in the mesh.
1951 .. method:: getPolygon(index)
1953 Gets the specified polygon from the mesh.
1955 :arg index: polygon number
1956 :type index: integer
1957 :return: a polygon object.
1958 :rtype: :class:`PolyProxy`
1960 .. method:: transform(matid, matrix)
1962 Transforms the vertices of a mesh.
1964 :arg matid: material index, -1 transforms all.
1965 :type matid: integer
1966 :arg matrix: transformation matrix.
1967 :type matrix: 4x4 matrix [[float]]
1969 .. method:: transform_uv(matid, matrix, uv_index=-1)
1971 Transforms the vertices UV's of a mesh.
1973 :arg matid: material index, -1 transforms all.
1974 :type matid: integer
1975 :arg matrix: transformation matrix.
1976 :type matrix: 4x4 matrix [[float]]
1977 :arg matid: optional uv index, -1 for all, otherwise 0 or 1.
1978 :type matid: integer
1980 .. class:: SCA_MouseSensor(SCA_ISensor)
1982 Mouse Sensor logic brick.
1984 .. attribute:: position
1986 current [x, y] coordinates of the mouse, in frame coordinates (pixels).
1988 :type: [integer, interger]
1996 * KX_MOUSESENSORMODE_LEFTBUTTON(1)
1997 * KX_MOUSESENSORMODE_MIDDLEBUTTON(2)
1998 * KX_MOUSESENSORMODE_RIGHTBUTTON(3)
1999 * KX_MOUSESENSORMODE_WHEELUP(4)
2000 * KX_MOUSESENSORMODE_WHEELDOWN(5)
2001 * KX_MOUSESENSORMODE_MOVEMENT(6)
2003 .. method:: getButtonStatus(button)
2005 Get the mouse button status.
2007 :arg button: The code that represents the key you want to get the state of, use one of :ref:`these constants<mouse-keys>`
2009 :return: The state of the given key, can be one of :ref:`these constants<input-status>`
2012 .. class:: KX_MouseFocusSensor(SCA_MouseSensor)
2014 The mouse focus sensor detects when the mouse is over the current game object.
2016 The mouse focus sensor works by transforming the mouse coordinates from 2d device
2017 space to 3d space then raycasting away from the camera.
2019 .. attribute:: raySource
2021 The worldspace source of the ray (the view position).
2023 :type: list (vector of 3 floats)
2025 .. attribute:: rayTarget
2027 The worldspace target of the ray.
2029 :type: list (vector of 3 floats)
2031 .. attribute:: rayDirection
2033 The :data:`rayTarget` - :class:`raySource` normalized.
2035 :type: list (normalized vector of 3 floats)
2037 .. attribute:: hitObject
2039 the last object the mouse was over.
2041 :type: :class:`KX_GameObject` or None
2043 .. attribute:: hitPosition
2045 The worldspace position of the ray intersecton.
2047 :type: list (vector of 3 floats)
2049 .. attribute:: hitNormal
2051 the worldspace normal from the face at point of intersection.
2053 :type: list (normalized vector of 3 floats)
2055 .. attribute:: hitUV
2057 the UV coordinates at the point of intersection.
2059 :type: list (vector of 2 floats)
2061 If the object has no UV mapping, it returns [0, 0].
2063 The UV coordinates are not normalized, they can be < 0 or > 1 depending on the UV mapping.
2065 .. attribute:: usePulseFocus
2067 When enabled, moving the mouse over a different object generates a pulse. (only used when the 'Mouse Over Any' sensor option is set).
2071 .. class:: KX_TouchSensor(SCA_ISensor)
2073 Touch sensor detects collisions between objects.
2075 .. attribute:: propName
2077 The property or material to collide with.
2081 .. attribute:: useMaterial
2083 Determines if the sensor is looking for a property or material. KX_True = Find material; KX_False = Find property.
2087 .. attribute:: usePulseCollision
2089 When enabled, changes to the set of colliding objects generate a pulse.
2093 .. attribute:: hitObject
2095 The last collided object. (read-only).
2097 :type: :class:`KX_GameObject` or None
2099 .. attribute:: hitObjectList
2101 A list of colliding objects. (read-only).
2103 :type: :class:`CListValue` of :class:`KX_GameObject`
2105 .. class:: KX_NearSensor(KX_TouchSensor)
2107 A near sensor is a specialised form of touch sensor.
2109 .. attribute:: distance
2111 The near sensor activates when an object is within this distance.
2115 .. attribute:: resetDistance
2117 The near sensor deactivates when the object exceeds this distance.
2121 .. class:: KX_NetworkMessageActuator(SCA_IActuator)
2125 .. attribute:: propName
2127 Messages will only be sent to objects with the given property name.
2131 .. attribute:: subject
2133 The subject field of the message.
2139 The body of the message.
2143 .. attribute:: usePropBody
2145 Send a property instead of a regular body message.
2149 .. class:: KX_NetworkMessageSensor(SCA_ISensor)
2151 The Message Sensor logic brick.
2153 Currently only loopback (local) networks are supported.
2155 .. attribute:: subject
2157 The subject the sensor is looking for.
2161 .. attribute:: frameMessageCount
2163 The number of messages received since the last frame. (read-only).
2167 .. attribute:: subjects
2169 The list of message subjects received. (read-only).
2171 :type: list of strings
2173 .. attribute:: bodies
2175 The list of message bodies received. (read-only).
2177 :type: list of strings
2179 .. class:: KX_ObjectActuator(SCA_IActuator)
2181 The object actuator ("Motion Actuator") applies force, torque, displacement, angular displacement,
2182 velocity, or angular velocity to an object.
2183 Servo control allows to regulate force to achieve a certain speed target.
2185 .. attribute:: force
2187 The force applied by the actuator.
2189 :type: list [x, y, z]
2191 .. attribute:: useLocalForce
2193 A flag specifying if the force is local.
2197 .. attribute:: torque
2199 The torque applied by the actuator.
2201 :type: list [x, y, z]
2203 .. attribute:: useLocalTorque
2205 A flag specifying if the torque is local.
2211 The displacement vector applied by the actuator.
2213 :type: list [x, y, z]
2215 .. attribute:: useLocalDLoc
2217 A flag specifying if the dLoc is local.
2223 The angular displacement vector applied by the actuator
2225 :type: list [x, y, z]
2229 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.
2231 .. attribute:: useLocalDRot
2233 A flag specifying if the dRot is local.
2239 The linear velocity applied by the actuator.
2241 :type: list [x, y, z]
2243 .. attribute:: useLocalLinV
2245 A flag specifying if the linear velocity is local.
2251 This is the target speed for servo controllers.
2255 The angular velocity applied by the actuator.
2257 :type: list [x, y, z]
2259 .. attribute:: useLocalAngV
2261 A flag specifying if the angular velocity is local.
2265 .. attribute:: damping
2267 The damping parameter of the servo controller.
2271 .. attribute:: forceLimitX
2273 The min/max force limit along the X axis and activates or deactivates the limits in the servo controller.
2275 :type: list [min(float), max(float), bool]
2277 .. attribute:: forceLimitY
2279 The min/max force limit along the Y axis and activates or deactivates the limits in the servo controller.
2281 :type: list [min(float), max(float), bool]
2283 .. attribute:: forceLimitZ
2285 The min/max force limit along the Z axis and activates or deactivates the limits in the servo controller.
2287 :type: list [min(float), max(float), bool]
2291 The PID coefficients of the servo controller.
2293 :type: list of floats [proportional, integral, derivate]
2295 .. attribute:: reference
2297 The object that is used as reference to compute the velocity for the servo controller.
2299 :type: :class:`KX_GameObject` or None
2301 .. class:: KX_ParentActuator(SCA_IActuator)
2303 The parent actuator can set or remove an objects parent object.
2305 .. attribute:: object
2307 the object this actuator sets the parent too.
2309 :type: :class:`KX_GameObject` or None
2313 The mode of this actuator.
2315 :type: integer from 0 to 1.
2317 .. attribute:: compound
2319 Whether the object shape should be added to the parent compound shape when parenting.
2321 Effective only if the parent is already a compound shape.
2325 .. attribute:: ghost
2327 Whether the object should be made ghost when parenting
2328 Effective only if the shape is not added to the parent compound shape.
2332 .. class:: KX_PhysicsObjectWrapper(PyObjectPlus)
2334 KX_PhysicsObjectWrapper
2336 .. method:: setActive(active)
2338 Set the object to be active.
2340 :arg active: set to True to be active
2341 :type active: boolean
2343 .. method:: setAngularVelocity(x, y, z, local)
2345 Set the angular velocity of the object.
2347 :arg x: angular velocity for the x-axis
2350 :arg y: angular velocity for the y-axis
2353 :arg z: angular velocity for the z-axis
2356 :arg local: set to True for local axis
2357 :type local: boolean
2359 .. method:: setLinearVelocity(x, y, z, local)
2361 Set the linear velocity of the object.
2363 :arg x: linear velocity for the x-axis
2366 :arg y: linear velocity for the y-axis
2369 :arg z: linear velocity for the z-axis
2372 :arg local: set to True for local axis
2373 :type local: boolean
2375 .. class:: KX_PolyProxy(SCA_IObject)
2377 A polygon holds the index of the vertex forming the poylgon.
2380 The polygon attributes are read-only, you need to retrieve the vertex proxy if you want
2381 to change the vertex settings.
2383 .. attribute:: matname
2385 The name of polygon material, empty if no material.
2389 .. attribute:: material
2391 The material of the polygon.
2393 :type: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial`
2395 .. attribute:: texture
2397 The texture name of the polygon.
2401 .. attribute:: matid
2403 The material index of the polygon, use this to retrieve vertex proxy from mesh proxy.
2409 vertex index of the first vertex of the polygon, use this to retrieve vertex proxy from mesh proxy.
2415 vertex index of the second vertex of the polygon, use this to retrieve vertex proxy from mesh proxy.
2421 vertex index of the third vertex of the polygon, use this to retrieve vertex proxy from mesh proxy.
2427 Vertex index of the fourth vertex of the polygon, 0 if polygon has only 3 vertex
2428 Use this to retrieve vertex proxy from mesh proxy.
2432 .. attribute:: visible
2434 visible state of the polygon: 1=visible, 0=invisible.
2438 .. attribute:: collide
2440 collide state of the polygon: 1=receives collision, 0=collision free.
2444 .. method:: getMaterialName()
2446 Returns the polygon material name with MA prefix
2448 :return: material name
2451 .. method:: getMaterial()
2453 :return: The polygon material
2454 :rtype: :class:`KX_PolygonMaterial` or :class:`KX_BlenderMaterial`
2456 .. method:: getTextureName()
2458 :return: The texture name
2461 .. method:: getMaterialIndex()
2463 Returns the material bucket index of the polygon.
2464 This index and the ones returned by getVertexIndex() are needed to retrieve the vertex proxy from :class:`MeshProxy`.
2466 :return: the material index in the mesh
2469 .. method:: getNumVertex()
2471 Returns the number of vertex of the polygon.
2473 :return: number of vertex, 3 or 4.
2476 .. method:: isVisible()
2478 Returns whether the polygon is visible or not
2480 :return: 0=invisible, 1=visible
2483 .. method:: isCollider()
2485 Returns whether the polygon is receives collision or not
2487 :return: 0=collision free, 1=receives collision
2490 .. method:: getVertexIndex(vertex)
2492 Returns the mesh vertex index of a polygon vertex
2493 This index and the one returned by getMaterialIndex() are needed to retrieve the vertex proxy from :class:`MeshProxy`.
2495 :arg vertex: index of the vertex in the polygon: 0->3
2496 :arg vertex: integer
2497 :return: mesh vertex index
2500 .. method:: getMesh()
2502 Returns a mesh proxy
2505 :rtype: :class:`MeshProxy`
2507 .. class:: KX_PolygonMaterial(PyObjectPlus)
2509 This is the interface to materials in the game engine.
2511 Materials define the render state to be applied to mesh objects.
2515 Some of the methods/variables are CObjects. If you mix these up, you will crash blender.
2517 .. code-block:: python
2519 from bge import logic
2525 // original vertex position, no changes
2526 gl_Position = ftransform();
2527 // coordinate of the 1st texture channel
2528 gl_TexCoord[0] = gl_MultiTexCoord0;
2529 // coordinate of the 2nd texture channel
2530 gl_TexCoord[1] = gl_MultiTexCoord1;
2534 fragment_shader ="""
2536 uniform sampler2D color_0;
2537 uniform sampler2D color_1;
2538 uniform float factor;
2542 vec4 color_0 = texture2D(color_0, gl_TexCoord[0].st);
2543 vec4 color_1 = texture2D(color_1, gl_TexCoord[1].st);
2544 gl_FragColor = mix(color_0, color_1, factor);
2548 object = logic.getCurrentController().owner
2550 for mesh in object.meshes:
2551 for material in mesh.materials:
2552 shader = material.getShader()
2554 if not shader.isValid():
2555 shader.setSource(vertex_shader, fragment_shader, True)
2557 # get the first texture channel of the material
2558 shader.setSampler('color_0', 0)
2559 # get the second texture channel of the material
2560 shader.setSampler('color_1', 1)
2561 # pass another uniform to the shader
2562 shader.setUniform1f('factor', 0.3)
2565 .. attribute:: texture
2569 :type: string (read-only)
2571 .. attribute:: gl_texture
2573 OpenGL texture handle (eg for glBindTexture(GL_TEXTURE_2D, gl_texture).
2575 :type: integer (read-only)
2577 .. attribute:: material
2581 :type: string (read-only)
2583 .. attribute:: tface
2585 Texture face properties.
2587 :type: CObject (read-only)
2595 .. attribute:: tilexrep
2597 Number of tile repetitions in x direction.
2601 .. attribute:: tileyrep
2603 Number of tile repetitions in y direction.
2607 .. attribute:: drawingmode
2609 Drawing mode for the material.
2610 - 2 (drawingmode & 4) Textured
2611 - 4 (drawingmode & 16) Light
2612 - 14 (drawingmode & 16384) 3d Polygon Text.
2616 .. attribute:: transparent
2618 This material is transparent. All meshes with this
2619 material will be rendered after non transparent meshes from back
2624 .. attribute:: zsort
2626 Transparent polygons in meshes with this material will be sorted back to
2627 front before rendering.
2628 Non-Transparent polygons will be sorted front to back before rendering.
2632 .. attribute:: lightlayer
2634 Light layers this material affects.
2638 .. attribute:: triangle
2640 Mesh data with this material is triangles. It's probably not safe to change this.
2644 .. attribute:: diffuse
2646 The diffuse color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0].
2648 :type: list [r, g, b]
2650 .. attribute:: specular
2652 The specular color of the material. black = [0.0, 0.0, 0.0] white = [1.0, 1.0, 1.0].
2654 :type: list [r, g, b]
2656 .. attribute:: shininess
2658 The shininess (specular exponent) of the material. 0.0 <= shininess <= 128.0.
2662 .. attribute:: specularity
2664 The amount of specular of the material. 0.0 <= specularity <= 1.0.
2668 .. method:: updateTexture(tface, rasty)
2670 Updates a realtime animation.
2672 :arg tface: Texture face (eg mat.tface)
2673 :type tface: CObject
2674 :arg rasty: Rasterizer
2675 :type rasty: CObject
2677 .. method:: setTexture(tface)
2679 Sets texture render state.
2681 :arg tface: Texture face
2682 :type tface: CObject
2684 .. code-block:: python
2686 mat.setTexture(mat.tface)
2688 .. method:: activate(rasty, cachingInfo)
2690 Sets material parameters for this object for rendering.
2692 Material Parameters set:
2702 :arg rasty: Rasterizer instance.
2703 :type rasty: CObject
2704 :arg cachingInfo: Material cache instance.
2705 :type cachingInfo: CObject
2707 .. method:: setCustomMaterial(material)
2709 Sets the material state setup object.
2711 Using this method, you can extend or completely replace the gameengine material
2712 to do your own advanced multipass effects.
2714 Use this method to register your material class. Instead of the normal material,
2715 your class's activate method will be called just before rendering the mesh.
2716 This should setup the texture, material, and any other state you would like.
2717 It should return True to render the mesh, or False if you are finished. You should
2718 clean up any state Blender does not set before returning False.
2720 Activate Method Definition:
2722 .. code-block:: python
2724 def activate(self, rasty, cachingInfo, material):
2726 :arg material: The material object.
2727 :type material: instance
2729 .. code-block:: python
2735 def activate(self, rasty, cachingInfo, material):
2736 # Activate the material here.
2738 # The activate method will be called until it returns False.
2739 # Every time the activate method returns True the mesh will
2742 # rasty is a CObject for passing to material.updateTexture()
2743 # and material.activate()
2744 # cachingInfo is a CObject for passing to material.activate()
2745 # material is the KX_PolygonMaterial instance this material
2748 # default material properties:
2750 if self.pass_no == 0:
2751 material.activate(rasty, cachingInfo)
2752 # Return True to do this pass
2755 # clean up and return False to finish.
2759 # Create a new Python Material and pass it to the renderer.
2760 mat.setCustomMaterial(PyMaterial())
2762 .. class:: KX_RadarSensor(KX_NearSensor)
2764 Radar sensor is a near sensor with a conical sensor object.
2766 .. attribute:: coneOrigin
2768 The origin of the cone with which to test. The origin is in the middle of the cone. (read-only).
2770 :type: list of floats [x, y, z]
2772 .. attribute:: coneTarget
2774 The center of the bottom face of the cone with which to test. (read-only).
2776 :type: list of floats [x, y, z]
2778 .. attribute:: distance
2780 The height of the cone with which to test.
2784 .. attribute:: angle
2786 The angle of the cone (in degrees) with which to test.
2792 The axis on which the radar cone is cast.
2794 :type: integer from 0 to 5
2796 KX_RADAR_AXIS_POS_X, KX_RADAR_AXIS_POS_Y, KX_RADAR_AXIS_POS_Z,
2797 KX_RADAR_AXIS_NEG_X, KX_RADAR_AXIS_NEG_Y, KX_RADAR_AXIS_NEG_Z
2799 .. class:: KX_RaySensor(SCA_ISensor)
2801 A ray sensor detects the first object in a given direction.
2803 .. attribute:: propName
2805 The property the ray is looking for.
2809 .. attribute:: range
2811 The distance of the ray.
2815 .. attribute:: useMaterial
2817 Whether or not to look for a material (false = property).
2821 .. attribute:: useXRay
2823 Whether or not to use XRay.
2827 .. attribute:: hitObject
2829 The game object that was hit by the ray. (read-only).
2831 :type: :class:`KX_GameObject`
2833 .. attribute:: hitPosition
2835 The position (in worldcoordinates) where the object was hit by the ray. (read-only).
2837 :type: list [x, y, z]
2839 .. attribute:: hitNormal
2841 The normal (in worldcoordinates) of the object at the location where the object was hit by the ray. (read-only).
2843 :type: list [x, y, z]
2845 .. attribute:: rayDirection
2847 The direction from the ray (in worldcoordinates). (read-only).
2849 :type: list [x, y, z]
2853 The axis the ray is pointing on.
2855 :type: integer from 0 to 5
2864 .. class:: KX_SCA_AddObjectActuator(SCA_IActuator)
2866 Edit Object Actuator (in Add Object Mode)
2870 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.
2872 .. code-block:: none
2874 Error: GameObject 'Name' has a AddObjectActuator 'ActuatorName' without object (in 'nonactive' layer)
2876 .. attribute:: object
2878 the object this actuator adds.
2880 :type: :class:`KX_GameObject` or None
2882 .. attribute:: objectLastCreated
2884 the last added object from this actuator (read-only).
2886 :type: :class:`KX_GameObject` or None
2890 the lifetime of added objects, in frames. Set to 0 to disable automatic deletion.
2894 .. attribute:: linearVelocity
2896 the initial linear velocity of added objects.
2898 :type: list [vx, vy, vz]
2900 .. attribute:: angularVelocity
2902 the initial angular velocity of added objects.
2904 :type: list [vx, vy, vz]
2906 .. method:: instantAddObject()
2908 adds the object without needing to calling SCA_PythonController.activate()
2910 .. note:: Use objectLastCreated to get the newly created object.
2912 .. class:: KX_SCA_DynamicActuator(SCA_IActuator)
2920 the type of operation of the actuator, 0-4
2922 * KX_DYN_RESTORE_DYNAMICS(0)
2923 * KX_DYN_DISABLE_DYNAMICS(1)
2924 * KX_DYN_ENABLE_RIGID_BODY(2)
2925 * KX_DYN_DISABLE_RIGID_BODY(3)
2926 * KX_DYN_SET_MASS(4)
2930 the mass value for the KX_DYN_SET_MASS operation.
2934 .. class:: KX_SCA_EndObjectActuator(SCA_IActuator)
2936 Edit Object Actuator (in End Object mode)
2938 This actuator has no python methods.
2940 .. class:: KX_SCA_ReplaceMeshActuator(SCA_IActuator)
2942 Edit Object actuator, in Replace Mesh mode.
2946 Replace mesh actuators will be ignored if at game start, the named mesh doesn't exist.
2948 This will generate a warning in the console
2950 .. code-block:: none
2952 Error: GameObject 'Name' ReplaceMeshActuator 'ActuatorName' without object
2954 .. code-block:: python
2957 # Switch a game object's mesh based on its depth in the camera view.
2958 # +----------+ +-----------+ +-------------------------------------+
2959 # | Always +-----+ Python +-----+ Edit Object (Replace Mesh) LOD.Mesh |
2960 # +----------+ +-----------+ +-------------------------------------+
2961 from bge import logic
2963 # List detail meshes here
2964 # Mesh (name, near, far)
2965 # Meshes overlap so that they don't 'pop' when on the edge of the distance.
2966 meshes = ((".Hi", 0.0, -20.0),
2967 (".Med", -15.0, -50.0),
2968 (".Lo", -40.0, -100.0)
2971 cont = logic.getCurrentController()
2973 actuator = cont.actuators["LOD." + obj.name]
2974 camera = logic.getCurrentScene().active_camera
2976 def Depth(pos, plane):
2977 return pos[0]*plane[0] + pos[1]*plane[1] + pos[2]*plane[2] + plane[3]
2979 # Depth is negative and decreasing further from the camera
2980 depth = Depth(object.position, camera.world_to_camera[2])
2984 # Find the lowest detail mesh for depth
2986 if depth < mesh[1] and depth > mesh[2]:
2988 if "ME" + object.name + mesh[0] == actuator.getMesh():
2991 if newmesh != None and "ME" + object.name + newmesh[0] != actuator.mesh:
2992 # The mesh is a different mesh - switch it.
2993 # Check the current mesh is not a better fit.
2994 if curmesh == None or curmesh[1] < depth or curmesh[2] > depth:
2995 actuator.mesh = object.name + newmesh[0]
2996 cont.activate(actuator)
3000 :class:`MeshProxy` or the name of the mesh that will replace the current one.
3002 Set to None to disable actuator.
3004 :type: :class:`MeshProxy` or None if no mesh is set
3006 .. attribute:: useDisplayMesh
3008 when true the displayed mesh is replaced.
3012 .. attribute:: usePhysicsMesh
3014 when true the physics mesh is replaced.
3018 .. method:: instantReplaceMesh()
3020 Immediately replace mesh without delay.
3022 .. class:: KX_Scene(PyObjectPlus)
3024 An active scene that gives access to objects, cameras, lights and scene attributes.
3026 The activity culling stuff is supposed to disable logic bricks when their owner gets too far
3027 from the active camera. It was taken from some code lurking at the back of KX_Scene - who knows
3030 .. code-block:: python
3032 from bge import logic
3035 scene = logic.getCurrentScene()
3037 # print all the objects in the scene
3038 for object in scene.objects:
3041 # get an object named 'Cube'
3042 object = scene.objects["Cube"]
3044 # get the first object in the scene.
3045 object = scene.objects[0]
3047 .. code-block:: python
3049 # Get the depth of an object in the camera view.
3050 from bge import logic
3052 object = logic.getCurrentController().owner
3053 cam = logic.getCurrentScene().active_camera
3055 # Depth is negative and decreasing further from the camera
3056 depth = object.position[0]*cam.world_to_camera[2][0] + object.position[1]*cam.world_to_camera[2][1] + object.position[2]*cam.world_to_camera[2][2] + cam.world_to_camera[2][3]
3058 @bug: All attributes are read only at the moment.
3062 The scene's name, (read-only).
3066 .. attribute:: objects
3068 A list of objects in the scene, (read-only).
3070 :type: :class:`CListValue` of :class:`KX_GameObject`
3072 .. attribute:: objectsInactive
3074 A list of objects on background layers (used for the addObject actuator), (read-only).
3076 :type: :class:`CListValue` of :class:`KX_GameObject`
3078 .. attribute:: lights
3080 A list of lights in the scene, (read-only).
3082 :type: :class:`CListValue` of :class:`KX_LightObject`
3084 .. attribute:: cameras
3086 A list of cameras in the scene, (read-only).
3088 :type: :class:`CListValue` of :class:`KX_Camera`
3090 .. attribute:: active_camera
3092 The current active camera.
3094 :type: :class:`KX_Camera`
3098 This can be set directly from python to avoid using the :class:`KX_SceneActuator`.
3100 .. attribute:: suspended
3102 True if the scene is suspended, (read-only).
3106 .. attribute:: activity_culling
3108 True if the scene is activity culling.
3112 .. attribute:: activity_culling_radius
3114 The distance outside which to do activity culling. Measured in manhattan distance.
3118 .. attribute:: dbvt_culling
3120 True when Dynamic Bounding box Volume Tree is set (read-only).
3124 .. attribute:: pre_draw
3126 A list of callables to be run before the render step.
3130 .. attribute:: post_draw
3132 A list of callables to be run after the render step.
3136 .. attribute:: gravity
3138 The scene gravity using the world x, y and z axis.
3140 :type: list [fx, fy, fz]
3142 .. method:: addObject(object, other, time=0)
3144 Adds an object to the scene like the Add Object Actuator would.
3146 :arg object: The object to add
3147 :type object: :class:`KX_GameObject` or string
3148 :arg other: The object's center to use when adding the object
3149 :type other: :class:`KX_GameObject` or string
3150 :arg time: The lifetime of the added object, in frames. A time of 0 means the object will last forever.
3152 :return: The newly added object.
3153 :rtype: :class:`KX_GameObject`
3157 Removes the scene from the game.
3159 .. method:: restart()
3163 .. method:: replace(scene)
3165 Replaces this scene with another one.
3167 :arg scene: The name of the scene to replace this scene with.
3170 .. method:: suspend()
3172 Suspends this scene.
3174 .. method:: resume()
3178 .. method:: get(key, default=None)
3180 Return the value matching key, or the default value if its not found.
3181 :return: The key value or a default.
3183 .. class:: KX_SceneActuator(SCA_IActuator)
3185 Scene Actuator logic brick.
3189 Scene actuators that use a scene name will be ignored if at game start, the named scene doesn't exist or is empty
3191 This will generate a warning in the console:
3193 .. code-block:: none
3195 Error: GameObject 'Name' has a SceneActuator 'ActuatorName' (SetScene) without scene
3197 .. attribute:: scene
3199 the name of the scene to change to/overlay/underlay/remove/suspend/resume.
3203 .. attribute:: camera
3205 the camera to change to.
3207 :type: :class:`KX_Camera` on read, string or :class:`KX_Camera` on write
3211 When setting the attribute, you can use either a :class:`KX_Camera` or the name of the camera.
3213 .. attribute:: useRestart
3215 Set flag to True to restart the sene.
3221 The mode of the actuator.
3223 :type: integer from 0 to 5.
3225 .. class:: KX_SoundActuator(SCA_IActuator)
3229 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.
3231 .. attribute:: fileName
3233 The filename of the sound this actuator plays.
3237 .. attribute:: volume
3239 The volume (gain) of the sound.
3243 .. attribute:: pitch
3245 The pitch of the sound.
3249 .. attribute:: rollOffFactor
3251 The roll off factor. Rolloff defines the rate of attenuation as the sound gets further away.
3255 .. attribute:: looping
3257 The loop mode of the actuator.
3261 .. attribute:: position
3263 The position of the sound as a list: [x, y, z].
3267 .. attribute:: velocity
3269 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].
3273 .. attribute:: orientation
3275 The orientation of the sound. When setting the orientation you can also use quaternion [float, float, float, float] or euler angles [float, float, float].
3277 :type: 3x3 matrix [[float]]
3281 The operation mode of the actuator. Can be one of :ref:`these constants<logic-sound-actuator>`
3285 .. class:: KX_StateActuator(SCA_IActuator)
3287 State actuator changes the state mask of parent object.
3289 .. attribute:: operation
3291 Type of bit operation to be applied on object state mask.
3293 You can use one of :ref:`these constants <state-actuator-operation>`
3299 Value that defines the bits that will be modified by the operation.
3301 The bits that are 1 in the mask will be updated in the object state.
3303 The bits that are 0 are will be left unmodified expect for the Copy operation which copies the mask to the object state.
3307 .. class:: KX_TrackToActuator(SCA_IActuator)
3309 Edit Object actuator in Track To mode.
3313 Track To Actuators will be ignored if at game start, the object to track to is invalid.
3315 This will generate a warning in the console:
3317 .. code-block:: none
3319 GameObject 'Name' no object in EditObjectActuator 'ActuatorName'
3321 .. attribute:: object
3323 the object this actuator tracks.
3325 :type: :class:`KX_GameObject` or None
3329 the time in frames with which to delay the tracking motion.
3333 .. attribute:: use3D
3335 the tracking motion to use 3D.
3339 .. class:: KX_VehicleWrapper(PyObjectPlus)
3345 .. method:: addWheel(wheel, attachPos, attachDir, axleDir, suspensionRestLength, wheelRadius, hasSteering)
3347 Add a wheel to the vehicle
3349 :arg wheel: The object to use as a wheel.
3350 :type wheel: :class:`KX_GameObject` or a KX_GameObject name
3351 :arg attachPos: The position that this wheel will attach to.
3352 :type attachPos: vector of 3 floats
3353 :arg attachDir: The direction this wheel points.
3354 :type attachDir: vector of 3 floats
3355 :arg axleDir: The direction of this wheels axle.
3356 :type axleDir: vector of 3 floats
3357 :arg suspensionRestLength: TODO - Description
3358 :type suspensionRestLength: float
3359 :arg wheelRadius: The size of the wheel.
3360 :type wheelRadius: float
3362 .. method:: applyBraking(force, wheelIndex)
3364 Apply a braking force to the specified wheel
3366 :arg force: the brake force
3369 :arg wheelIndex: index of the wheel where the force needs to be applied
3370 :type wheelIndex: integer
3372 .. method:: applyEngineForce(force, wheelIndex)
3374 Apply an engine force to the specified wheel
3376 :arg force: the engine force
3379 :arg wheelIndex: index of the wheel where the force needs to be applied
3380 :type wheelIndex: integer
3382 .. method:: getConstraintId()
3384 Get the constraint ID
3386 :return: the constraint id
3389 .. method:: getConstraintType()
3391 Returns the constraint type.
3393 :return: constraint type
3396 .. method:: getNumWheels()
3398 Returns the number of wheels.
3400 :return: the number of wheels for this vehicle
3403 .. method:: getWheelOrientationQuaternion(wheelIndex)
3405 Returns the wheel orientation as a quaternion.
3407 :arg wheelIndex: the wheel index
3408 :type wheelIndex: integer
3410 :return: TODO Description
3411 :rtype: TODO - type should be quat as per method name but from the code it looks like a matrix
3413 .. method:: getWheelPosition(wheelIndex)
3415 Returns the position of the specified wheel
3417 :arg wheelIndex: the wheel index
3418 :type wheelIndex: integer
3419 :return: position vector
3420 :rtype: list[x, y, z]
3422 .. method:: getWheelRotation(wheelIndex)
3424 Returns the rotation of the specified wheel
3426 :arg wheelIndex: the wheel index
3427 :type wheelIndex: integer
3429 :return: the wheel rotation
3432 .. method:: setRollInfluence(rollInfluece, wheelIndex)
3434 Set the specified wheel's roll influence.
3435 The higher the roll influence the more the vehicle will tend to roll over in corners.
3437 :arg rollInfluece: the wheel roll influence
3438 :type rollInfluece: float
3440 :arg wheelIndex: the wheel index
3441 :type wheelIndex: integer
3443 .. method:: setSteeringValue(steering, wheelIndex)
3445 Set the specified wheel's steering
3447 :arg steering: the wheel steering
3448 :type steering: float
3450 :arg wheelIndex: the wheel index
3451 :type wheelIndex: integer
3453 .. method:: setSuspensionCompression(compression, wheelIndex)
3455 Set the specified wheel's compression
3457 :arg compression: the wheel compression
3458 :type compression: float
3460 :arg wheelIndex: the wheel index
3461 :type wheelIndex: integer
3463 .. method:: setSuspensionDamping(damping, wheelIndex)
3465 Set the specified wheel's damping
3467 :arg damping: the wheel damping
3468 :type damping: float
3470 :arg wheelIndex: the wheel index
3471 :type wheelIndex: integer
3473 .. method:: setSuspensionStiffness(stiffness, wheelIndex)
3475 Set the specified wheel's stiffness
3477 :arg stiffness: the wheel stiffness
3478 :type stiffness: float
3480 :arg wheelIndex: the wheel index
3481 :type wheelIndex: integer
3483 .. method:: setTyreFriction(friction, wheelIndex)
3485 Set the specified wheel's tyre friction
3487 :arg friction: the tyre friction
3488 :type friction: float
3490 :arg wheelIndex: the wheel index
3491 :type wheelIndex: integer
3493 .. class:: KX_CharacterWrapper(PyObjectPlus)
3495 A wrapper to expose character physics options.
3497 .. attribute:: onGround
3499 Whether or not the character is on the ground. (read-only)
3503 .. attribute:: gravity
3505 The gravity value used for the character.
3511 The character jumps based on it's jump speed.
3513 .. class:: KX_VertexProxy(SCA_IObject)
3515 A vertex holds position, UV, color and normal information.
3518 The physics simulation is NOT currently updated - physics will not respond
3519 to changes in the vertex position.
3523 The position of the vertex.
3525 :type: list [x, y, z]
3529 The texture coordinates of the vertex.
3533 .. attribute:: normal
3535 The normal of the vertex.
3537 :type: list [nx, ny, nz]
3539 .. attribute:: color
3541 The color of the vertex.
3543 :type: list [r, g, b, a]
3545 Black = [0.0, 0.0, 0.0, 1.0], White = [1.0, 1.0, 1.0, 1.0]
3547 .. attribute:: colour
3553 The x coordinate of the vertex.
3559 The y coordinate of the vertex.
3565 The z coordinate of the vertex.
3571 The u texture coordinate of the vertex.
3577 The v texture coordinate of the vertex.
3583 The second u texture coordinate of the vertex.
3589 The second v texture coordinate of the vertex.
3595 The red component of the vertex color. 0.0 <= r <= 1.0.
3601 The green component of the vertex color. 0.0 <= g <= 1.0.
3607 The blue component of the vertex color. 0.0 <= b <= 1.0.
3613 The alpha component of the vertex color. 0.0 <= a <= 1.0.
3617 .. method:: getXYZ()
3619 Gets the position of this vertex.
3621 :return: this vertexes position in local coordinates.
3622 :rtype: list [x, y, z]
3624 .. method:: setXYZ(pos)
3626 Sets the position of this vertex.
3628 :type: list [x, y, z]
3630 :arg pos: the new position for this vertex in local coordinates.
3634 Gets the UV (texture) coordinates of this vertex.
3636 :return: this vertexes UV (texture) coordinates.
3639 .. method:: setUV(uv)
3641 Sets the UV (texture) coordinates of this vertex.
3645 .. method:: getUV2()
3647 Gets the 2nd UV (texture) coordinates of this vertex.
3649 :return: this vertexes UV (texture) coordinates.
3652 .. method:: setUV2(uv, unit)
3654 Sets the 2nd UV (texture) coordinates of this vertex.
3658 :arg unit: optional argument, FLAT==1, SECOND_UV==2, defaults to SECOND_UV
3661 .. method:: getRGBA()
3663 Gets the color of this vertex.
3665 The color is represented as four bytes packed into an integer value. The color is
3668 Since Python offers no way to get each byte without shifting, you must use the struct module to
3669 access color in an machine independent way.
3671 Because of this, it is suggested you use the r, g, b and a attributes or the color attribute instead.
3673 .. code-block:: python
3676 col = struct.unpack('4B', struct.pack('I', v.getRGBA()))
3677 # col = (r, g, b, a)
3678 # black = ( 0, 0, 0, 255)
3679 # white = (255, 255, 255, 255)
3681 :return: packed color. 4 byte integer with one byte per color channel in RGBA format.
3684 .. method:: setRGBA(col)
3686 Sets the color of this vertex.
3688 See getRGBA() for the format of col, and its relevant problems. Use the r, g, b and a attributes
3689 or the color attribute instead.
3691 setRGBA() also accepts a four component list as argument col. The list represents the color as [r, g, b, a]
3692 with black = [0.0, 0.0, 0.0, 1.0] and white = [1.0, 1.0, 1.0, 1.0]
3694 .. code-block:: python
3696 v.setRGBA(0xff0000ff) # Red
3697 v.setRGBA(0xff00ff00) # Green on little endian, transparent purple on big endian
3698 v.setRGBA([1.0, 0.0, 0.0, 1.0]) # Red
3699 v.setRGBA([0.0, 1.0, 0.0, 1.0]) # Green on all platforms.
3701 :arg col: the new color of this vertex in packed RGBA format.
3702 :type col: integer or list [r, g, b, a]
3704 .. method:: getNormal()
3706 Gets the normal vector of this vertex.
3708 :return: normalized normal vector.
3709 :rtype: list [nx, ny, nz]
3711 .. method:: setNormal(normal)
3713 Sets the normal vector of this vertex.
3715 :type: sequence of floats [r, g, b]
3717 :arg normal: the new normal of this vertex.
3719 .. class:: KX_VisibilityActuator(SCA_IActuator)
3721 Visibility Actuator.
3723 .. attribute:: visibility
3725 whether the actuator makes its parent object visible or invisible.
3729 .. attribute:: useOcclusion
3731 whether the actuator makes its parent object an occluder or not.
3735 .. attribute:: useRecursion
3737 whether the visibility/occlusion should be propagated to all children of the object.
3741 .. class:: SCA_2DFilterActuator(SCA_IActuator)
3743 Create, enable and disable 2D filters
3745 The following properties don't have an immediate effect.
3746 You must active the actuator to get the result.
3747 The actuator is not persistent: it automatically stops itself after setting up the filter
3748 but the filter remains active. To stop a filter you must activate the actuator with 'type'
3749 set to :data:`~bge.logic.RAS_2DFILTER_DISABLED` or :data:`~bge.logic.RAS_2DFILTER_NOFILTER`.
3751 .. attribute:: shaderText
3753 shader source code for custom shader.
3757 .. attribute:: disableMotionBlur
3759 action on motion blur: 0=enable, 1=disable.
3765 Type of 2D filter, use one of :ref:`these constants <Two-D-FilterActuator-mode>`
3769 .. attribute:: passNumber
3771 order number of filter in the stack of 2D filters. Filters are executed in increasing order of passNb.
3773 Only be one filter can be defined per passNb.
3775 :type: integer (0-100)
3777 .. attribute:: value
3779 argument for motion blur filter.
3781 :type: float (0.0-100.0)
3783 .. class:: SCA_ANDController(SCA_IController)
3785 An AND controller activates only when all linked sensors are activated.
3787 There are no special python methods for this controller.
3789 .. class:: SCA_ActuatorSensor(SCA_ISensor)
3791 Actuator sensor detect change in actuator state of the parent object.
3792 It generates a positive pulse if the corresponding actuator is activated
3793 and a negative pulse if the actuator is deactivated.
3795 .. attribute:: actuator
3797 the name of the actuator that the sensor is monitoring.
3801 .. class:: SCA_AlwaysSensor(SCA_ISensor)
3803 This sensor is always activated.
3805 .. class:: SCA_DelaySensor(SCA_ISensor)
3807 The Delay sensor generates positive and negative triggers at precise time,
3808 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.
3810 The duration parameter defines the length of the ON period following the OFF period.
3811 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.
3813 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).
3815 Use :class:`SCA_ISensor.reset` at any time to restart sensor.
3817 .. attribute:: delay
3819 length of the initial OFF period as number of frame, 0 for immediate trigger.
3823 .. attribute:: duration
3825 length of the ON period in number of frame after the initial OFF period.
3827 If duration is greater than 0, a negative trigger is sent at the end of the ON pulse.
3831 .. attribute:: repeat
3833 1 if the OFF-ON cycle should be repeated indefinately, 0 if it should run once.
3837 .. class:: SCA_JoystickSensor(SCA_ISensor)
3839 This sensor detects player joystick events.
3841 .. attribute:: axisValues
3843 The state of the joysticks axis as a list of values :data:`numAxis` long. (read-only).
3845 :type: list of ints.
3847 Each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing.
3848 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.
3850 * left:[-32767, 0, ...]
3851 * right:[32767, 0, ...]
3852 * up:[0, -32767, ...]
3853 * down:[0, 32767, ...]
3855 .. attribute:: axisSingle
3857 like :data:`axisValues` but returns a single axis value that is set by the sensor. (read-only).
3863 Only use this for "Single Axis" type sensors otherwise it will raise an error.
3865 .. attribute:: hatValues
3867 The state of the joysticks hats as a list of values :data:`numHats` long. (read-only).
3871 Each spesifying the direction of the hat from 1 to 12, 0 when inactive.
3873 Hat directions are as follows...
3885 .. attribute:: hatSingle
3887 Like :data:`hatValues` but returns a single hat direction value that is set by the sensor. (read-only).
3891 .. attribute:: numAxis
3893 The number of axes for the joystick at this index. (read-only).
3897 .. attribute:: numButtons
3899 The number of buttons for the joystick at this index. (read-only).
3903 .. attribute:: numHats
3905 The number of hats for the joystick at this index. (read-only).
3909 .. attribute:: connected
3911 True if a joystick is connected at this joysticks index. (read-only).
3915 .. attribute:: index
3917 The joystick index to use (from 0 to 7). The first joystick is always 0.
3921 .. attribute:: threshold
3923 Axis threshold. Joystick axis motion below this threshold wont trigger an event. Use values between (0 and 32767), lower values are more sensitive.
3927 .. attribute:: button
3929 The button index the sensor reacts to (first button = 0). When the "All Events" toggle is set, this option has no effect.