a95e66cee9674adf6715432313419660522e63b2
[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
9         in objects of this class.
10         
11         @ivar mass: The object's mass (provided the object has a physics controller). float. read only
12         @ivar parent: The object's parent object. (Read only)
13         @type parent: KX_GameObject
14         @ivar visible: visibility flag. boolean.
15         @ivar position: The object's position. 
16         @type position: list [x, y, z]
17         @ivar orientation: The object's orientation. 3x3 Matrix.  
18                            You can also write a Quaternion or Euler vector.
19         @type orientation: 3x3 Matrix [[float]]
20         @ivar scaling: The object's scaling factor. list [sx, sy, sz]
21         @type scaling: list [sx, sy, sz]
22         """
23         
24         def setVisible(visible):
25                 """
26                 Sets the game object's visible flag.
27                 
28                 @type visible: boolean
29                 """
30         def setPosition(pos):
31                 """
32                 Sets the game object's position.
33                 
34                 @type pos: [x, y, z]
35                 @param pos: the new position, in world coordinates.
36                 """
37         def getPosition():
38                 """
39                 Gets the game object's position.
40                 
41                 @rtype: list [x, y, z]
42                 @return: the object's position in world coordinates.
43                 """
44         def setOrientation(orn):
45                 """
46                 Sets the game object's orientation.
47                 
48                 @type orn: 3x3 rotation matrix, or Quaternion.
49                 @param orn: a rotation matrix specifying the new rotation.
50                 """
51         def getOrientation():
52                 """
53                 Gets the game object's orientation.
54                 
55                 @rtype: 3x3 rotation matrix
56                 @return: The game object's rotation matrix
57                 """
58         def getLinearVelocity():
59                 """
60                 Gets the game object's linear velocity.
61                 
62                 This method returns the game object's velocity through it's centre of mass,
63                 ie no angular velocity component.
64                 
65                 cf getVelocity()
66                 
67                 @rtype: list [vx, vy, vz]
68                 @return: the object's linear velocity.
69                 """
70         def getVelocity(point):
71                 """
72                 Gets the game object's velocity at the specified point.
73                 
74                 Gets the game object's velocity at the specified point, including angular
75                 components.
76                 
77                 @type point: list [x, y, z]
78                 @param point: the point to return the velocity for, in local coordinates. (optional: default = [0, 0, 0])
79                 @rtype: list [vx, vy, vz]
80                 @return: the velocity at the specified point.
81                 """
82         def getMass():
83                 """
84                 Gets the game object's mass.
85                 
86                 @rtype: float
87                 @return: the object's mass.
88                 """
89         def getReactionForce():
90                 """
91                 Gets the game object's reaction force.
92                 
93                 The reaction force is the force applied to this object over the last simulation timestep.
94                 This also includes impulses, eg from collisions.
95                 
96                 @rtype: list [fx, fy, fz]
97                 @return: the reaction force of this object.
98                 """
99         def applyImpulse(point, impulse):
100                 """
101                 Applies an impulse to the game object.
102                 
103                 This will apply the specified impulse to the game object at the specified point.
104                 If point != getPosition(), applyImpulse will also change the object's angular momentum.
105                 Otherwise, only linear momentum will change.
106                 
107                 @type point: list [x, y, z]
108                 @param point: the point to apply the impulse to (in world coordinates)
109                 """
110         def suspendDynamics():
111                 """
112                 Suspends physics for this object.
113                 """
114         def restoreDynamics():
115                 """
116                 Resumes physics for this object.
117                 """
118         def enableRigidBody():
119                 """
120                 Enables rigid body physics for this object.
121                 
122                 Rigid body physics allows the object to roll on collisions.
123                 """
124         def disableRigidBody():
125                 """
126                 Disables rigid body physics for this object.
127                 """
128         def getParent():
129                 """
130                 Gets this object's parent.
131                 
132                 @rtype: game object
133                 @return: this object's parent object, or None if this object has no parent.
134                 """
135         def getMesh(mesh):
136                 """
137                 Gets the mesh object for this object.
138                 
139                 @type mesh: integer
140                 @param mesh: the mesh object to return (optional: default mesh = 0)
141                 @rtype: mesh object
142                 @return: the first mesh object associated with this game object, or None if this object has no meshs.
143                 """
144         def getPhysicsId():
145                 """
146                 Returns the user data object associated with this game object's physics controller.
147                 """