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