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