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