1
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, SHD_TANGENT
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: User a timer for the uniform value.
289 @var SHD_TANGENT: Not yet documented.
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 @var globalDict: A dictionary that is saved between loading blend files so you can use
307 it to store inventory and other variables you want to store between
308 scenes and blend files. It can also be written to a file and loaded
309 later on with the game load/save actuators.
310 note: only python built in types such as int/string/bool/float/tuples/lists
311 can be saved, GameObjects, Actuators etc will not work as expectred.
312 """
313
314 import GameTypes
315
316
317
318
319
321 """
322 Gets the Python controller associated with this Python script.
323
324 @rtype: L{SCA_PythonController}
325 """
327 """
328 Gets the current Scene.
329
330 @rtype: L{KX_Scene}
331 """
333 """
334 Gets a list of the current scenes loaded in the game engine.
335
336 @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.
337
338 @rtype: list of L{KX_Scene}
339 """
341 """
342 Activates the given actuator.
343
344 @deprecated: Use L{GameTypes.SCA_PythonController.activate} and L{GameTypes.SCA_PythonController.deactivate} instead.
345 @type actuator: L{SCA_IActuator} or the actuator name as a string.
346 @type activate: boolean
347 @param activate: whether to activate or deactivate the given actuator.
348 """
349 -def sendMessage(subject, body="", to="", message_from=""):
350 """
351 Sends a message to sensors in any active scene.
352
353 @param subject: The subject of the message
354 @type subject: string
355 @param body: The body of the message (optional)
356 @type body: string
357 @param to: The name of the object to send the message to (optional)
358 @type to: string
359 @param message_from: The name of the object that the message is coming from (optional)
360 @type message_from: string
361 """
363 """
364 Sets the world gravity.
365
366 @type gravity: list [fx, fy, fz]
367 """
369 """
370 Returns a 512 point list from the sound card.
371 This only works if the fmod sound driver is being used.
372
373 @rtype: list [float], len(getSpectrum()) == 512
374 """
376 """
377 Stops the sound driver using DSP effects.
378
379 Only the fmod sound driver supports this.
380 DSP can be computationally expensive.
381 """
383 """
384 Gets the maximum number of logic frame per render frame.
385
386 @return: The maximum number of logic frame per render frame
387 @rtype: interger
388 """
390 """
391 Sets the maximum number of logic frame that are executed per render frame.
392 This does not affect the physic system that still runs at full frame rate.
393
394 @param maxlogic: The new maximum number of logic frame per render frame. Valid values: 1..5
395 @type maxlogic: integer
396 """
398 """
399 Gets the maximum number of physics frame per render frame.
400
401 @return: The maximum number of physics frame per render frame
402 @rtype: interger
403 """
405 """
406 Sets the maximum number of physics timestep that are executed per render frame.
407 Higher value allows physics to keep up with realtime even if graphics slows down the game.
408 Physics timestep is fixed and equal to 1/tickrate (see setLogicTicRate)
409 maxphysics/ticrate is the maximum delay of the renderer that physics can compensate.
410
411 @param maxphysics: The new maximum number of physics timestep per render frame. Valid values: 1..5.
412 @type maxphysics: integer
413 """
415 """
416 Gets the logic update frequency.
417
418 @return: The logic frequency in Hz
419 @rtype: float
420 """
422 """
423 Sets the logic update frequency.
424
425 The logic update frequency is the number of times logic bricks are executed every second.
426 The default is 60 Hz.
427
428 @param ticrate: The new logic update frequency (in Hz).
429 @type ticrate: float
430 """
432 """
433 NOT IMPLEMENTED
434 Gets the physics update frequency
435
436 @return: The physics update frequency in Hz
437 @rtype: float
438 """
440 """
441 NOT IMPLEMENTED
442 Sets the physics update frequency
443
444 The physics update frequency is the number of times the physics system is executed every second.
445 The default is 60 Hz.
446
447 @param ticrate: The new update frequency (in Hz).
448 @type ticrate: float
449 """
450
451
453 """
454 Gets the estimated average framerate
455
456 @return: The estimed average framerate in frames per second
457 @rtype: float
458 """
460 """
461 Converts a blender internal path into a proper file system path.
462
463 Use / as directory separator in path
464 You can use '//' at the start of the string to define a relative path;
465 Blender replaces that string by the directory of the startup .blend or runtime file
466 to make a full path name (doesn't change during the game, even if you load other .blend).
467 The function also converts the directory separator to the local file system format.
468
469 @param path: The path string to be converted/expanded.
470 @type path: string
471 @return: The converted string
472 @rtype: string
473 """
474
476 """
477 Returns a list of blend files in the same directory as the open blend file, or from using the option argument.
478
479 @param path: Optional directory argument, will be expanded (like expandPath) into the full path.
480 @type path: string
481 @return: A list of filenames, with no directory prefix
482 @rtype: list
483 """
485 """
486 Prints GL Extension Info into the console
487 """
489 """
490 Returns a random floating point value in the range [0...1)
491 """
492
493