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 @ivar timeOffset: adjust the slowparent delay at runtime. 26 @type timeOffset: float 27 """

28 - def endObject(visible):

29 """ 30 Delete this object, can be used inpace of the EndObject Actuator. 31 The actual removal of the object from the scene is delayed. 32 """

33 - def getVisible():

34 """ 35 Gets the game object's visible flag. 36 37 @rtype: boolean 38 """

39 - def setVisible(visible):

40 """ 41 Sets the game object's visible flag. 42 43 @type visible: boolean 44 """

45 - def getState():

46 """ 47 Gets the game object's state bitmask. 48 49 @rtype: int 50 @return: the objects state. 51 """

52 - def setState(state):

53 """ 54 Sets the game object's state flag. 55 The bitmasks for states from 1 to 30 can be set with (1<<0, 1<<1, 1<<2 ... 1<<29) 56 57 @type state: integer 58 """

59 - def setPosition(pos):

60 """ 61 Sets the game object's position. 62 Global coordinates for root object, local for child objects. 63 64 65 @type pos: [x, y, z] 66 @param pos: the new position, in local coordinates. 67 """

68 - def setWorldPosition(pos):

69 """ 70 Sets the game object's position in world coordinates regardless if the object is root or child. 71 72 @type pos: [x, y, z] 73 @param pos: the new position, in world coordinates. 74 """

75 - def getPosition():

76 """ 77 Gets the game object's position. 78 79 @rtype: list [x, y, z] 80 @return: the object's position in world coordinates. 81 """

82 - def setOrientation(orn):

83 """ 84 Sets the game object's orientation. 85 86 @type orn: 3x3 rotation matrix, or Quaternion. 87 @param orn: a rotation matrix specifying the new rotation. 88 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed. 89 """

90 - def alignAxisToVect(vect, axis):

91 """ 92 Aligns any of the game object's axis along the given vector. 93 94 @type vect: 3d vector. 95 @param vect: a vector to align the axis. 96 @type axis: integer. 97 @param axis:The axis you want to align 98 - 0: X axis 99 - 1: Y axis 100 - 2: Z axis (default) 101 """

102 - def getAxisVect(vect):

103 """ 104 Returns the axis vector rotates by the objects worldspace orientation. 105 This is the equivalent if multiplying the vector by the orientation matrix. 106 107 @type vect: 3d vector. 108 @param vect: a vector to align the axis. 109 @rtype: 3d vector. 110 @return: The vector in relation to the objects rotation. 111 112 """

113 - def getOrientation():

114 """ 115 Gets the game object's orientation. 116 117 @rtype: 3x3 rotation matrix 118 @return: The game object's rotation matrix 119 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed. 120 """

121 - def getLinearVelocity(local = 0):

122 """ 123 Gets the game object's linear velocity. 124 125 This method returns the game object's velocity through it's centre of mass, 126 ie no angular velocity component. 127 128 @type local: boolean 129 @param local: - False: you get the "global" velocity ie: relative to world orientation (default). 130 - True: you get the "local" velocity ie: relative to object orientation. 131 @rtype: list [vx, vy, vz] 132 @return: the object's linear velocity. 133 """

134 - def setLinearVelocity(velocity, local = 0):

135 """ 136 Sets the game object's linear velocity. 137 138 This method sets game object's velocity through it's centre of mass, 139 ie no angular velocity component. 140 141 @type velocity: 3d vector. 142 @param velocity: linear velocity vector. 143 @type local: boolean 144 @param local: - False: you get the "global" velocity ie: relative to world orientation (default). 145 - True: you get the "local" velocity ie: relative to object orientation. 146 """

147 - def getAngularVelocity(local = 0):

148 """ 149 Gets the game object's angular velocity. 150 151 @type local: boolean 152 @param local: - False: you get the "global" velocity ie: relative to world orientation (default). 153 - True: you get the "local" velocity ie: relative to object orientation. 154 @rtype: list [vx, vy, vz] 155 @return: the object's angular velocity. 156 """

157 - def setAngularVelocity(velocity, local = 0):

158 """ 159 Sets the game object's angular velocity. 160 161 @type velocity: 3d vector. 162 @param velocity: angular velocity vector. 163 @type local: boolean 164 @param local: - False: you get the "global" velocity ie: relative to world orientation (default). 165 - True: you get the "local" velocity ie: relative to object orientation. 166 """

167 - def getVelocity(point):

168 """ 169 Gets the game object's velocity at the specified point. 170 171 Gets the game object's velocity at the specified point, including angular 172 components. 173 174 @type point: list [x, y, z] 175 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0]) 176 @rtype: list [vx, vy, vz] 177 @return: the velocity at the specified point. 178 """

179 - def getMass():

180 """ 181 Gets the game object's mass. 182 183 @rtype: float 184 @return: the object's mass. 185 """

186 - def getReactionForce():

187 """ 188 Gets the game object's reaction force. 189 190 The reaction force is the force applied to this object over the last simulation timestep. 191 This also includes impulses, eg from collisions. 192 193 @rtype: list [fx, fy, fz] 194 @return: the reaction force of this object. 195 """

196 - def applyImpulse(point, impulse):

197 """ 198 Applies an impulse to the game object. 199 200 This will apply the specified impulse to the game object at the specified point. 201 If point != getPosition(), applyImpulse will also change the object's angular momentum. 202 Otherwise, only linear momentum will change. 203 204 @type point: list [x, y, z] 205 @param point: the point to apply the impulse to (in world coordinates) 206 """

