source/gameengine/PyDoc/KX_GameObject.py

   1 # $Id$
   2 # Documentation for game objects
   3
   4 # from SCA_IObject import *
   5 # from SCA_ISensor import *
   6 # from SCA_IController import *
   7 # from SCA_IActuator import *
   8
   9
  10 class KX_GameObject: # (SCA_IObject)
  11         """
  12         All game objects are derived from this class.
  13
  14         Properties assigned to game objects are accessible as attributes of this class.
  15
  16         @ivar name: The object's name. (Read only)
  17                 - note: Currently (Blender 2.49) the prefix "OB" is added to all objects name. This may change in blender 2.5.
  18         @type name: string.
  19         @ivar mass: The object's mass (provided the object has a physics controller). Read only.
  20         @type mass: float
  21         @ivar parent: The object's parent object. (Read only)
  22         @type parent: L{KX_GameObject} or None
  23         @ivar visible: visibility flag.
  24                 - note: Game logic will still run for invisible objects.
  25         @type visible: boolean
  26         @ivar position: The object's position.
  27         @type position: list [x, y, z]
  28         @ivar orientation: The object's orientation. 3x3 Matrix. You can also write a Quaternion or Euler vector.
  29         @type orientation: 3x3 Matrix [[float]]
  30         @ivar scaling: The object's scaling factor. list [sx, sy, sz]
  31         @type scaling: list [sx, sy, sz]
  32         @ivar timeOffset: adjust the slowparent delay at runtime.
  33         @type timeOffset: float
  34         @ivar state: the game object's state bitmask.
  35         @type state: int
  36         @ivar meshes: a list meshes for this object.
  37                 - note: Most objects use only 1 mesh.
  38                 - note: Changes to this list will not update the KX_GameObject.
  39         @type meshes: list of L{KX_MeshProxy}
  40         @ivar sensors: a list of L{SCA_ISensor} objects.
  41                 - note: This attribute is experemental and may be removed (but probably wont be).
  42                 - note: Changes to this list will not update the KX_GameObject.
  43         @type sensors: list
  44         @ivar controllers: a list of L{SCA_IController} objects.
  45                 - note: This attribute is experemental and may be removed (but probably wont be).
  46                 - note: Changes to this list will not update the KX_GameObject.
  47         @type controllers: list of L{SCA_ISensor}.
  48         @ivar actuators: a list of L{SCA_IActuator} objects.
  49                 - note: This attribute is experemental and may be removed (but probably wont be).
  50                 - note: Changes to this list will not update the KX_GameObject.
  51         @type actuators: list
  52         """
  53         def endObject(visible):
  54                 """
  55                 Delete this object, can be used inpace of the EndObject Actuator.
  56                 The actual removal of the object from the scene is delayed.
  57                 """
  58         def replaceMesh(mesh_name):
  59                 """
  60                 Replace the mesh of this object with a new mesh. This works the same was as the actuator.
  61                 @type mesh_name: string
  62                 """
  63         def getVisible():
  64                 """
  65                 Gets the game object's visible flag. (B{deprecated})
  66
  67                 @rtype: boolean
  68                 """
  69         def setVisible(visible, recursive):
  70                 """
  71                 Sets the game object's visible flag.
  72
  73                 @type visible: boolean
  74                 @type recursive: boolean
  75                 @param recursive: optional argument to set all childrens visibility flag too.
  76                 """
  77         def getState():
  78                 """
  79                 Gets the game object's state bitmask. (B{deprecated})
  80
  81                 @rtype: int
  82                 @return: the objects state.
  83                 """
  84         def setState(state):
  85                 """
  86                 Sets the game object's state flag. (B{deprecated}).
  87                 The bitmasks for states from 1 to 30 can be set with (1<<0, 1<<1, 1<<2 ... 1<<29)
  88
  89                 @type state: integer
  90                 """
  91         def setPosition(pos):
  92                 """
  93                 Sets the game object's position. (B{deprecated})
  94                 Global coordinates for root object, local for child objects.
  95
  96
  97                 @type pos: [x, y, z]
  98                 @param pos: the new position, in local coordinates.
  99                 """
 100         def setWorldPosition(pos):
 101                 """
 102                 Sets the game object's position in world coordinates regardless if the object is root or child.
 103
 104                 @type pos: [x, y, z]
 105                 @param pos: the new position, in world coordinates.
 106                 """
 107         def getPosition():
 108                 """
 109                 Gets the game object's position. (B{deprecated})
 110
 111                 @rtype: list [x, y, z]
 112                 @return: the object's position in world coordinates.
 113                 """
 114         def setOrientation(orn):
 115                 """
 116                 Sets the game object's orientation. (B{deprecated})
 117
 118                 @type orn: 3x3 rotation matrix, or Quaternion.
 119                 @param orn: a rotation matrix specifying the new rotation.
 120                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
 121                 """
 122         def alignAxisToVect(vect, axis):
 123                 """
 124                 Aligns any of the game object's axis along the given vector.
 125
 126                 @type vect: 3d vector.
 127                 @param vect: a vector to align the axis.
 128                 @type axis: integer.
 129                 @param axis:The axis you want to align
 130                                         - 0: X axis
 131                                         - 1: Y axis
 132                                         - 2: Z axis (default)
 133                 """
 134         def getAxisVect(vect):
 135                 """
 136                 Returns the axis vector rotates by the objects worldspace orientation.
 137                 This is the equivalent if multiplying the vector by the orientation matrix.
 138
 139                 @type vect: 3d vector.
 140                 @param vect: a vector to align the axis.
 141                 @rtype: 3d vector.
 142                 @return: The vector in relation to the objects rotation.
 143
 144                 """
 145         def getOrientation():
 146                 """
 147                 Gets the game object's orientation. (B{deprecated})
 148
 149                 @rtype: 3x3 rotation matrix
 150                 @return: The game object's rotation matrix
 151                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
 152                 """
 153         def applyMovement(movement, local = 0):
 154                 """
 155                 Sets the game object's movement.
 156
 157                 @type movement: 3d vector.
 158                 @param movement: movement vector.
 159                 @type local: boolean
 160                 @param local: - False: you get the "global" movement ie: relative to world orientation (default).
 161                               - True: you get the "local" movement ie: relative to object orientation.
 162                 """
 163         def applyRotation(rotation, local = 0):
 164                 """
 165                 Sets the game object's rotation.
 166
 167                 @type rotation: 3d vector.
 168                 @param rotation: rotation vector.
 169                 @type local: boolean
 170                 @param local: - False: you get the "global" rotation ie: relative to world orientation (default).
 171                                           - True: you get the "local" rotation ie: relative to object orientation.
 172                 """
 173         def applyForce(force, local = 0):
 174                 """
 175                 Sets the game object's force.
 176
 177                 This requires a dynamic object.
 178
 179                 @type force: 3d vector.
 180                 @param force: force vector.
 181                 @type local: boolean
 182                 @param local: - False: you get the "global" force ie: relative to world orientation (default).
 183                                           - True: you get the "local" force ie: relative to object orientation.
 184                 """
 185         def applyTorque(torque, local = 0):
 186                 """
 187                 Sets the game object's torque.
 188
 189                 This requires a dynamic object.
 190
 191                 @type torque: 3d vector.
 192                 @param torque: torque vector.
 193                 @type local: boolean
 194                 @param local: - False: you get the "global" torque ie: relative to world orientation (default).
 195                                           - True: you get the "local" torque ie: relative to object orientation.
 196                 """
 197         def getLinearVelocity(local = 0):
 198                 """
 199                 Gets the game object's linear velocity.
 200
 201                 This method returns the game object's velocity through it's centre of mass,
 202                 ie no angular velocity component.
 203
 204                 @type local: boolean
 205                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
 206                               - True: you get the "local" velocity ie: relative to object orientation.
 207                 @rtype: list [vx, vy, vz]
 208                 @return: the object's linear velocity.
 209                 """
 210         def setLinearVelocity(velocity, local = 0):
 211                 """
 212                 Sets the game object's linear velocity.
 213
 214                 This method sets game object's velocity through it's centre of mass,
 215                 ie no angular velocity component.
 216
 217                 This requires a dynamic object.
 218
 219                 @type velocity: 3d vector.
 220                 @param velocity: linear velocity vector.
 221                 @type local: boolean
 222                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
 223                               - True: you get the "local" velocity ie: relative to object orientation.
 224                 """
 225         def getAngularVelocity(local = 0):
 226                 """
 227                 Gets the game object's angular velocity.
 228
 229                 @type local: boolean
 230                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
 231                               - True: you get the "local" velocity ie: relative to object orientation.
 232                 @rtype: list [vx, vy, vz]
 233                 @return: the object's angular velocity.
 234                 """
 235         def setAngularVelocity(velocity, local = 0):
 236                 """
 237                 Sets the game object's angular velocity.
 238
 239                 This requires a dynamic object.
 240
 241                 @type velocity: 3d vector.
 242                 @param velocity: angular velocity vector.
 243                 @type local: boolean
 244                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
 245                               - True: you get the "local" velocity ie: relative to object orientation.
 246                 """
 247         def getVelocity(point):
 248                 """
 249                 Gets the game object's velocity at the specified point.
 250
 251                 Gets the game object's velocity at the specified point, including angular
 252                 components.
 253
 254                 @type point: list [x, y, z]
 255                 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])
 256                 @rtype: list [vx, vy, vz]
 257                 @return: the velocity at the specified point.
 258                 """
 259         def getMass():
 260                 """
 261                 Gets the game object's mass. (B{deprecated})
 262
 263                 @rtype: float
 264                 @return: the object's mass.
 265                 """
 266         def getReactionForce():
 267                 """
 268                 Gets the game object's reaction force.
 269
 270                 The reaction force is the force applied to this object over the last simulation timestep.
 271                 This also includes impulses, eg from collisions.
 272
 273                 (B{This is not implimented for bullet physics at the moment})
 274
 275                 @rtype: list [fx, fy, fz]
 276                 @return: the reaction force of this object.
 277                 """
 278         def applyImpulse(point, impulse):
 279                 """
 280                 Applies an impulse to the game object.
 281
 282                 This will apply the specified impulse to the game object at the specified point.
 283                 If point != getPosition(), applyImpulse will also change the object's angular momentum.
 284                 Otherwise, only linear momentum will change.
 285
 286                 @type point: list [x, y, z]
 287                 @param point: the point to apply the impulse to (in world coordinates)
 288                 """
 289         def suspendDynamics():
 290                 """
 291                 Suspends physics for this object.
 292                 """
 293         def restoreDynamics():
 294                 """
 295                 Resumes physics for this object.
 296                 @Note: The objects linear velocity will be applied from when the dynamics were suspended.
 297                 """
 298         def enableRigidBody():
 299                 """
 300                 Enables rigid body physics for this object.
 301
 302                 Rigid body physics allows the object to roll on collisions.
 303                 @Note: This is not working with bullet physics yet.
 304                 """
 305         def disableRigidBody():
 306                 """
 307                 Disables rigid body physics for this object.
 308                 @Note: This is not working with bullet physics yet. The angular is removed but rigid body physics can still rotate it later.
 309                 """
 310         def getParent():
 311                 """
 312                 Gets this object's parent. (B{deprecated})
 313
 314                 @rtype: L{KX_GameObject}
 315                 @return: this object's parent object, or None if this object has no parent.
 316                 """
 317         def setParent(parent):
 318                 """
 319                 Sets this object's parent.
 320
 321                 @type parent: L{KX_GameObject}
 322                 @param parent: new parent object.
 323                 """
 324         def removeParent():
 325                 """
 326                 Removes this objects parent.
 327                 """
 328         def getChildren():
 329                 """
 330                 Return a list of immediate children of this object.
 331                 @rtype: list
 332                 @return: a list of all this objects children.
 333                 """
 334         def getChildrenRecursive():
 335                 """
 336                 Return a list of children of this object, including all their childrens children.
 337                 @rtype: list
 338                 @return: a list of all this objects children recursivly.
 339                 """
 340         def getMesh(mesh):
 341                 """
 342                 Gets the mesh object for this object.
 343
 344                 @type mesh: integer
 345                 @param mesh: the mesh object to return (optional: default mesh = 0)
 346                 @rtype: L{KX_MeshProxy}
 347                 @return: the first mesh object associated with this game object, or None if this object has no meshs.
 348                 """
 349         def getPhysicsId():
 350                 """
 351                 Returns the user data object associated with this game object's physics controller.
 352                 """
 353         def getPropertyNames():
 354                 """
 355                 Gets a list of all property names.
 356                 @rtype: list
 357                 @return: All property names for this object.
 358                 """
 359         def getDistanceTo(other):
 360                 """
 361                 Returns the distance to another object or point.
 362
 363                 @param other: a point or another L{KX_GameObject} to measure the distance to.
 364                 @type other: L{KX_GameObject} or list [x, y, z]
 365                 @rtype: float
 366                 """
 367         def getVectTo(other):
 368                 """
 369                 Returns the vector and the distance to another object or point.
 370                 The vector is normalized unless the distance is 0, in which a NULL vector is returned.
 371
 372                 @param other: a point or another L{KX_GameObject} to get the vector and distance to.
 373                 @type other: L{KX_GameObject} or list [x, y, z]
 374                 @rtype: 3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z))
 375                 @return: (distance, globalVector(3), localVector(3))
 376                 """
 377         def rayCastTo(other,dist,prop):
 378                 """
 379                 Look towards another point/object and find first object hit within dist that matches prop.
 380
 381                 The ray is always casted from the center of the object, ignoring the object itself.
 382                 The ray is casted towards the center of another object or an explicit [x,y,z] point.
 383                 Use rayCast() if you need to retrieve the hit point
 384
 385                 @param other: [x,y,z] or object towards which the ray is casted
 386                 @type other: L{KX_GameObject} or 3-tuple
 387                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
 388                 @type dist: float
 389                 @param prop: property name that object must have; can be omitted => detect any object
 390                 @type prop: string
 391                 @rtype: L{KX_GameObject}
 392                 @return: the first object hit or None if no object or object does not match prop
 393                 """
 394         def rayCast(objto,objfrom,dist,prop,face,xray,poly):
 395                 """
 396                 Look from a point/object to another point/object and find first object hit within dist that matches prop.
 397                 if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit.
 398                 if poly is 1, returns a 4-tuple with in addition a L{KX_PolyProxy} as 4th element.
 399
 400                 Ex::
 401                         # shoot along the axis gun-gunAim (gunAim should be collision-free)
 402                         ob,point,normal = gun.rayCast(gunAim,None,50)
 403                         if ob:
 404                                 # hit something
 405
 406                 Notes:
 407                 The ray ignores the object on which the method is called.
 408                 It is casted from/to object center or explicit [x,y,z] points.
 409
 410                 The face paremeter determines the orientation of the normal::
 411                   0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
 412                   1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
 413
 414                 The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
 415                 The prop and xray parameters interact as follow::
 416                     prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
 417                     prop off, xray on : idem.
 418                     prop on,  xray off: return closest hit if it matches prop, no hit otherwise.
 419                     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.
 420                 The L{KX_PolyProxy} 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray.
 421                 If there is no hit or the hit object is not a static mesh, None is returned as 4th element.
 422
 423                 The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
 424
 425                 @param objto: [x,y,z] or object to which the ray is casted
 426                 @type objto: L{KX_GameObject} or 3-tuple
 427                 @param objfrom: [x,y,z] or object from which the ray is casted; None or omitted => use self object center
 428                 @type objfrom: L{KX_GameObject} or 3-tuple or None
 429                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
 430                 @type dist: float
 431                 @param prop: property name that object must have; can be omitted => detect any object
 432                 @type prop: string
 433                 @param face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
 434                 @type face: int
 435                 @param xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
 436                 @type xray: int
 437                 @param poly: polygon option: 1=>return value is a 4-tuple and the 4th element is a L{KX_PolyProxy}
 438                 @type poly: int
 439                 @rtype:    3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz))
 440                         or 4-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), L{KX_PolyProxy})
 441                 @return: (object,hitpoint,hitnormal) or (object,hitpoint,hitnormal,polygon)
 442                          If no hit, returns (None,None,None) or (None,None,None,None)
 443                          If the object hit is not a static mesh, polygon is None
 444                 """
 445         def setCollisionMargin(margin):
 446                 """
 447                 Set the objects collision margin.
 448
 449                 note: If this object has no physics controller (a physics ID of zero), this function will raise RuntimeError.
 450
 451                 @type margin: float
 452                 @param margin: the collision margin distance in blender units.
 453                 """