8d6996dc4017fbb42f52b690f4c1a6efb80d02fc
[blender.git] / doc / python_api / rst / bge_types / bge.types.KX_GameObject.rst
1 KX_GameObject(SCA_IObject)
2 ==========================
3
4 .. module:: bge.types
5
6 base class --- :class:`SCA_IObject`
7
8 .. class:: KX_GameObject(SCA_IObject)
9
10    All game objects are derived from this class.
11
12    Properties assigned to game objects are accessible as attributes of this class.
13
14    .. note::
15
16       Calling ANY method or attribute on an object that has been removed from a scene will raise a SystemError,
17       if an object may have been removed since last accessing it use the :data:`invalid` attribute to check.
18
19    KX_GameObject can be subclassed to extend functionality. For example:
20
21    .. code-block:: python
22
23         import bge
24
25         class CustomGameObject(bge.types.KX_GameObject):
26             RATE = 0.05
27
28             def __init__(self, old_owner):
29                 # "old_owner" can just be ignored. At this point, "self" is
30                 # already the object in the scene, and "old_owner" has been
31                 # destroyed.
32
33                 # New attributes can be defined - but we could also use a game
34                 # property, like "self['rate']".
35                 self.rate = CustomGameObject.RATE
36
37             def update(self):
38                 self.worldPosition.z += self.rate
39
40                 # switch direction
41                 if self.worldPosition.z > 1.0:
42                     self.rate = -CustomGameObject.RATE
43                 elif self.worldPosition.z < 0.0:
44                     self.rate = CustomGameObject.RATE
45
46         # Called first
47         def mutate(cont):
48             old_object = cont.owner
49             mutated_object = CustomGameObject(cont.owner)
50
51             # After calling the constructor above, references to the old object
52             # should not be used.
53             assert(old_object is not mutated_object)
54             assert(old_object.invalid)
55             assert(mutated_object is cont.owner)
56
57         # Called later - note we are now working with the mutated object.
58         def update(cont):
59             cont.owner.update()
60
61    When subclassing objects other than empties and meshes, the specific type
62    should be used - e.g. inherit from :class:`BL_ArmatureObject` when the object
63    to mutate is an armature.
64
65    .. attribute:: name
66
67       The object's name. (read-only).
68
69       :type: string
70
71    .. attribute:: mass
72
73       The object's mass
74
75       :type: float
76
77       .. note::
78
79          The object must have a physics controller for the mass to be applied, otherwise the mass value will be returned as 0.0.
80
81    .. attribute:: linearDamping
82
83       The object's linear damping, also known as translational damping. Can be set simultaneously with angular damping using the :py:meth:`setDamping` method.
84
85       :type: float between 0 and 1 inclusive.
86
87       .. note::
88
89          The object must have a physics controller for the linear damping to be applied, otherwise the value will be returned as 0.0.
90
91    .. attribute:: angularDamping
92
93       The object's angular damping, also known as rotationation damping. Can be set simultaneously with linear damping using the :py:meth:`setDamping` method.
94
95       :type: float between 0 and 1 inclusive.
96
97       .. note::
98
99          The object must have a physics controller for the angular damping to be applied, otherwise the value will be returned as 0.0.
100
101
102    .. attribute:: linVelocityMin
103
104       Enforces the object keeps moving at a minimum velocity.
105
106       :type: float
107
108       .. note::
109
110          Applies to dynamic and rigid body objects only.
111
112       .. note::
113
114          A value of 0.0 disables this option.
115
116       .. note::
117
118          While objects are stationary the minimum velocity will not be applied.
119
120    .. attribute:: linVelocityMax
121
122       Clamp the maximum linear velocity to prevent objects moving beyond a set speed.
123
124       :type: float
125
126       .. note::
127
128          Applies to dynamic and rigid body objects only.
129
130       .. note::
131
132          A value of 0.0 disables this option (rather then setting it stationary).
133
134    .. attribute:: localInertia
135
136       the object's inertia vector in local coordinates. Read only.
137
138       :type: Vector((ix, iy, iz))
139
140    .. attribute:: parent
141
142       The object's parent object. (read-only).
143
144       :type: :class:`KX_GameObject` or None
145
146    .. attribute:: groupMembers
147
148       Returns the list of group members if the object is a group object (dupli group instance), otherwise None is returned.
149
150       :type: :class:`CListValue` of :class:`KX_GameObject` or None
151
152    .. attribute:: groupObject
153
154       Returns the group object (dupli group instance) that the object belongs to or None if the object is not part of a group.
155
156       :type: :class:`KX_GameObject` or None
157
158    .. attribute:: collisionCallbacks
159
160       A list of functions to be called when a collision occurs.
161
162       :type: list of functions and/or methods
163
164       Callbacks should either accept one argument `(object)`, or three
165       arguments `(object, point, normal)`. For simplicity, per
166       colliding object only the first collision point is reported.
167
168       .. code-block:: python
169
170         # Function form
171         def callback_three(object, point, normal):
172             print('Hit by %r at %s with normal %s' % (object.name, point, normal))
173
174         def callback_one(object):
175             print('Hit by %r' % object.name)
176
177         def register_callback(controller):
178             controller.owner.collisionCallbacks.append(callback_three)
179             controller.owner.collisionCallbacks.append(callback_one)
180
181
182         # Method form
183         class YourGameEntity(bge.types.KX_GameObject):
184             def __init__(self, old_owner):
185                 self.collisionCallbacks.append(self.on_collision_three)
186                 self.collisionCallbacks.append(self.on_collision_one)
187
188             def on_collision_three(self, object, point, normal):
189                 print('Hit by %r at %s with normal %s' % (object.name, point, normal))
190
191             def on_collision_one(self, object):
192                 print('Hit by %r' % object.name)
193
194       .. note::
195         For backward compatibility, a callback with variable number of
196         arguments (using `*args`) will be passed only the `object`
197         argument. Only when there is more than one fixed argument (not
198         counting `self` for methods) will the three-argument form be
199         used.
200
201    .. attribute:: scene
202
203       The object's scene. (read-only).
204
205       :type: :class:`KX_Scene` or None
206
207    .. attribute:: visible
208
209       visibility flag.
210
211       :type: boolean
212
213       .. note::
214
215          Game logic will still run for invisible objects.
216
217    .. attribute:: record_animation
218
219       Record animation for this object.
220
221       :type: boolean
222
223    .. attribute:: color
224
225       The object color of the object. [r, g, b, a]
226
227       :type: :class:`mathutils.Vector`
228
229    .. attribute:: occlusion
230
231       occlusion capability flag.
232
233       :type: boolean
234
235    .. attribute:: position
236
237       The object's position. [x, y, z] On write: local position, on read: world position
238
239       .. deprecated:: use :data:`localPosition` and :data:`worldPosition`.
240
241       :type: :class:`mathutils.Vector`
242
243    .. attribute:: orientation
244
245       The object's orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector. On write: local orientation, on read: world orientation
246
247       .. deprecated:: use :data:`localOrientation` and :data:`worldOrientation`.
248
249       :type: :class:`mathutils.Matrix`
250
251    .. attribute:: scaling
252
253       The object's scaling factor. [sx, sy, sz] On write: local scaling, on read: world scaling
254
255       .. deprecated:: use :data:`localScale` and :data:`worldScale`.
256
257       :type: :class:`mathutils.Vector`
258
259    .. attribute:: localOrientation
260
261       The object's local orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.
262
263       :type: :class:`mathutils.Matrix`
264
265    .. attribute:: worldOrientation
266
267       The object's world orientation. 3x3 Matrix.
268
269       :type: :class:`mathutils.Matrix`
270
271    .. attribute:: localScale
272
273       The object's local scaling factor. [sx, sy, sz]
274
275       :type: :class:`mathutils.Vector`
276
277    .. attribute:: worldScale
278
279       The object's world scaling factor. [sx, sy, sz]
280
281       :type: :class:`mathutils.Vector`
282
283    .. attribute:: localPosition
284
285       The object's local position. [x, y, z]
286
287       :type: :class:`mathutils.Vector`
288
289    .. attribute:: worldPosition
290
291       The object's world position. [x, y, z]
292
293       :type: :class:`mathutils.Vector`
294
295    .. attribute:: localTransform
296
297       The object's local space transform matrix. 4x4 Matrix.
298
299       :type: :class:`mathutils.Matrix`
300
301    .. attribute:: worldTransform
302
303       The object's world space transform matrix. 4x4 Matrix.
304
305       :type: :class:`mathutils.Matrix`
306
307    .. attribute:: localLinearVelocity
308
309       The object's local linear velocity. [x, y, z]
310
311       :type: :class:`mathutils.Vector`
312
313    .. attribute:: worldLinearVelocity
314
315       The object's world linear velocity. [x, y, z]
316
317       :type: :class:`mathutils.Vector`
318
319    .. attribute:: localAngularVelocity
320
321       The object's local angular velocity. [x, y, z]
322
323       :type: :class:`mathutils.Vector`
324
325    .. attribute:: worldAngularVelocity
326
327       The object's world angular velocity. [x, y, z]
328
329       :type: :class:`mathutils.Vector`
330
331    .. attribute:: timeOffset
332
333       adjust the slowparent delay at runtime.
334
335       :type: float
336
337    .. attribute:: state
338
339       the game object's state bitmask, using the first 30 bits, one bit must always be set.
340
341       :type: int
342
343    .. attribute:: meshes
344
345       a list meshes for this object.
346
347       :type: list of :class:`KX_MeshProxy`
348
349       .. note::
350
351          Most objects use only 1 mesh.
352
353       .. note::
354
355          Changes to this list will not update the KX_GameObject.
356
357    .. attribute:: sensors
358
359       a sequence of :class:`SCA_ISensor` objects with string/index lookups and iterator support.
360
361       :type: list
362
363       .. note::
364
365          This attribute is experemental and may be removed (but probably wont be).
366
367       .. note::
368
369          Changes to this list will not update the KX_GameObject.
370
371    .. attribute:: controllers
372
373       a sequence of :class:`SCA_IController` objects with string/index lookups and iterator support.
374
375       :type: list of :class:`SCA_ISensor`
376
377       .. note::
378
379          This attribute is experemental and may be removed (but probably wont be).
380
381       .. note::
382
383          Changes to this list will not update the KX_GameObject.
384
385    .. attribute:: actuators
386
387       a list of :class:`SCA_IActuator` with string/index lookups and iterator support.
388
389       :type: list
390
391       .. note::
392
393          This attribute is experemental and may be removed (but probably wont be).
394
395       .. note::
396
397          Changes to this list will not update the KX_GameObject.
398
399    .. attribute:: attrDict
400
401       get the objects internal python attribute dictionary for direct (faster) access.
402
403       :type: dict
404
405    .. attribute:: children
406
407       direct children of this object, (read-only).
408
409       :type: :class:`CListValue` of :class:`KX_GameObject`'s
410
411    .. attribute:: childrenRecursive
412
413       all children of this object including childrens children, (read-only).
414
415       :type: :class:`CListValue` of :class:`KX_GameObject`'s
416
417    .. attribute:: life
418
419       The number of seconds until the object ends, assumes 50fps.
420       (when added with an add object actuator), (read-only).
421
422       :type: float
423
424    .. attribute:: debug
425
426       If true, the object's debug properties will be displayed on screen.
427
428       :type: boolean
429
430    .. attribute:: debugRecursive
431
432       If true, the object's and children's debug properties will be displayed on screen.
433
434       :type: boolean
435       
436    .. attribute:: currentLodLevel
437
438       The index of the level of detail (LOD) currently used by this object (read-only).
439
440       :type: int
441
442    .. method:: endObject()
443
444       Delete this object, can be used in place of the EndObject Actuator.
445
446       The actual removal of the object from the scene is delayed.
447
448    .. method:: replaceMesh(mesh, useDisplayMesh=True, usePhysicsMesh=False)
449
450       Replace the mesh of this object with a new mesh. This works the same was as the actuator.
451
452       :arg mesh: mesh to replace or the meshes name.
453       :type mesh: :class:`MeshProxy` or string
454       :arg useDisplayMesh: when enabled the display mesh will be replaced (optional argument).
455       :type useDisplayMesh: boolean
456       :arg usePhysicsMesh: when enabled the physics mesh will be replaced (optional argument).
457       :type usePhysicsMesh: boolean
458
459    .. method:: setVisible(visible, recursive)
460
461       Sets the game object's visible flag.
462
463       :arg visible: the visible state to set.
464       :type visible: boolean
465       :arg recursive: optional argument to set all childrens visibility flag too.
466       :type recursive: boolean
467
468    .. method:: setOcclusion(occlusion, recursive)
469
470       Sets the game object's occlusion capability.
471
472       :arg occlusion: the state to set the occlusion to.
473       :type occlusion: boolean
474       :arg recursive: optional argument to set all childrens occlusion flag too.
475       :type recursive: boolean
476
477    .. method:: alignAxisToVect(vect, axis=2, factor=1.0)
478
479       Aligns any of the game object's axis along the given vector.
480
481
482       :arg vect: a vector to align the axis.
483       :type vect: 3D vector
484       :arg axis: The axis you want to align
485
486          * 0: X axis
487          * 1: Y axis
488          * 2: Z axis
489
490       :type axis: integer
491       :arg factor: Only rotate a feaction of the distance to the target vector (0.0 - 1.0)
492       :type factor: float
493
494    .. method:: getAxisVect(vect)
495
496       Returns the axis vector rotates by the objects worldspace orientation.
497       This is the equivalent of multiplying the vector by the orientation matrix.
498
499       :arg vect: a vector to align the axis.
500       :type vect: 3D Vector
501       :return: The vector in relation to the objects rotation.
502       :rtype: 3d vector.
503
504    .. method:: applyMovement(movement, local=False)
505
506       Sets the game object's movement.
507
508       :arg movement: movement vector.
509       :type movement: 3D Vector
510       :arg local:
511          * False: you get the "global" movement ie: relative to world orientation.
512          * True: you get the "local" movement ie: relative to object orientation.
513       :arg local: boolean
514
515    .. method:: applyRotation(rotation, local=False)
516
517       Sets the game object's rotation.
518
519       :arg rotation: rotation vector.
520       :type rotation: 3D Vector
521       :arg local:
522          * False: you get the "global" rotation ie: relative to world orientation.
523          * True: you get the "local" rotation ie: relative to object orientation.
524       :arg local: boolean
525
526    .. method:: applyForce(force, local=False)
527
528       Sets the game object's force.
529
530       This requires a dynamic object.
531
532       :arg force: force vector.
533       :type force: 3D Vector
534       :arg local:
535          * False: you get the "global" force ie: relative to world orientation.
536          * True: you get the "local" force ie: relative to object orientation.
537       :type local: boolean
538
539    .. method:: applyTorque(torque, local=False)
540
541       Sets the game object's torque.
542
543       This requires a dynamic object.
544
545       :arg torque: torque vector.
546       :type torque: 3D Vector
547       :arg local:
548          * False: you get the "global" torque ie: relative to world orientation.
549          * True: you get the "local" torque ie: relative to object orientation.
550       :type local: boolean
551
552    .. method:: getLinearVelocity(local=False)
553
554       Gets the game object's linear velocity.
555
556       This method returns the game object's velocity through it's centre of mass, ie no angular velocity component.
557
558       :arg local:
559          * False: you get the "global" velocity ie: relative to world orientation.
560          * True: you get the "local" velocity ie: relative to object orientation.
561       :type local: boolean
562       :return: the object's linear velocity.
563       :rtype: Vector((vx, vy, vz))
564
565    .. method:: setLinearVelocity(velocity, local=False)
566
567       Sets the game object's linear velocity.
568
569       This method sets game object's velocity through it's centre of mass,
570       ie no angular velocity component.
571
572       This requires a dynamic object.
573
574       :arg velocity: linear velocity vector.
575       :type velocity: 3D Vector
576       :arg local:
577          * False: you get the "global" velocity ie: relative to world orientation.
578          * True: you get the "local" velocity ie: relative to object orientation.
579       :type local: boolean
580
581    .. method:: getAngularVelocity(local=False)
582
583       Gets the game object's angular velocity.
584
585       :arg local:
586          * False: you get the "global" velocity ie: relative to world orientation.
587          * True: you get the "local" velocity ie: relative to object orientation.
588       :type local: boolean
589       :return: the object's angular velocity.
590       :rtype: Vector((vx, vy, vz))
591
592    .. method:: setAngularVelocity(velocity, local=False)
593
594       Sets the game object's angular velocity.
595
596       This requires a dynamic object.
597
598       :arg velocity: angular velocity vector.
599       :type velocity: boolean
600       :arg local:
601          * False: you get the "global" velocity ie: relative to world orientation.
602          * True: you get the "local" velocity ie: relative to object orientation.
603
604    .. method:: getVelocity(point=(0, 0, 0))
605
606       Gets the game object's velocity at the specified point.
607
608       Gets the game object's velocity at the specified point, including angular
609       components.
610
611       :arg point: optional point to return the velocity for, in local coordinates.
612       :type point: 3D Vector
613       :return: the velocity at the specified point.
614       :rtype: Vector((vx, vy, vz))
615
616    .. method:: getReactionForce()
617
618       Gets the game object's reaction force.
619
620       The reaction force is the force applied to this object over the last simulation timestep.
621       This also includes impulses, eg from collisions.
622
623       :return: the reaction force of this object.
624       :rtype: Vector((fx, fy, fz))
625
626       .. note::
627
628          This is not implimented at the moment.
629
630    .. method:: applyImpulse(point, impulse, local=False)
631
632       Applies an impulse to the game object.
633
634       This will apply the specified impulse to the game object at the specified point.
635       If point != position, applyImpulse will also change the object's angular momentum.
636       Otherwise, only linear momentum will change.
637
638       :arg point: the point to apply the impulse to (in world or local coordinates)
639       :type point: point [ix, iy, iz] the point to apply the impulse to (in world or local coordinates)
640       :arg impulse: impulse vector.
641       :type impulse: 3D Vector
642       :arg local:
643          * False: you get the "global" impulse ie: relative to world coordinates with world orientation.
644          * True: you get the "local" impulse ie: relative to local coordinates with object orientation.
645       :type local: boolean
646
647    .. method:: setDamping(linear_damping, angular_damping)
648
649       Sets both the :py:attr:`linearDamping` and :py:attr:`angularDamping` simultaneously. This is more efficient than setting both properties individually.
650
651       :arg linear_damping: Linear ("translational") damping factor.
652       :type linear_damping: float ∈ [0, 1]
653       :arg angular_damping: Angular ("rotational") damping factor.
654       :type angular_damping: float ∈ [0, 1]
655
656    .. method:: suspendDynamics()
657
658       Suspends physics for this object.
659
660    .. method:: restoreDynamics()
661
662       Resumes physics for this object.
663
664       .. note::
665
666          The objects linear velocity will be applied from when the dynamics were suspended.
667
668    .. method:: enableRigidBody()
669
670       Enables rigid body physics for this object.
671
672       Rigid body physics allows the object to roll on collisions.
673
674    .. method:: disableRigidBody()
675
676       Disables rigid body physics for this object.
677
678    .. method:: setParent(parent, compound=True, ghost=True)
679
680       Sets this object's parent.
681       Control the shape status with the optional compound and ghost parameters:
682
683       In that case you can control if it should be ghost or not:
684
685       :arg parent: new parent object.
686       :type parent: :class:`KX_GameObject`
687       :arg compound: whether the shape should be added to the parent compound shape.
688
689          * True: the object shape should be added to the parent compound shape.
690          * False: the object should keep its individual shape.
691
692       :type compound: boolean
693       :arg ghost: whether the object should be ghost while parented.
694
695          * True: if the object should be made ghost while parented.
696          * False: if the object should be solid while parented.
697
698       :type ghost: boolean
699
700       .. note::
701
702          If the object type is sensor, it stays ghost regardless of ghost parameter
703
704    .. method:: removeParent()
705
706       Removes this objects parent.
707
708    .. method:: getPhysicsId()
709
710       Returns the user data object associated with this game object's physics controller.
711
712    .. method:: getPropertyNames()
713
714       Gets a list of all property names.
715
716       :return: All property names for this object.
717       :rtype: list
718
719    .. method:: getDistanceTo(other)
720
721       :arg other: a point or another :class:`KX_GameObject` to measure the distance to.
722       :type other: :class:`KX_GameObject` or list [x, y, z]
723       :return: distance to another object or point.
724       :rtype: float
725
726    .. method:: getVectTo(other)
727
728       Returns the vector and the distance to another object or point.
729       The vector is normalized unless the distance is 0, in which a zero length vector is returned.
730
731       :arg other: a point or another :class:`KX_GameObject` to get the vector and distance to.
732       :type other: :class:`KX_GameObject` or list [x, y, z]
733       :return: (distance, globalVector(3), localVector(3))
734       :rtype: 3-tuple (float, 3-tuple (x, y, z), 3-tuple (x, y, z))
735
736    .. method:: rayCastTo(other, dist, prop)
737
738       Look towards another point/object and find first object hit within dist that matches prop.
739
740       The ray is always casted from the center of the object, ignoring the object itself.
741       The ray is casted towards the center of another object or an explicit [x, y, z] point.
742       Use rayCast() if you need to retrieve the hit point
743
744       :arg other: [x, y, z] or object towards which the ray is casted
745       :type other: :class:`KX_GameObject` or 3-tuple
746       :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
747       :type dist: float
748       :arg prop: property name that object must have; can be omitted => detect any object
749       :type prop: string
750       :return: the first object hit or None if no object or object does not match prop
751       :rtype: :class:`KX_GameObject`
752
753    .. method:: rayCast(objto, objfrom, dist, prop, face, xray, poly)
754
755       Look from a point/object to another point/object and find first object hit within dist that matches prop.
756       if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None, None, None) if no hit.
757       if poly is 1, returns a 4-tuple with in addition a :class:`KX_PolyProxy` as 4th element.
758       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.
759
760       .. code-block:: python
761
762          # shoot along the axis gun-gunAim (gunAim should be collision-free)
763          obj, point, normal = gun.rayCast(gunAim, None, 50)
764          if obj:
765             # do something
766             pass
767
768       The face paremeter determines the orientation of the normal.
769
770       * 0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
771       * 1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
772
773       The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
774       The prop and xray parameters interact as follow.
775
776       * prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
777       * prop off, xray on : idem.
778       * prop on, xray off: return closest hit if it matches prop, no hit otherwise.
779       * 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.
780
781       The :class:`KX_PolyProxy` 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray.
782       If there is no hit or the hit object is not a static mesh, None is returned as 4th element.
783
784       The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
785
786       :arg objto: [x, y, z] or object to which the ray is casted
787       :type objto: :class:`KX_GameObject` or 3-tuple
788       :arg objfrom: [x, y, z] or object from which the ray is casted; None or omitted => use self object center
789       :type objfrom: :class:`KX_GameObject` or 3-tuple or None
790       :arg dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
791       :type dist: float
792       :arg prop: property name that object must have; can be omitted or "" => detect any object
793       :type prop: string
794       :arg face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
795       :type face: integer
796       :arg xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
797       :type xray: integer
798       :arg poly: polygon option: 0, 1 or 2 to return a 3-, 4- or 5-tuple with information on the face hit.
799
800          * 0 or omitted: return value is a 3-tuple (object, hitpoint, hitnormal) or (None, None, None) if no hit
801          * 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.
802          * 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.
803
804       :type poly: integer
805       :return: (object, hitpoint, hitnormal) or (object, hitpoint, hitnormal, polygon) or (object, hitpoint, hitnormal, polygon, hituv).
806
807          * object, hitpoint and hitnormal are None if no hit.
808          * 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
809          * hituv is valid only if polygon is valid and the object has a UV mapping, otherwise it is None
810
811       :rtype:
812
813          * 3-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz))
814          * or 4-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz), :class:`KX_PolyProxy`)
815          * or 5-tuple (:class:`KX_GameObject`, 3-tuple (x, y, z), 3-tuple (nx, ny, nz), :class:`KX_PolyProxy`, 2-tuple (u, v))
816
817       .. note::
818
819          The ray ignores the object on which the method is called. It is casted from/to object center or explicit [x, y, z] points.
820
821    .. method:: setCollisionMargin(margin)
822
823       Set the objects collision margin.
824
825       :arg margin: the collision margin distance in blender units.
826       :type margin: float
827
828       .. note::
829
830          If this object has no physics controller (a physics ID of zero), this function will raise RuntimeError.
831
832    .. method:: sendMessage(subject, body="", to="")
833
834       Sends a message.
835
836       :arg subject: The subject of the message
837       :type subject: string
838       :arg body: The body of the message (optional)
839       :type body: string
840       :arg to: The name of the object to send the message to (optional)
841       :type to: string
842
843    .. method:: reinstancePhysicsMesh(gameObject, meshObject)
844
845       Updates the physics system with the changed mesh.
846
847       If no arguments are given the physics mesh will be re-created from the first mesh assigned to the game object.
848
849       :arg gameObject: optional argument, set the physics shape from this gameObjets mesh.
850       :type gameObject: string, :class:`KX_GameObject` or None
851       :arg meshObject: optional argument, set the physics shape from this mesh.
852       :type meshObject: string, :class:`MeshProxy` or None
853
854       :return: True if reinstance succeeded, False if it failed.
855       :rtype: boolean
856
857       .. note::
858
859          If this object has instances the other instances will be updated too.
860
861       .. note::
862
863          The gameObject argument has an advantage that it can convert from a mesh with modifiers applied (such as subsurf).
864
865       .. warning::
866
867          Only triangle mesh type objects are supported currently (not convex hull)
868
869       .. warning::
870
871          If the object is a part of a combound object it will fail (parent or child)
872
873       .. warning::
874
875          Rebuilding the physics mesh can be slow, running many times per second will give a performance hit.
876
877    .. method:: get(key, default=None)
878
879       Return the value matching key, or the default value if its not found.
880       :return: The key value or a default.
881
882    .. method:: playAction(name, start_frame, end_frame, layer=0, priority=0, blendin=0, play_mode=KX_ACTION_MODE_PLAY, layer_weight=0.0, ipo_flags=0, speed=1.0, blend_mode=KX_ACTION_BLEND_BLEND)
883
884       Plays an action.
885
886       :arg name: the name of the action
887       :type name: string
888       :arg start: the start frame of the action
889       :type start: float
890       :arg end: the end frame of the action
891       :type end: float
892       :arg layer: the layer the action will play in (actions in different layers are added/blended together)
893       :type layer: integer
894       :arg priority: only play this action if there isn't an action currently playing in this layer with a higher (lower number) priority
895       :type priority: integer
896       :arg blendin: the amount of blending between this animation and the previous one on this layer
897       :type blendin: float
898       :arg play_mode: the play mode
899       :type play_mode: one of :ref:`these constants <gameobject-playaction-mode>`
900       :arg layer_weight: how much of the previous layer to use for blending
901       :type layer_weight: float
902       :arg ipo_flags: flags for the old IPO behaviors (force, etc)
903       :type ipo_flags: int bitfield
904       :arg speed: the playback speed of the action as a factor (1.0 = normal speed, 2.0 = 2x speed, etc)
905       :type speed: float
906       :arg blend_mode: how to blend this layer with previous layers
907       :type blend_mode: one of :ref:`these constants <gameobject-playaction-blend>`
908
909    .. method:: stopAction(layer=0)
910
911       Stop playing the action on the given layer.
912
913       :arg layer: The layer to stop playing.
914       :type layer: integer
915
916    .. method:: getActionFrame(layer=0)
917
918       Gets the current frame of the action playing in the supplied layer.
919
920       :arg layer: The layer that you want to get the frame from.
921       :type layer: integer
922
923       :return: The current frame of the action
924       :rtype: float
925
926    .. method:: setActionFrame(frame, layer=0)
927
928       Set the current frame of the action playing in the supplied layer.
929
930       :arg layer: The layer where you want to set the frame
931       :type layer: integer
932       :arg frame: The frame to set the action to
933       :type frame: float
934
935    .. method:: isPlayingAction(layer=0)
936
937       Checks to see if there is an action playing in the given layer.
938
939       :arg layer: The layer to check for a playing action.
940       :type layer: integer
941
942       :return: Whether or not the action is playing
943       :rtype: boolean
944
945    .. method:: addDebugProperty (name, debug = True)
946
947       Adds a single debug property to the debug list.
948
949       :arg name: name of the property that added to the debug list.
950       :type name: string
951       :arg debug: the debug state.
952       :type debug: boolean