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