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         """