207 - def suspendDynamics():

208 """ 209 Suspends physics for this object. 210 """

211 - def restoreDynamics():

212 """ 213 Resumes physics for this object. 214 @Note: The objects linear velocity will be applied from when the dynamics were suspended. 215 """

216 - def enableRigidBody():

217 """ 218 Enables rigid body physics for this object. 219 220 Rigid body physics allows the object to roll on collisions. 221 @Note: This is not working with bullet physics yet. 222 """

223 - def disableRigidBody():

224 """ 225 Disables rigid body physics for this object. 226 @Note: This is not working with bullet physics yet. The angular is removed but rigid body physics can still rotate it later. 227 """

228 - def getParent():

229 """ 230 Gets this object's parent. 231 232 @rtype: L{KX_GameObject} 233 @return: this object's parent object, or None if this object has no parent. 234 """

235 - def setParent(parent):

236 """ 237 Sets this object's parent. 238 239 @type parent: L{KX_GameObject} 240 @param parent: new parent object. 241 """

242 - def removeParent():

243 """ 244 Removes this objects parent. 245 """

246 - def getChildren():

247 """ 248 Return a list of immediate children of this object. 249 @rtype: list 250 @return: a list of all this objects children. 251 """

252 - def getChildrenRecursive():

253 """ 254 Return a list of children of this object, including all their childrens children. 255 @rtype: list 256 @return: a list of all this objects children recursivly. 257 """

258 - def getMesh(mesh):

259 """ 260 Gets the mesh object for this object. 261 262 @type mesh: integer 263 @param mesh: the mesh object to return (optional: default mesh = 0) 264 @rtype: L{KX_MeshProxy} 265 @return: the first mesh object associated with this game object, or None if this object has no meshs. 266 """

267 - def getPhysicsId():

268 """ 269 Returns the user data object associated with this game object's physics controller. 270 """

271 - def getPropertyNames():

272 """ 273 Gets a list of all property names. 274 @rtype: list 275 @return: All property names for this object. 276 """

277 - def getDistanceTo(other):

278 """ 279 Returns the distance to another object or point. 280 281 @param other: a point or another L{KX_GameObject} to measure the distance to. 282 @type other: L{KX_GameObject} or list [x, y, z] 283 @rtype: float 284 """

285 - def getVectTo(other):

286 """ 287 Returns the vector and the distance to another object or point. 288 The vector is normalized unless the distance is 0, in which a NULL vector is returned. 289 290 @param other: a point or another L{KX_GameObject} to get the vector and distance to. 291 @type other: L{KX_GameObject} or list [x, y, z] 292 @rtype: 3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z)) 293 @return: (distance, globalVector(3), localVector(3)) 294 """

295 - def rayCastTo(other,dist,prop):

296 """ 297 Look towards another point/object and find first object hit within dist that matches prop. 298 299 The ray is always casted from the center of the object, ignoring the object itself. 300 The ray is casted towards the center of another object or an explicit [x,y,z] point. 301 Use rayCast() if you need to retrieve the hit point 302 303 @param other: [x,y,z] or object towards which the ray is casted 304 @type other: L{KX_GameObject} or 3-tuple 305 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other 306 @type dist: float 307 @param prop: property name that object must have; can be omitted => detect any object 308 @type prop: string 309 @rtype: L{KX_GameObject} 310 @return: the first object hit or None if no object or object does not match prop 311 """

312 - def rayCast(objto,objfrom,dist,prop,face,xray,poly):

313 """ 314 Look from a point/object to another point/object and find first object hit within dist that matches prop. 315 if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit. 316 if poly is 1, returns a 4-tuple with in addition a L{KX_PolyProxy} as 4th element. 317 318 Ex:: 319 # shoot along the axis gun-gunAim (gunAim should be collision-free) 320 ob,point,normal = gun.rayCast(gunAim,None,50) 321 if ob: 322 # hit something 323 324 Notes: 325 The ray ignores the object on which the method is called. 326 It is casted from/to object center or explicit [x,y,z] points. 327 328 The face paremeter determines the orientation of the normal:: 329 0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside) 330 1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect) 331 332 The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray. 333 The prop and xray parameters interact as follow:: 334 prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray. 335 prop off, xray on : idem. 336 prop on, xray off: return closest hit if it matches prop, no hit otherwise. 337 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. 338 The L{KX_PolyProxy} 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray. 339 If there is no hit or the hit object is not a static mesh, None is returned as 4th element. 340 341 The ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects. 342 343 @param objto: [x,y,z] or object to which the ray is casted 344 @type objto: L{KX_GameObject} or 3-tuple 345 @param objfrom: [x,y,z] or object from which the ray is casted; None or omitted => use self object center 346 @type objfrom: L{KX_GameObject} or 3-tuple or None 347 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to 348 @type dist: float 349 @param prop: property name that object must have; can be omitted => detect any object 350 @type prop: string 351 @param face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin 352 @type face: int 353 @param xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object 354 @type xray: int 355 @param poly: polygon option: 1=>return value is a 4-tuple and the 4th element is a L{KX_PolyProxy} 356 @type poly: int 357 @rtype: 3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz)) 358 or 4-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), L{KX_PolyProxy}) 359 @return: (object,hitpoint,hitnormal) or (object,hitpoint,hitnormal,polygon) 360 If no hit, returns (None,None,None) or (None,None,None,None) 361 If the object hit is not a static mesh, polygon is None 362 """

Source Code for Module KX_GameObject