f158b41097534d9829eecc7c86ced84318ea87eb
[blender.git] / source / gameengine / PyDoc / GameLogic.py
1 # $Id$
2 """
3 Documentation for the GameLogic Module.
4 =======================================
5
6         There are only three importable modules in the game engine:
7                 - GameLogic
8                 - L{GameKeys}
9                 - L{Rasterizer}
10         
11         All the other modules are accessible through the methods in GameLogic.
12         
13         See L{WhatsNew} for updates, changes and new functionality in the Game Engine Python API.
14         
15         Examples::
16                 # To get the controller thats running this python script:
17                 co = GameLogic.getCurrentController() # GameLogic is automatically imported
18                 
19                 # To get the game object this controller is on:
20                 obj = co.getOwner()
21         L{KX_GameObject} and L{KX_Camera} or L{KX_Light} methods are
22         available depending on the type of object::
23                 # To get a sensor linked to this controller.
24                 # "sensorname" is the name of the sensor as defined in the Blender interface.
25                 # +---------------------+  +--------+
26                 # | Sensor "sensorname" +--+ Python +
27                 # +---------------------+  +--------+
28                 sens = co.getSensor("sensorname")
29         
30                 # To get a list of all sensors:
31                 sensors = co.getSensors()
32
33         See the sensor's reference for available methods:
34                 - L{DelaySensor<SCA_DelaySensor.SCA_DelaySensor>}
35                 - L{JoystickSensor<SCA_JoystickSensor.SCA_JoystickSensor>}
36                 - L{KeyboardSensor<SCA_KeyboardSensor.SCA_KeyboardSensor>}
37                 - L{MouseFocusSensor<KX_MouseFocusSensor.KX_MouseFocusSensor>}
38                 - L{MouseSensor<SCA_MouseSensor.SCA_MouseSensor>}
39                 - L{NearSensor<KX_NearSensor.KX_NearSensor>}
40                 - L{NetworkMessageSensor<KX_NetworkMessageSensor.KX_NetworkMessageSensor>}
41                 - L{PropertySensor<SCA_PropertySensor.SCA_PropertySensor>}
42                 - L{RadarSensor<KX_RadarSensor.KX_RadarSensor>}
43                 - L{RandomSensor<SCA_RandomSensor.SCA_RandomSensor>}
44                 - L{RaySensor<KX_RaySensor.KX_RaySensor>}
45                 - L{TouchSensor<KX_TouchSensor.KX_TouchSensor>}
46         
47         You can also access actuators linked to the controller::
48                 # To get an actuator attached to the controller:
49                 #                          +--------+  +-------------------------+
50                 #                          + Python +--+ Actuator "actuatorname" |
51                 #                          +--------+  +-------------------------+
52                 actuator = co.getActuator("actuatorname")
53                 
54                 # Activate an actuator
55                 GameLogic.addActiveActuator(actuator, True)
56                 
57         See the actuator's reference for available methods:
58                 - L{ActionActuator<BL_ActionActuator.BL_ActionActuator>}
59                 - L{AddObjectActuator<KX_SCA_AddObjectActuator.KX_SCA_AddObjectActuator>}
60                 - L{CameraActuator<KX_CameraActuator.KX_CameraActuator>}
61                 - L{CDActuator<KX_CDActuator.KX_CDActuator>}
62                 - L{ConstraintActuator<KX_ConstraintActuator.KX_ConstraintActuator>}
63                 - L{EndObjectActuator<KX_SCA_EndObjectActuator.KX_SCA_EndObjectActuator>}
64                 - L{GameActuator<KX_GameActuator.KX_GameActuator>}
65                 - L{IpoActuator<KX_IpoActuator.KX_IpoActuator>}
66                 - L{NetworkMessageActuator<KX_NetworkMessageActuator.KX_NetworkMessageActuator>}
67                 - L{ObjectActuator<KX_ObjectActuator.KX_ObjectActuator>}
68                 - L{PropertyActuator<SCA_PropertyActuator.SCA_PropertyActuator>}
69                 - L{RandomActuator<SCA_RandomActuator.SCA_RandomActuator>}
70                 - L{ReplaceMeshActuator<KX_SCA_ReplaceMeshActuator.KX_SCA_ReplaceMeshActuator>}
71                 - L{SceneActuator<KX_SceneActuator.KX_SceneActuator>}
72                 - L{SoundActuator<KX_SoundActuator.KX_SoundActuator>}
73                 - L{TrackToActuator<KX_TrackToActuator.KX_TrackToActuator>}
74                 - L{VisibilityActuator<KX_VisibilityActuator.KX_VisibilityActuator>}
75                 - L{DynamicActuator<KX_SCA_DynamicActuator.KX_SCA_DynamicActuator>}
76         
77         Most logic brick's methods are accessors for the properties available in the logic buttons.
78         Consult the logic bricks documentation for more information on how each logic brick works.
79         
80         There are also methods to access the current L{KX_Scene}::
81                 # Get the current scene
82                 scene = GameLogic.getCurrentScene()
83                 
84                 # Get the current camera
85                 cam = scene.active_camera
86
87         Matricies as used by the game engine are B{row major}::
88                 matrix[row][col] = blah
89         L{KX_Camera} has some examples using matricies.
90
91
92 @group Constants: KX_TRUE, KX_FALSE
93 @var KX_TRUE: True value used by some modules.
94 @var KX_FALSE: False value used by some modules.
95
96 @group Property Sensor: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL, KX_PROPSENSOR_INTERVAL, KX_PROPSENSOR_CHANGED, KX_PROPSENSOR_EXPRESSION
97 @var KX_PROPSENSOR_EQUAL:               Activate when the property is equal to the sensor value.
98 @var KX_PROPSENSOR_NOTEQUAL:    Activate when the property is not equal to the sensor value.
99 @var KX_PROPSENSOR_INTERVAL:    Activate when the property is between the specified limits.
100 @var KX_PROPSENSOR_CHANGED:     Activate when the property changes
101 @var KX_PROPSENSOR_EXPRESSION:  Activate when the expression matches
102
103 @group Constraint Actuator: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ
104 @var KX_CONSTRAINTACT_LOCX: See L{KX_ConstraintActuator}
105 @var KX_CONSTRAINTACT_LOCY: See L{KX_ConstraintActuator}
106 @var KX_CONSTRAINTACT_LOCZ: See L{KX_ConstraintActuator}
107 @var KX_CONSTRAINTACT_ROTX: See L{KX_ConstraintActuator}
108 @var KX_CONSTRAINTACT_ROTY: See L{KX_ConstraintActuator}
109 @var KX_CONSTRAINTACT_ROTZ: See L{KX_ConstraintActuator}
110
111 @group IPO Actuator: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
112 @var KX_IPOACT_PLAY:     See L{KX_IpoActuator}
113 @var KX_IPOACT_PINGPONG:         See L{KX_IpoActuator}
114 @var KX_IPOACT_FLIPPER:  See L{KX_IpoActuator}
115 @var KX_IPOACT_LOOPSTOP:         See L{KX_IpoActuator}
116 @var KX_IPOACT_LOOPEND:  See L{KX_IpoActuator}
117
118 @group Random Distributions: KX_RANDOMACT_BOOL_CONST, KX_RANDOMACT_BOOL_UNIFORM, KX_RANDOMACT_BOOL_BERNOUILLI, KX_RANDOMACT_INT_CONST, KX_RANDOMACT_INT_UNIFORM, KX_RANDOMACT_INT_POISSON, KX_RANDOMACT_FLOAT_CONST, KX_RANDOMACT_FLOAT_UNIFORM, KX_RANDOMACT_FLOAT_NORMAL, KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL
119 @var KX_RANDOMACT_BOOL_CONST:           See L{SCA_RandomActuator}
120 @var KX_RANDOMACT_BOOL_UNIFORM:         See L{SCA_RandomActuator}
121 @var KX_RANDOMACT_BOOL_BERNOUILLI:              See L{SCA_RandomActuator}
122 @var KX_RANDOMACT_INT_CONST:            See L{SCA_RandomActuator}
123 @var KX_RANDOMACT_INT_UNIFORM:          See L{SCA_RandomActuator}
124 @var KX_RANDOMACT_INT_POISSON:          See L{SCA_RandomActuator}
125 @var KX_RANDOMACT_FLOAT_CONST:          See L{SCA_RandomActuator}
126 @var KX_RANDOMACT_FLOAT_UNIFORM:                See L{SCA_RandomActuator}
127 @var KX_RANDOMACT_FLOAT_NORMAL:         See L{SCA_RandomActuator}
128 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL:           See L{SCA_RandomActuator}
129
130 @group Action Actuator: KX_ACTIONACT_PLAY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND, KX_ACTIONACT_PROPERTY
131 @var KX_ACTIONACT_PLAY:     See L{BL_ActionActuator}
132 @var KX_ACTIONACT_FLIPPER:  See L{BL_ActionActuator}
133 @var KX_ACTIONACT_LOOPSTOP: See L{BL_ActionActuator}
134 @var KX_ACTIONACT_LOOPEND:  See L{BL_ActionActuator}
135 @var KX_ACTIONACT_PROPERTY: See L{BL_ActionActuator}
136
137 @group Sound Actuator: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
138 @var KX_SOUNDACT_PLAYSTOP:                  See L{KX_SoundActuator}
139 @var KX_SOUNDACT_PLAYEND:                   See L{KX_SoundActuator}
140 @var KX_SOUNDACT_LOOPSTOP:                  See L{KX_SoundActuator}
141 @var KX_SOUNDACT_LOOPEND:                   See L{KX_SoundActuator}
142 @var KX_SOUNDACT_LOOPBIDIRECTIONAL:         See L{KX_SoundActuator}
143 @var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP:    See L{KX_SoundActuator}
144
145 @group Radar Sensor: KX_RADAR_AXIS_POS_X, KX_RADAR_AXIS_POS_Y, KX_RADAR_AXIS_POS_Z, KX_RADAR_AXIS_NEG_X, KX_RADAR_AXIS_NEG_Y, KX_RADAR_AXIS_NEG_Z
146 @var KX_RADAR_AXIS_POS_X:                   See L{KX_RadarSensor}
147 @var KX_RADAR_AXIS_POS_Y:                   See L{KX_RadarSensor}
148 @var KX_RADAR_AXIS_POS_Z:                   See L{KX_RadarSensor}
149 @var KX_RADAR_AXIS_NEG_X:                   See L{KX_RadarSensor}
150 @var KX_RADAR_AXIS_NEG_Y:                   See L{KX_RadarSensor}
151 @var KX_RADAR_AXIS_NEG_Z:                   See L{KX_RadarSensor}
152
153 @group Ray Sensor: KX_RAY_AXIS_POS_X, KX_RAY_AXIS_POS_Y, KX_RAY_AXIS_POS_Z, KX_RAY_AXIS_NEG_X, KX_RAY_AXIS_NEG_Y, KX_RAY_AXIS_NEG_Z
154 @var KX_RAY_AXIS_POS_X:             See L{KX_RaySensor}
155 @var KX_RAY_AXIS_POS_Y:             See L{KX_RaySensor}
156 @var KX_RAY_AXIS_POS_Z:             See L{KX_RaySensor}
157 @var KX_RAY_AXIS_NEG_X:             See L{KX_RaySensor}
158 @var KX_RAY_AXIS_NEG_Y:             See L{KX_RaySensor}
159 @var KX_RAY_AXIS_NEG_Z:             See L{KX_RaySensor}
160
161 @group Dynamic Actuator: KX_DYN_RESTORE_DYNAMICS, KX_DYN_DISABLE_DYNAMICS, KX_DYN_ENABLE_RIGID_BODY, KX_DYN_DISABLE_RIGID_BODY, KX_DYN_SET_MASS
162 @var KX_DYN_RESTORE_DYNAMICS:   See L{KX_SCA_DynamicActuator}
163 @var KX_DYN_DISABLE_DYNAMICS:   See L{KX_SCA_DynamicActuator}
164 @var KX_DYN_ENABLE_RIGID_BODY:  See L{KX_SCA_DynamicActuator}
165 @var KX_DYN_DISABLE_RIGID_BODY: See L{KX_SCA_DynamicActuator}
166 @var KX_DYN_SET_MASS:                   See L{KX_SCA_DynamicActuator}
167
168 """
169
170
171 def getCurrentController():
172         """
173         Gets the Python controller associated with this Python script.
174         
175         @rtype: L{SCA_PythonController}
176         """
177 def getCurrentScene():
178         """
179         Gets the current Scene.
180         
181         @rtype: L{KX_Scene}
182         """
183 def addActiveActuator(actuator, activate):
184         """
185         Activates the given actuator.
186         
187         @type actuator: L{SCA_IActuator} or the actuator name as a string.
188         @type activate: boolean
189         @param activate: whether to activate or deactivate the given actuator.
190         """
191 def getRandomFloat():
192         """
193         Returns a random floating point value in the range [0...1)
194         """
195 def setGravity(gravity):
196         """
197         Sets the world gravity.
198         
199         @type gravity: list [fx, fy, fz]
200         """
201 def getSpectrum():
202         """
203         Returns a 512 point list from the sound card.
204         This only works if the fmod sound driver is being used.
205         
206         @rtype: list [float], len(getSpectrum()) == 512
207         """
208 def stopDSP():
209         """
210         Stops the sound driver using DSP effects.
211         
212         Only the fmod sound driver supports this.
213         DSP can be computationally expensive.
214         """
215 def getLogicTicRate():
216         """
217         Gets the logic update frequency.
218         
219         @return: The logic frequency in Hz
220         @rtype: float
221         """
222 def setLogicTicRate(ticrate):
223         """
224         Sets the logic update frequency.
225         
226         The logic update frequency is the number of times logic bricks are executed every second.
227         The default is 30 Hz.
228         
229         @param ticrate: The new logic update frequency (in Hz).
230         @type ticrate: float
231         """
232 def getPhysicsTicRate():
233         """
234         Gets the physics update frequency
235         
236         @return: The physics update frequency in Hz
237         @rtype: float
238         """
239 def setPhysicsTicRate(ticrate):
240         """
241         Sets the physics update frequency
242         
243         The physics update frequency is the number of times the physics system is executed every second.
244         The default is 60 Hz.
245         
246         @param ticrate: The new update frequency (in Hz).
247         @type ticrate: float
248         """
249 def getAverageFrameRate():
250         """
251         Gets the estimated average framerate
252         
253         @return: The estimed average framerate in frames per second
254         @rtype: float
255         """
256
257 def expandPath(path):
258         """
259         Converts a blender internal path into a proper file system path.
260
261         Use / as directory separator in path
262         You can use '//' at the start of the string to define a relative path;
263         Blender replaces that string by the directory of the startup .blend or runtime file
264         to make a full path name (doesn't change during the game, even if you load other .blend).
265         The function also converts the directory separator to the local file system format.
266
267         @param path: The path string to be converted/expanded.
268         @type path: string
269         @return: The converted string
270         @rtype: string
271         """
272
273 def getBlendFileList(path = "//"):
274         """
275         Returns a list of blend files in the same directory as the open blend file, or from using the option argument.
276
277         @param path: Optional directory argument, will be expanded (like expandPath) into the full path.
278         @type path: string
279         @return: A list of filenames, with no directory prefix
280         @rtype: list
281         """