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