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