BGE patch: KX_GameObject::rayCast() improvements to have X-Ray option, return true...
[blender.git] / source / gameengine / PyDoc / KX_GameObject.py
1 # $Id$
2 # Documentation for game objects
3
4 class 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(visible):
34                 """
35                 Gets the game object's visible flag.
36                 
37                 @type visible: 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():
53                 """
54                 Sets the game object's visible 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 visible: boolean
58                 """
59         def setPosition(pos):
60                 """
61                 Sets the game object's position.
62                 
63                 @type pos: [x, y, z]
64                 @param pos: the new position, in world coordinates.
65                 """
66         def getPosition():
67                 """
68                 Gets the game object's position.
69                 
70                 @rtype: list [x, y, z]
71                 @return: the object's position in world coordinates.
72                 """
73         def setOrientation(orn):
74                 """
75                 Sets the game object's orientation.
76                 
77                 @type orn: 3x3 rotation matrix, or Quaternion.
78                 @param orn: a rotation matrix specifying the new rotation.
79                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
80                 """
81         def alignAxisToVect(vect, axis):
82                 """
83                 Aligns any of the game object's axis along the given vector.
84                 
85                 @type vect: 3d vector.
86                 @param vect: a vector to align the axis.
87                 @type axis: integer.
88                 @param axis:The axis you want to align
89                                         - 0: X axis
90                                         - 1: Y axis
91                                         - 2: Z axis (default) 
92                 """
93         def getAxisVect(vect):
94                 """
95                 Returns the axis vector rotates by the objects worldspace orientation.
96                 This is the equivalent if multiplying the vector by the orientation matrix.
97                 
98                 @type vect: 3d vector.
99                 @param vect: a vector to align the axis.
100                 @rtype: 3d vector.
101                 @return: The vector in relation to the objects rotation.
102
103                 """
104         def getOrientation():
105                 """
106                 Gets the game object's orientation.
107                 
108                 @rtype: 3x3 rotation matrix
109                 @return: The game object's rotation matrix
110                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
111                 """
112         def getLinearVelocity(local = 0):
113                 """
114                 Gets the game object's linear velocity.
115                 
116                 This method returns the game object's velocity through it's centre of mass,
117                 ie no angular velocity component.
118                 
119                 @type local: boolean
120                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
121                               - True: you get the "local" velocity ie: relative to object orientation.
122                 @rtype: list [vx, vy, vz]
123                 @return: the object's linear velocity.
124                 """
125         def setLinearVelocity(velocity, local = 0):
126                 """
127                 Sets the game object's linear velocity.
128                 
129                 This method sets game object's velocity through it's centre of mass,
130                 ie no angular velocity component.
131                 
132                 @type velocity: 3d vector.
133                 @param velocity: linear velocity vector.
134                 @type local: boolean
135                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
136                               - True: you get the "local" velocity ie: relative to object orientation.
137                 """
138         def getAngularVelocity(local = 0):
139                 """
140                 Gets the game object's angular velocity.
141                 
142                 @type local: boolean
143                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
144                               - True: you get the "local" velocity ie: relative to object orientation.
145                 @rtype: list [vx, vy, vz]
146                 @return: the object's angular velocity.
147                 """
148         def setAngularVelocity(velocity, local = 0):
149                 """
150                 Sets the game object's angular velocity.
151                 
152                 @type velocity: 3d vector.
153                 @param velocity: angular velocity vector.
154                 @type local: boolean
155                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
156                               - True: you get the "local" velocity ie: relative to object orientation.
157                 """
158         def getVelocity(point):
159                 """
160                 Gets the game object's velocity at the specified point.
161                 
162                 Gets the game object's velocity at the specified point, including angular
163                 components.
164                 
165                 @type point: list [x, y, z]
166                 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])
167                 @rtype: list [vx, vy, vz]
168                 @return: the velocity at the specified point.
169                 """
170         def getMass():
171                 """
172                 Gets the game object's mass.
173                 
174                 @rtype: float
175                 @return: the object's mass.
176                 """
177         def getReactionForce():
178                 """
179                 Gets the game object's reaction force.
180                 
181                 The reaction force is the force applied to this object over the last simulation timestep.
182                 This also includes impulses, eg from collisions.
183                 
184                 @rtype: list [fx, fy, fz]
185                 @return: the reaction force of this object.
186                 """
187         def applyImpulse(point, impulse):
188                 """
189                 Applies an impulse to the game object.
190                 
191                 This will apply the specified impulse to the game object at the specified point.
192                 If point != getPosition(), applyImpulse will also change the object's angular momentum.
193                 Otherwise, only linear momentum will change.
194                 
195                 @type point: list [x, y, z]
196                 @param point: the point to apply the impulse to (in world coordinates)
197                 """
198         def suspendDynamics():
199                 """
200                 Suspends physics for this object.
201                 """
202         def restoreDynamics():
203                 """
204                 Resumes physics for this object.
205                 @Note: The objects linear velocity will be applied from when the dynamics were suspended.
206                 """
207         def enableRigidBody():
208                 """
209                 Enables rigid body physics for this object.
210                 
211                 Rigid body physics allows the object to roll on collisions.
212                 @Note: This is not working with bullet physics yet.
213                 """
214         def disableRigidBody():
215                 """
216                 Disables rigid body physics for this object.
217                 @Note: This is not working with bullet physics yet. The angular is removed but rigid body physics can still rotate it later.
218                 """
219         def getParent():
220                 """
221                 Gets this object's parent.
222                 
223                 @rtype: L{KX_GameObject}
224                 @return: this object's parent object, or None if this object has no parent.
225                 """
226         def setParent(parent):
227                 """
228                 Sets this object's parent.
229                 
230                 @type parent: L{KX_GameObject}
231                 @param parent: new parent object.
232                 """
233         def removeParent():
234                 """
235                 Removes this objects parent.
236                 """
237         def getChildren():
238                 """
239                 Return a list of immediate children of this object.
240                 @rtype: list
241                 @return: a list of all this objects children.
242                 """
243         def getChildrenRecursive():
244                 """
245                 Return a list of children of this object, including all their childrens children.
246                 @rtype: list
247                 @return: a list of all this objects children recursivly.
248                 """
249         def getMesh(mesh):
250                 """
251                 Gets the mesh object for this object.
252                 
253                 @type mesh: integer
254                 @param mesh: the mesh object to return (optional: default mesh = 0)
255                 @rtype: L{KX_MeshProxy}
256                 @return: the first mesh object associated with this game object, or None if this object has no meshs.
257                 """
258         def getPhysicsId():
259                 """
260                 Returns the user data object associated with this game object's physics controller.
261                 """
262         def getPropertyNames():
263                 """
264                 Gets a list of all property names.
265                 @rtype: list
266                 @return: All property names for this object.
267                 """
268         def getDistanceTo(other):
269                 """
270                 Returns the distance to another object or point.
271                 
272                 @param other: a point or another L{KX_GameObject} to measure the distance to.
273                 @type other: L{KX_GameObject} or list [x, y, z]
274                 @rtype: float
275                 """
276         def getVectTo(other):
277                 """
278                 Returns the vector and the distance to another object or point.
279                 The vector is normalized unless the distance is 0, in which a NULL vector is returned.
280                 
281                 @param other: a point or another L{KX_GameObject} to get the vector and distance to.
282                 @type other: L{KX_GameObject} or list [x, y, z]
283                 @rtype: 3-tuple (float, 3-tuple (x,y,z), 3-tuple (x,y,z))
284                 @return: (distance, globalVector(3), localVector(3))
285                 """
286         def rayCastTo(other,dist,prop):
287                 """
288                 Look towards another point/object and find first object hit within dist that matches prop.
289
290                 The ray is always casted from the center of the object, ignoring the object itself.
291                 The ray is casted towards the center of another object or an explicit [x,y,z] point.
292                 Use rayCast() if you need to retrieve the hit point 
293
294                 @param other: [x,y,z] or object towards which the ray is casted
295                 @type other: L{KX_GameObject} or 3-tuple
296                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
297                 @type dist: float
298                 @param prop: property name that object must have; can be omitted => detect any object
299                 @type prop: string
300                 @rtype: L{KX_GameObject}
301                 @return: the first object hit or None if no object or object does not match prop
302                 """
303         def rayCast(to,from,dist,prop,face,xray,poly):
304                 """
305                 Look from a point/object to another point/object and find first object hit within dist that matches prop.
306                 if poly is 0, returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit.
307                 if poly is 1, returns a 4-tuple with in addition a L{KX_PolyProxy} as 4th element.
308                 Ex:
309                         # shoot along the axis gun-gunAim (gunAim should be collision-free)
310                         ob,point,normal = gun.rayCast(gunAim,None,50)
311                         if ob:
312                                 # hit something
313
314                 Notes:                          
315                 The ray ignores the object on which the method is called.
316                 It is casted from/to object center or explicit [x,y,z] points.
317                 The face paremeter determines the orientation of the normal: 
318                   0 => hit normal is always oriented towards the ray origin (as if you casted the ray from outside)
319                   1 => hit normal is the real face normal (only for mesh object, otherwise face has no effect)
320                 The ray has X-Ray capability if xray parameter is 1, otherwise the first object hit (other than self object) stops the ray.
321                 The prop and xray parameters interact as follow:
322                     prop off, xray off: return closest hit or no hit if there is no object on the full extend of the ray.
323                     prop off, xray on : idem.
324                     prop on,  xray off: return closest hit if it matches prop, no hit otherwise.
325                     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.
326                 The L{KX_PolyProxy} 4th element of the return tuple when poly=1 allows to retrieve information on the polygon hit by the ray.
327                 If there is no hit or the hit object is not a static mesh, None is returned as 4th element. 
328                 The     ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
329
330                 @param to: [x,y,z] or object to which the ray is casted
331                 @type to: L{KX_GameObject} or 3-tuple
332                 @param from: [x,y,z] or object from which the ray is casted; None or omitted => use self object center
333                 @type from: L{KX_GameObject} or 3-tuple or None
334                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
335                 @type dist: float
336                 @param prop: property name that object must have; can be omitted => detect any object
337                 @type prop: string
338                 @param face: normal option: 1=>return face normal; 0 or omitted => normal is oriented towards origin
339                 @type face: int
340                 @param xray: X-ray option: 1=>skip objects that don't match prop; 0 or omitted => stop on first object
341                 @type xray: int
342                 @param poly: polygon option: 1=>return value is a 4-tuple and the 4th element is a L{KX_PolyProxy}
343                 @type poly: int
344                 @rtype:    3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz))
345                         or 4-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz), L{KX_PolyProxy))
346                 @return: (object,hitpoint,hitnormal) or (object,hitpoint,hitnormal,polygon)
347                          If no hit, returns (None,None,None) or (None,None,None,None)
348                          If the object hit is not a static mesh, polygon is None
349                 """
350
351