soc-2008-mxcurioni: merged changes to revision 15441
[blender-staging.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 getAxisVect(vect):
82                 """
83                 Returns the axis vector rotates by the objects worldspace orientation.
84                 This is the equivalent if multiplying the vector by the orientation matrix.
85                 
86                 @type vect: 3d vector.
87                 @param vect: a vector to align the axis.
88                 @rtype: 3d vector.
89                 @return: The vector in relation to the objects rotation.
90
91                 """
92         def getOrientation():
93                 """
94                 Gets the game object's orientation.
95                 
96                 @rtype: 3x3 rotation matrix
97                 @return: The game object's rotation matrix
98                 @note: When using this matrix with Blender.Mathutils.Matrix() types, it will need to be transposed.
99                 """
100         def getLinearVelocity(local = 0):
101                 """
102                 Gets the game object's linear velocity.
103                 
104                 This method returns the game object's velocity through it's centre of mass,
105                 ie no angular velocity component.
106                 
107                 @type local: boolean
108                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
109                               - True: you get the "local" velocity ie: relative to object orientation.
110                 @rtype: list [vx, vy, vz]
111                 @return: the object's linear velocity.
112                 """
113         def setLinearVelocity(velocity, local = 0):
114                 """
115                 Sets the game object's linear velocity.
116                 
117                 This method sets game object's velocity through it's centre of mass,
118                 ie no angular velocity component.
119                 
120                 @type velocity: 3d vector.
121                 @param velocity: linear velocity vector.
122                 @type local: boolean
123                 @param local: - False: you get the "global" velocity ie: relative to world orientation (default).
124                               - True: you get the "local" velocity ie: relative to object orientation.
125                 """
126         def getVelocity(point):
127                 """
128                 Gets the game object's velocity at the specified point.
129                 
130                 Gets the game object's velocity at the specified point, including angular
131                 components.
132                 
133                 @type point: list [x, y, z]
134                 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])
135                 @rtype: list [vx, vy, vz]
136                 @return: the velocity at the specified point.
137                 """
138         def getMass():
139                 """
140                 Gets the game object's mass.
141                 
142                 @rtype: float
143                 @return: the object's mass.
144                 """
145         def getReactionForce():
146                 """
147                 Gets the game object's reaction force.
148                 
149                 The reaction force is the force applied to this object over the last simulation timestep.
150                 This also includes impulses, eg from collisions.
151                 
152                 @rtype: list [fx, fy, fz]
153                 @return: the reaction force of this object.
154                 """
155         def applyImpulse(point, impulse):
156                 """
157                 Applies an impulse to the game object.
158                 
159                 This will apply the specified impulse to the game object at the specified point.
160                 If point != getPosition(), applyImpulse will also change the object's angular momentum.
161                 Otherwise, only linear momentum will change.
162                 
163                 @type point: list [x, y, z]
164                 @param point: the point to apply the impulse to (in world coordinates)
165                 """
166         def suspendDynamics():
167                 """
168                 Suspends physics for this object.
169                 """
170         def restoreDynamics():
171                 """
172                 Resumes physics for this object.
173                 @Note: The objects linear velocity will be applied from when the dynamics were suspended.
174                 """
175         def enableRigidBody():
176                 """
177                 Enables rigid body physics for this object.
178                 
179                 Rigid body physics allows the object to roll on collisions.
180                 @Note: This is not working with bullet physics yet.
181                 """
182         def disableRigidBody():
183                 """
184                 Disables rigid body physics for this object.
185                 @Note: This is not working with bullet physics yet. The angular is removed but rigid body physics can still rotate it later.
186                 """
187         def getParent():
188                 """
189                 Gets this object's parent.
190                 
191                 @rtype: L{KX_GameObject}
192                 @return: this object's parent object, or None if this object has no parent.
193                 """
194         def setParent(parent):
195                 """
196                 Sets this object's parent.
197                 
198                 @type parent: L{KX_GameObject}
199                 @param parent: new parent object.
200                 """
201         def removeParent():
202                 """
203                 Removes this objects parent.
204                 """
205         def getMesh(mesh):
206                 """
207                 Gets the mesh object for this object.
208                 
209                 @type mesh: integer
210                 @param mesh: the mesh object to return (optional: default mesh = 0)
211                 @rtype: L{KX_MeshProxy}
212                 @return: the first mesh object associated with this game object, or None if this object has no meshs.
213                 """
214         def getPhysicsId():
215                 """
216                 Returns the user data object associated with this game object's physics controller.
217                 """
218         def getPropertyNames():
219                 """
220                 Gets a list of all property names.
221                 @rtype: list
222                 @return: All property names for this object.
223                 """
224         def getDistanceTo(other):
225                 """
226                 Returns the distance to another object or point.
227                 
228                 @param other: a point or another L{KX_GameObject} to measure the distance to.
229                 @type other: L{KX_GameObject} or list [x, y, z]
230                 @rtype: float
231                 """
232         def rayCastTo(other,dist,prop):
233                 """
234                 Look towards another point/object and find first object hit within dist that matches prop.
235
236                 The ray is always casted from the center of the object, ignoring the object itself.
237                 The ray is casted towards the center of another object or an explicit [x,y,z] point.
238                 Use rayCast() if you need to retrieve the hit point 
239
240                 @param other: [x,y,z] or object towards which the ray is casted
241                 @type other: L{KX_GameObject} or 3-tuple
242                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to other
243                 @type dist: float
244                 @param prop: property name that object must have; can be omitted => detect any object
245                 @type prop: string
246                 @rtype: L{KX_GameObject}
247                 @return: the first object hit or None if no object or object does not match prop
248                 """
249         def rayCast(to,from,dist,prop):
250                 """
251                 Look from a point/object to another point/object and find first object hit within dist that matches prop.
252                 Returns a 3-tuple with object reference, hit point and hit normal or (None,None,None) if no hit.
253                 Ex:
254                         # shoot along the axis gun-gunAim (gunAim should be collision-free)
255                         ob,point,normal = gun.rayCast(gunAim,None,50)
256                         if ob:
257                                 # hit something
258
259                 Notes:                          
260                 The ray ignores the object on which the method is called.
261                 If is casted from/to object center or explicit [x,y,z] points.
262                 The ray does not have X-Ray capability: the first object hit (other than self object) stops the ray
263                 If a property was specified and the first object hit does not have that property, there is no hit
264                 The     ray ignores collision-free objects and faces that dont have the collision flag enabled, you can however use ghost objects.
265
266                 @param to: [x,y,z] or object to which the ray is casted
267                 @type to: L{KX_GameObject} or 3-tuple
268                 @param from: [x,y,z] or object from which the ray is casted; None or omitted => use self object center
269                 @type from: L{KX_GameObject} or 3-tuple or None
270                 @param dist: max distance to look (can be negative => look behind); 0 or omitted => detect up to to
271                 @type dist: float
272                 @param prop: property name that object must have; can be omitted => detect any object
273                 @type prop: string
274                 @rtype: 3-tuple (L{KX_GameObject}, 3-tuple (x,y,z), 3-tuple (nx,ny,nz))
275                 @return: (object,hitpoint,hitnormal) or (None,None,None)
276                 """
277