source/gameengine/PyDoc/KX_GameObject.py

   1 # $Id$
   2 # Documentation for game objects
   3
   4 class KX_GameObject:
   5         """
   6         All game objects are derived from this class.
   7
   8         Properties assigned to game objects are accessible as attributes of this class.
   9
  10         @ivar name: The object's name.
  11         @type name: string.
  12         @ivar mass: The object's mass (provided the object has a physics controller). Read only.
  13         @type mass: float
  14         @ivar parent: The object's parent object. (Read only)
  15         @type parent: L{KX_GameObject}
  16         @ivar visible: visibility flag.
  17         @type visible: boolean
  18         @ivar position: The object's position.
  19         @type position: list [x, y, z]
  20         @ivar orientation: The object's orientation. 3x3 Matrix.
  21                            You can also write a Quaternion or Euler vector.
  22         @type orientation: 3x3 Matrix [[float]]
  23         @ivar scaling: The object's scaling factor. list [sx, sy, sz]
  24         @type scaling: list [sx, sy, sz]
  25         """
  26
  27         def setVisible(visible):
  28                 """
  29                 Sets the game object's visible flag.
  30
  31                 @type visible: boolean
  32                 """
  33         def setPosition(pos):
  34                 """
  35                 Sets the game object's position.
  36
  37                 @type pos: [x, y, z]
  38                 @param pos: the new position, in world coordinates.
  39                 """
  40         def getPosition():
  41                 """
  42                 Gets the game object's position.
  43
  44                 @rtype: list [x, y, z]
  45                 @return: the object's position in world coordinates.
  46                 """
  47         def setOrientation(orn):
  48                 """
  49                 Sets the game object's orientation.
  50
  51                 @type orn: 3x3 rotation matrix, or Quaternion.
  52                 @param orn: a rotation matrix specifying the new rotation.
  53                 """
  54         def getOrientation():
  55                 """
  56                 Gets the game object's orientation.
  57
  58                 @rtype: 3x3 rotation matrix
  59                 @return: The game object's rotation matrix
  60                 """
  61         def getLinearVelocity(local):
  62                 """
  63                 Gets the game object's linear velocity.
  64
  65                 This method returns the game object's velocity through it's centre of mass,
  66                 ie no angular velocity component.
  67
  68                 @type local: boolean
  69                 @param local: - False: you get the "global" velocity ie: relative to world orientation.
  70                               - True: you get the "local" velocity ie: relative to object orientation.
  71                 @rtype: list [vx, vy, vz]
  72                 @return: the object's linear velocity.
  73                 """
  74         def getVelocity(point):
  75                 """
  76                 Gets the game object's velocity at the specified point.
  77
  78                 Gets the game object's velocity at the specified point, including angular
  79                 components.
  80
  81                 @type point: list [x, y, z]
  82                 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])
  83                 @rtype: list [vx, vy, vz]
  84                 @return: the velocity at the specified point.
  85                 """
  86         def getMass():
  87                 """
  88                 Gets the game object's mass.
  89
  90                 @rtype: float
  91                 @return: the object's mass.
  92                 """
  93         def getReactionForce():
  94                 """
  95                 Gets the game object's reaction force.
  96
  97                 The reaction force is the force applied to this object over the last simulation timestep.
  98                 This also includes impulses, eg from collisions.
  99
 100                 @rtype: list [fx, fy, fz]
 101                 @return: the reaction force of this object.
 102                 """
 103         def applyImpulse(point, impulse):
 104                 """
 105                 Applies an impulse to the game object.
 106
 107                 This will apply the specified impulse to the game object at the specified point.
 108                 If point != getPosition(), applyImpulse will also change the object's angular momentum.
 109                 Otherwise, only linear momentum will change.
 110
 111                 @type point: list [x, y, z]
 112                 @param point: the point to apply the impulse to (in world coordinates)
 113                 """
 114         def suspendDynamics():
 115                 """
 116                 Suspends physics for this object.
 117                 """
 118         def restoreDynamics():
 119                 """
 120                 Resumes physics for this object.
 121                 """
 122         def enableRigidBody():
 123                 """
 124                 Enables rigid body physics for this object.
 125
 126                 Rigid body physics allows the object to roll on collisions.
 127                 """
 128         def disableRigidBody():
 129                 """
 130                 Disables rigid body physics for this object.
 131                 """
 132         def getParent():
 133                 """
 134                 Gets this object's parent.
 135
 136                 @rtype: L{KX_GameObject}
 137                 @return: this object's parent object, or None if this object has no parent.
 138                 """
 139         def setParent(parent):
 140                 """
 141                 Sets this object's parent.
 142
 143                 @type parent: L{KX_GameObject}
 144                 @param parent: new parent object.
 145                 """
 146         def removeParent():
 147                 """
 148                 Removes this objects parent.
 149                 """
 150         def getMesh(mesh):
 151                 """
 152                 Gets the mesh object for this object.
 153
 154                 @type mesh: integer
 155                 @param mesh: the mesh object to return (optional: default mesh = 0)
 156                 @rtype: L{KX_MeshProxy}
 157                 @return: the first mesh object associated with this game object, or None if this object has no meshs.
 158                 """
 159         def getPhysicsId():
 160                 """
 161                 Returns the user data object associated with this game object's physics controller.
 162                 """
 163         def getDistanceTo(other):
 164                 """
 165                 Returns the distance to another object or point.
 166
 167                 @param other: a point or another L{KX_GameObject} to measure the distance to.
 168                 @type other: L{KX_GameObject} or list [x, y, z]
 169                 @rtype: float
 170                 """
 171         def rayCastTo(other,dist,prop):
 172                 """
 173                 Look towards another point/object and find first object hit within dist that matches prop.
 174
 175                 The ray is always casted from the center of the object, ignoring the object itself.
 176                 The ray is casted towards the center of another object or an explicit [x,y,z] point.
 177                 Use rayCast() if you need to retrieve the hit point
 178
 179                 @param other: [x,y,z] or object towards which the ray is casted
 180                 @type other: L{KX_GameObject} or 3-tuple
 181                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
 182                 @type dist: float
 183                 @param prop: property name that object must have; can be omitted => detect any object
 184                 @type prop: string
 185                 @rtype: L{KX_GameObject}
 186                 @return: the first object hit or None if no object or object does not match prop
 187                 """
 188         def rayCast(to,from,dist,prop):
 189                 """
 190                 Look from a point/object to another point/object and find first object hit within dist that matches prop.
 191                 Returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit.
 192                 Ex:
 193                         # shoot along the axis gun-gunAim (gunAim should be collision-free)
 194                         ob,point,normal = gun.rayCast(gunAim,None,50)
 195                         if ob:
 196                                 # hit something
 197
 198                 Notes:
 199                 The ray ignores the object on which the method is called.
 200                 If is casted from/to object center or explicit [x,y,z] points.
 201                 The ray does not have X-Ray capability: the first object hit (other than self object) stops the ray
 202                 If a property was specified and the first object hit does not have that property, there is no hit
 203                 The     ray ignores collision-free objects
 204
 205                 @param to: [x,y,z] or object to which the ray is casted
 206                 @type to: L{KX_GameObject} or 3-tuple
 207                 @param from: [x,y,z] or object from which the ray is casted; None or omitted => use self object center
 208                 @type from: L{KX_GameObject} or 3-tuple or None
 209                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
 210                 @type dist: float
 211                 @param prop: property name that object must have; can be omitted => detect any object
 212                 @type prop: string
 213                 @rtype: 3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz))
 214                 @return: (object,hitpoint,hitnormal) or (None,None,None)
 215                 """
 216