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