BGE: GUI control over frame rate, logic rate, physics rate and physics subrate.
[blender.git] / source / gameengine / PyDoc / GameLogic.py
1 # $Id$
2 """
3 Documentation for the GameLogic Module.
4 =======================================
5         
6         Module to access logic functions, imported automatically into the python controllers namespace.
7         
8         Examples::
9                 # To get the controller thats running this python script:
10                 cont = GameLogic.getCurrentController() # GameLogic is automatically imported
11                 
12                 # To get the game object this controller is on:
13                 obj = cont.owner
14         L{KX_GameObject} and L{KX_Camera} or L{KX_LightObject} methods are
15         available depending on the type of object::
16                 # To get a sensor linked to this controller.
17                 # "sensorname" is the name of the sensor as defined in the Blender interface.
18                 # +---------------------+  +--------+
19                 # | Sensor "sensorname" +--+ Python +
20                 # +---------------------+  +--------+
21                 sens = cont.sensors["sensorname"]
22         
23                 # To get a sequence of all sensors:
24                 sensors = co.sensors
25
26         See the sensor's reference for available methods:
27                 - L{DelaySensor<GameTypes.SCA_DelaySensor>}
28                 - L{JoystickSensor<GameTypes.SCA_JoystickSensor>}
29                 - L{KeyboardSensor<GameTypes.SCA_KeyboardSensor>}
30                 - L{MouseFocusSensor<GameTypes.KX_MouseFocusSensor>}
31                 - L{MouseSensor<GameTypes.SCA_MouseSensor>}
32                 - L{NearSensor<GameTypes.KX_NearSensor>}
33                 - L{NetworkMessageSensor<GameTypes.KX_NetworkMessageSensor>}
34                 - L{PropertySensor<GameTypes.SCA_PropertySensor>}
35                 - L{RadarSensor<GameTypes.KX_RadarSensor>}
36                 - L{RandomSensor<GameTypes.SCA_RandomSensor>}
37                 - L{RaySensor<GameTypes.KX_RaySensor>}
38                 - L{TouchSensor<GameTypes.KX_TouchSensor>}
39         
40         You can also access actuators linked to the controller::
41                 # To get an actuator attached to the controller:
42                 #                          +--------+  +-------------------------+
43                 #                          + Python +--+ Actuator "actuatorname" |
44                 #                          +--------+  +-------------------------+
45                 actuator = co.actuators["actuatorname"]
46                 
47                 # Activate an actuator
48                 controller.activate(actuator)
49                 
50         See the actuator's reference for available methods:
51                 - L{2DFilterActuator<GameTypes.SCA_2DFilterActuator>}
52                 - L{ActionActuator<GameTypes.BL_ActionActuator>}
53                 - L{AddObjectActuator<GameTypes.KX_SCA_AddObjectActuator>}
54                 - L{CameraActuator<GameTypes.KX_CameraActuator>}
55                 - L{CDActuator<GameTypes.KX_CDActuator>}
56                 - L{ConstraintActuator<GameTypes.KX_ConstraintActuator>}
57                 - L{DynamicActuator<GameTypes.KX_SCA_DynamicActuator>}
58                 - L{EndObjectActuator<GameTypes.KX_SCA_EndObjectActuator>}
59                 - L{GameActuator<GameTypes.KX_GameActuator>}
60                 - L{IpoActuator<GameTypes.KX_IpoActuator>}
61                 - L{NetworkMessageActuator<GameTypes.KX_NetworkMessageActuator>}
62                 - L{ObjectActuator<GameTypes.KX_ObjectActuator>}
63                 - L{ParentActuator<GameTypes.KX_ParentActuator>}
64                 - L{PropertyActuator<GameTypes.SCA_PropertyActuator>}
65                 - L{RandomActuator<GameTypes.SCA_RandomActuator>}
66                 - L{ReplaceMeshActuator<GameTypes.KX_SCA_ReplaceMeshActuator>}
67                 - L{SceneActuator<GameTypes.KX_SceneActuator>}
68                 - L{ShapeActionActuator<GameTypes.BL_ShapeActionActuator>}
69                 - L{SoundActuator<GameTypes.KX_SoundActuator>}
70                 - L{StateActuator<GameTypes.KX_StateActuator>}
71                 - L{TrackToActuator<GameTypes.KX_TrackToActuator>}
72                 - L{VisibilityActuator<GameTypes.KX_VisibilityActuator>}
73
74         Most logic brick's methods are accessors for the properties available in the logic buttons.
75         Consult the logic bricks documentation for more information on how each logic brick works.
76         
77         There are also methods to access the current L{KX_Scene}::
78                 # Get the current scene
79                 scene = GameLogic.getCurrentScene()
80                 
81                 # Get the current camera
82                 cam = scene.active_camera
83
84         Matricies as used by the game engine are B{row major}::
85                 matrix[row][col] = float
86         L{KX_Camera} has some examples using matricies.
87
88
89 @group Constants: KX_TRUE, KX_FALSE
90 @var KX_TRUE: True value used by some modules.
91 @var KX_FALSE: False value used by some modules.
92
93 @group Property Sensor: KX_PROPSENSOR_*
94 @var KX_PROPSENSOR_EQUAL:               Activate when the property is equal to the sensor value.
95 @var KX_PROPSENSOR_NOTEQUAL:    Activate when the property is not equal to the sensor value.
96 @var KX_PROPSENSOR_INTERVAL:    Activate when the property is between the specified limits.
97 @var KX_PROPSENSOR_CHANGED:     Activate when the property changes
98 @var KX_PROPSENSOR_EXPRESSION:  Activate when the expression matches
99
100 @group Constraint Actuator: KX_CONSTRAINTACT_*
101 @var KX_CONSTRAINTACT_LOCX: See L{KX_ConstraintActuator}
102 @var KX_CONSTRAINTACT_LOCY: See L{KX_ConstraintActuator}
103 @var KX_CONSTRAINTACT_LOCZ: See L{KX_ConstraintActuator}
104 @var KX_CONSTRAINTACT_ROTX: See L{KX_ConstraintActuator}
105 @var KX_CONSTRAINTACT_ROTY: See L{KX_ConstraintActuator}
106 @var KX_CONSTRAINTACT_ROTZ: See L{KX_ConstraintActuator}
107 @var KX_CONSTRAINTACT_DIRNX: See L{KX_ConstraintActuator}
108 @var KX_CONSTRAINTACT_DIRNY: See L{KX_ConstraintActuator}
109 @var KX_CONSTRAINTACT_DIRPX: See L{KX_ConstraintActuator}
110 @var KX_CONSTRAINTACT_DIRPY: See L{KX_ConstraintActuator}
111 @var KX_CONSTRAINTACT_ORIX: See L{KX_ConstraintActuator}
112 @var KX_CONSTRAINTACT_ORIY: See L{KX_ConstraintActuator}
113 @var KX_CONSTRAINTACT_ORIZ: See L{KX_ConstraintActuator}
114
115 @group IPO Actuator: KX_IPOACT_*
116 @var KX_IPOACT_PLAY:     See L{KX_IpoActuator}
117 @var KX_IPOACT_PINGPONG:         See L{KX_IpoActuator}
118 @var KX_IPOACT_FLIPPER:  See L{KX_IpoActuator}
119 @var KX_IPOACT_LOOPSTOP:         See L{KX_IpoActuator}
120 @var KX_IPOACT_LOOPEND:  See L{KX_IpoActuator}
121 @var KX_IPOACT_FROM_PROP:        See L{KX_IpoActuator}
122
123 @group Random Distributions: KX_RANDOMACT_*
124 @var KX_RANDOMACT_BOOL_CONST:           See L{SCA_RandomActuator}
125 @var KX_RANDOMACT_BOOL_UNIFORM:         See L{SCA_RandomActuator}
126 @var KX_RANDOMACT_BOOL_BERNOUILLI:              See L{SCA_RandomActuator}
127 @var KX_RANDOMACT_INT_CONST:            See L{SCA_RandomActuator}
128 @var KX_RANDOMACT_INT_UNIFORM:          See L{SCA_RandomActuator}
129 @var KX_RANDOMACT_INT_POISSON:          See L{SCA_RandomActuator}
130 @var KX_RANDOMACT_FLOAT_CONST:          See L{SCA_RandomActuator}
131 @var KX_RANDOMACT_FLOAT_UNIFORM:                See L{SCA_RandomActuator}
132 @var KX_RANDOMACT_FLOAT_NORMAL:         See L{SCA_RandomActuator}
133 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL:           See L{SCA_RandomActuator}
134
135 @group Action Actuator: KX_ACTIONACT_*
136 @var KX_ACTIONACT_PLAY:     See L{BL_ActionActuator}
137 @var KX_ACTIONACT_FLIPPER:  See L{BL_ActionActuator}
138 @var KX_ACTIONACT_LOOPSTOP: See L{BL_ActionActuator}
139 @var KX_ACTIONACT_LOOPEND:  See L{BL_ActionActuator}
140 @var KX_ACTIONACT_PROPERTY: See L{BL_ActionActuator}
141
142 @group Sound Actuator: KX_SOUNDACT_*
143 @var KX_SOUNDACT_PLAYSTOP:                  See L{KX_SoundActuator}
144 @var KX_SOUNDACT_PLAYEND:                   See L{KX_SoundActuator}
145 @var KX_SOUNDACT_LOOPSTOP:                  See L{KX_SoundActuator}
146 @var KX_SOUNDACT_LOOPEND:                   See L{KX_SoundActuator}
147 @var KX_SOUNDACT_LOOPBIDIRECTIONAL:         See L{KX_SoundActuator}
148 @var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP:    See L{KX_SoundActuator}
149
150 @group Radar Sensor: KX_RADAR_*
151 @var KX_RADAR_AXIS_POS_X:                   See L{KX_RadarSensor}
152 @var KX_RADAR_AXIS_POS_Y:                   See L{KX_RadarSensor}
153 @var KX_RADAR_AXIS_POS_Z:                   See L{KX_RadarSensor}
154 @var KX_RADAR_AXIS_NEG_X:                   See L{KX_RadarSensor}
155 @var KX_RADAR_AXIS_NEG_Y:                   See L{KX_RadarSensor}
156 @var KX_RADAR_AXIS_NEG_Z:                   See L{KX_RadarSensor}
157
158 @group Ray Sensor: KX_RAY_*
159 @var KX_RAY_AXIS_POS_X:             See L{KX_RaySensor}
160 @var KX_RAY_AXIS_POS_Y:             See L{KX_RaySensor}
161 @var KX_RAY_AXIS_POS_Z:             See L{KX_RaySensor}
162 @var KX_RAY_AXIS_NEG_X:             See L{KX_RaySensor}
163 @var KX_RAY_AXIS_NEG_Y:             See L{KX_RaySensor}
164 @var KX_RAY_AXIS_NEG_Z:             See L{KX_RaySensor}
165
166 @group Dynamic Actuator: KX_DYN_*
167 @var KX_DYN_RESTORE_DYNAMICS:   See L{KX_SCA_DynamicActuator}
168 @var KX_DYN_DISABLE_DYNAMICS:   See L{KX_SCA_DynamicActuator}
169 @var KX_DYN_ENABLE_RIGID_BODY:  See L{KX_SCA_DynamicActuator}
170 @var KX_DYN_DISABLE_RIGID_BODY: See L{KX_SCA_DynamicActuator}
171 @var KX_DYN_SET_MASS:                   See L{KX_SCA_DynamicActuator}
172
173 @group Game Actuator: KX_GAME_*
174 @var KX_GAME_LOAD:              See L{KX_GameActuator}
175 @var KX_GAME_START:             See L{KX_GameActuator}
176 @var KX_GAME_RESTART:   See L{KX_GameActuator}
177 @var KX_GAME_QUIT:              See L{KX_GameActuator}
178 @var KX_GAME_SAVECFG:   See L{KX_GameActuator}
179 @var KX_GAME_LOADCFG:   See L{KX_GameActuator}
180
181 @group Scene Actuator: KX_SCENE_*
182 @var KX_SCENE_RESTART:                  See L{KX_SceneActuator}
183 @var KX_SCENE_SET_SCENE:                        See L{KX_SceneActuator}
184 @var KX_SCENE_SET_CAMERA:               See L{KX_SceneActuator}
185 @var KX_SCENE_ADD_FRONT_SCENE:  See L{KX_SceneActuator}
186 @var KX_SCENE_ADD_BACK_SCENE:   See L{KX_SceneActuator}
187 @var KX_SCENE_REMOVE_SCENE:             See L{KX_SceneActuator}
188 @var KX_SCENE_SUSPEND:                  See L{KX_SceneActuator}
189 @var KX_SCENE_RESUME:                   See L{KX_SceneActuator}
190
191 @group Input Status: KX_INPUT_*
192 @var KX_INPUT_NONE:                             See L{SCA_MouseSensor}
193 @var KX_INPUT_JUST_ACTIVATED:   See L{SCA_MouseSensor}
194 @var KX_INPUT_ACTIVE:                   See L{SCA_MouseSensor}
195 @var KX_INPUT_JUST_RELEASED:    See L{SCA_MouseSensor}
196
197
198 @group Mouse Buttons: KX_MOUSE_BUT_*
199 @var KX_MOUSE_BUT_LEFT:         See L{SCA_MouseSensor}
200 @var KX_MOUSE_BUT_MIDDLE:       See L{SCA_MouseSensor}
201 @var KX_MOUSE_BUT_RIGHT:        See L{SCA_MouseSensor}
202
203 @group States: KX_STATE*
204 @var KX_STATE1:
205 @var KX_STATE10:
206 @var KX_STATE11:
207 @var KX_STATE12:
208 @var KX_STATE13:
209 @var KX_STATE14:
210 @var KX_STATE15:
211 @var KX_STATE16:
212 @var KX_STATE17:
213 @var KX_STATE18:
214 @var KX_STATE19:
215 @var KX_STATE2:
216 @var KX_STATE20:
217 @var KX_STATE21:
218 @var KX_STATE22:
219 @var KX_STATE23:
220 @var KX_STATE24:
221 @var KX_STATE25:
222 @var KX_STATE26:
223 @var KX_STATE27:
224 @var KX_STATE28:
225 @var KX_STATE29:
226 @var KX_STATE3:
227 @var KX_STATE30:
228 @var KX_STATE4:
229 @var KX_STATE5:
230 @var KX_STATE6:
231 @var KX_STATE7:
232 @var KX_STATE8:
233 @var KX_STATE9:
234 @var KX_STATE_OP_CLR:
235 @var KX_STATE_OP_CPY:
236 @var KX_STATE_OP_NEG:
237 @var KX_STATE_OP_SET:
238
239 @group 2D Filter: RAS_2DFILTER_*
240 @var RAS_2DFILTER_BLUR:
241 @var RAS_2DFILTER_CUSTOMFILTER:
242 @var RAS_2DFILTER_DILATION:
243 @var RAS_2DFILTER_DISABLED:
244 @var RAS_2DFILTER_ENABLED:
245 @var RAS_2DFILTER_EROSION:
246 @var RAS_2DFILTER_GRAYSCALE:
247 @var RAS_2DFILTER_INVERT:
248 @var RAS_2DFILTER_LAPLACIAN:
249 @var RAS_2DFILTER_MOTIONBLUR:
250 @var RAS_2DFILTER_NOFILTER:
251 @var RAS_2DFILTER_PREWITT:
252 @var RAS_2DFILTER_SEPIA:
253 @var RAS_2DFILTER_SHARPEN:
254 @var RAS_2DFILTER_SOBEL:
255
256 @group Constraint Actuator: KX_ACT_CONSTRAINT_*
257 @var KX_ACT_CONSTRAINT_DISTANCE:
258 @var KX_ACT_CONSTRAINT_DOROTFH:
259 @var KX_ACT_CONSTRAINT_FHNX:
260 @var KX_ACT_CONSTRAINT_FHNY:
261 @var KX_ACT_CONSTRAINT_FHNZ:
262 @var KX_ACT_CONSTRAINT_FHPX:
263 @var KX_ACT_CONSTRAINT_FHPY:
264 @var KX_ACT_CONSTRAINT_FHPZ:
265 @var KX_ACT_CONSTRAINT_LOCAL:
266 @var KX_ACT_CONSTRAINT_MATERIAL:
267 @var KX_ACT_CONSTRAINT_NORMAL:
268 @var KX_ACT_CONSTRAINT_PERMANENT:
269
270 @group Parent Actuator: KX_PARENT_*
271 @var KX_PARENT_REMOVE:
272 @var KX_PARENT_SET:
273
274 @group Shader: MODELMATRIX*, MODELVIEWMATRIX*, VIEWMATRIX*, CAM_POS, CONSTANT_TIMER
275 @var VIEWMATRIX:
276 @var VIEWMATRIX_INVERSE:
277 @var VIEWMATRIX_INVERSETRANSPOSE:
278 @var VIEWMATRIX_TRANSPOSE:
279 @var MODELMATRIX:
280 @var MODELMATRIX_INVERSE:
281 @var MODELMATRIX_INVERSETRANSPOSE:
282 @var MODELMATRIX_TRANSPOSE:
283 @var MODELVIEWMATRIX:
284 @var MODELVIEWMATRIX_INVERSE:
285 @var MODELVIEWMATRIX_INVERSETRANSPOSE:
286 @var MODELVIEWMATRIX_TRANSPOSE:
287 @var CAM_POS: Current camera position
288 @var CONSTANT_TIMER: Current camera position
289 @var SHD_TANGENT: Current camera position
290
291 @group Blender Material: BL_*
292 @var BL_DST_ALPHA:
293 @var BL_DST_COLOR:
294 @var BL_ONE:
295 @var BL_ONE_MINUS_DST_ALPHA:
296 @var BL_ONE_MINUS_DST_COLOR:
297 @var BL_ONE_MINUS_SRC_ALPHA:
298 @var BL_ONE_MINUS_SRC_COLOR:
299 @var BL_SRC_ALPHA:
300 @var BL_SRC_ALPHA_SATURATE:
301 @var BL_SRC_COLOR:
302 @var BL_ZERO:
303
304 @group Deprecated: addActiveActuator
305 """
306
307 import GameTypes
308
309 # TODO
310 # globalDict
311 # error
312
313 def getCurrentController():
314         """
315         Gets the Python controller associated with this Python script.
316         
317         @rtype: L{SCA_PythonController}
318         """
319 def getCurrentScene():
320         """
321         Gets the current Scene.
322         
323         @rtype: L{KX_Scene}
324         """
325 def getSceneList():
326         """
327         Gets a list of the current scenes loaded in the game engine.
328         
329         @note: Scenes in your blend file that have not been converted wont be in this list. This list will only contain scenes such as overlays scenes.
330         
331         @rtype: list of L{KX_Scene}
332         """
333 def addActiveActuator(actuator, activate):
334         """
335         Activates the given actuator.
336         
337         @deprecated: Use L{GameTypes.SCA_PythonController.activate} and L{GameTypes.SCA_PythonController.deactivate} instead.
338         @type actuator: L{SCA_IActuator} or the actuator name as a string.
339         @type activate: boolean
340         @param activate: whether to activate or deactivate the given actuator.
341         """
342 def sendMessage(subject, body="", to="", message_from=""):
343         """
344         Sends a message to sensors in any active scene.
345         
346         @param subject: The subject of the message
347         @type subject: string
348         @param body: The body of the message (optional)
349         @type body: string
350         @param to: The name of the object to send the message to (optional)
351         @type to: string
352         @param message_from: The name of the object that the message is coming from (optional)
353         @type message_from: string
354         """
355 def setGravity(gravity):
356         """
357         Sets the world gravity.
358         
359         @type gravity: list [fx, fy, fz]
360         """
361 def getSpectrum():
362         """
363         Returns a 512 point list from the sound card.
364         This only works if the fmod sound driver is being used.
365         
366         @rtype: list [float], len(getSpectrum()) == 512
367         """
368 def stopDSP():
369         """
370         Stops the sound driver using DSP effects.
371         
372         Only the fmod sound driver supports this.
373         DSP can be computationally expensive.
374         """
375 def getMaxLogicFrame():
376         """
377         Gets the maximum number of logic frame per render frame.
378         
379         @return: The maximum number of logic frame per render frame
380         @rtype: interger
381         """
382 def setMaxLogicFrame(maxlogic):
383         """
384         Sets the maximum number of logic frame that are executed per render frame.
385         This does not affect the physic system that still runs at full frame rate.      
386          
387         @param maxlogic: The new maximum number of logic frame per render frame. Valid values: 1..5
388         @type maxlogic: integer
389         """
390 def getMaxPhysicsFrame():
391         """
392         Gets the maximum number of physics frame per render frame.
393         
394         @return: The maximum number of physics frame per render frame
395         @rtype: interger
396         """
397 def setMaxPhysicsFrame(maxphysics):
398         """
399         Sets the maximum number of physics timestep that are executed per render frame.
400         Higher value allows physics to keep up with realtime even if graphics slows down the game.
401         Physics timestep is fixed and equal to 1/tickrate (see setLogicTicRate)
402         maxphysics/ticrate is the maximum delay of the renderer that physics can compensate.
403          
404         @param maxphysics: The new maximum number of physics timestep per render frame. Valid values: 1..5.
405         @type maxphysics: integer
406         """
407 def getLogicTicRate():
408         """
409         Gets the logic update frequency.
410         
411         @return: The logic frequency in Hz
412         @rtype: float
413         """
414 def setLogicTicRate(ticrate):
415         """
416         Sets the logic update frequency.
417         
418         The logic update frequency is the number of times logic bricks are executed every second.
419         The default is 60 Hz.
420         
421         @param ticrate: The new logic update frequency (in Hz).
422         @type ticrate: float
423         """
424 def getPhysicsTicRate():
425         """
426         NOT IMPLEMENTED
427         Gets the physics update frequency
428         
429         @return: The physics update frequency in Hz
430         @rtype: float
431         """
432 def setPhysicsTicRate(ticrate):
433         """
434         NOT IMPLEMENTED
435         Sets the physics update frequency
436         
437         The physics update frequency is the number of times the physics system is executed every second.
438         The default is 60 Hz.
439         
440         @param ticrate: The new update frequency (in Hz).
441         @type ticrate: float
442         """
443
444 #{ Utility functions
445 def getAverageFrameRate():
446         """
447         Gets the estimated average framerate
448         
449         @return: The estimed average framerate in frames per second
450         @rtype: float
451         """
452 def expandPath(path):
453         """
454         Converts a blender internal path into a proper file system path.
455
456         Use / as directory separator in path
457         You can use '//' at the start of the string to define a relative path;
458         Blender replaces that string by the directory of the startup .blend or runtime file
459         to make a full path name (doesn't change during the game, even if you load other .blend).
460         The function also converts the directory separator to the local file system format.
461
462         @param path: The path string to be converted/expanded.
463         @type path: string
464         @return: The converted string
465         @rtype: string
466         """
467
468 def getBlendFileList(path = "//"):
469         """
470         Returns a list of blend files in the same directory as the open blend file, or from using the option argument.
471
472         @param path: Optional directory argument, will be expanded (like expandPath) into the full path.
473         @type path: string
474         @return: A list of filenames, with no directory prefix
475         @rtype: list
476         """
477 def PrintGLInfo():
478         """
479         Prints GL Extension Info into the console
480         """
481 def getRandomFloat():
482         """
483         Returns a random floating point value in the range [0...1)
484         """
485 #}