Game Logic (bge.logic)

Introduction

Module to access logic functions, imported automatically into the python controllers namespace.

# To get the controller thats running this python script:
cont = bge.logic.getCurrentController() # bge.logic is automatically imported

# To get the game object this controller is on:
obj = cont.owner

KX_GameObject and KX_Camera or KX_LightObject methods are available depending on the type of object

# To get a sensor linked to this controller.
# "sensorname" is the name of the sensor as defined in the Blender interface.
# +---------------------+  +--------+
# | Sensor "sensorname" +--+ Python +
# +---------------------+  +--------+
sens = cont.sensors["sensorname"]

# To get a sequence of all sensors:
sensors = co.sensors

See the sensor’s reference for available methods:

You can also access actuators linked to the controller

# To get an actuator attached to the controller:
#                          +--------+  +-------------------------+
#                          + Python +--+ Actuator "actuatorname" |
#                          +--------+  +-------------------------+
actuator = co.actuators["actuatorname"]

# Activate an actuator
controller.activate(actuator)

See the actuator’s reference for available methods

Most logic brick’s methods are accessors for the properties available in the logic buttons. Consult the logic bricks documentation for more information on how each logic brick works.

There are also methods to access the current bge.types.KX_Scene

# Get the current scene
scene = bge.logic.getCurrentScene()

# Get the current camera
cam = scene.active_camera

Matricies as used by the game engine are row major matrix[row][col] = float

bge.types.KX_Camera has some examples using matrices.

Variables

bge.logic.globalDict

A dictionary that is saved between loading blend files so you can use it to store inventory and other variables you want to store between scenes and blend files. It can also be written to a file and loaded later on with the game load/save actuators.

Note

only python built in types such as int/string/bool/float/tuples/lists can be saved, GameObjects, Actuators etc will not work as expected.

bge.logic.keyboard

The current keyboard wrapped in an SCA_PythonKeyboard object.

bge.logic.mouse

The current mouse wrapped in an SCA_PythonMouse object.

General functions

bge.logic.getCurrentController()

Gets the Python controller associated with this Python script.

Return type:bge.types.SCA_PythonController
bge.logic.getCurrentScene()

Gets the current Scene.

Return type:bge.types.KX_Scene
bge.logic.getSceneList()

Gets a list of the current scenes loaded in the game engine.

Return type:list of bge.types.KX_Scene

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.

bge.logic.loadGlobalDict()

Loads bge.logic.globalDict from a file.

bge.logic.saveGlobalDict()

Saves bge.logic.globalDict to a file.

bge.logic.startGame(blend)

Loads the blend file.

Parameters:blend (string) – The name of the blend file
bge.logic.endGame()

Ends the current game.

bge.logic.restartGame()

Restarts the current game by reloading the .blend file (the last saved version, not what is currently running).

bge.logic.LibLoad(blend, type, data, load_actions=False, verbose=False, load_scripts=True)

Converts the all of the datablocks of the given type from the given blend.

Parameters:
  • blend (string) – The path to the blend file (or the name to use for the library if data is supplied)
  • type (string) – The datablock type (currently only “Action”, “Mesh” and “Scene” are supported)
  • data (bytes) – Binary data from a blend file (optional)
  • load_actions (bool) – Search for and load all actions in a given Scene and not just the “active” actions (Scene type only)
  • verbose (bool) – Whether or not to print debugging information (e.g., “SceneName: Scene”)
  • load_scripts (bool) – Whether or not to load text datablocks as well (can be disabled for some extra security)
bge.logic.LibNew(name, type, data)

Uses existing datablock data and loads in as a new library.

Parameters:
  • name (string) – A unique library name used for removal later
  • type (string) – The datablock type (currently only “Mesh” is supported)
  • data (list of strings) – A list of names of the datablocks to load
bge.logic.LibFree(name)

Frees a library, removing all objects and meshes from the currently active scenes.

Parameters:name (string) – The name of the library to free (the name used in LibNew)
bge.logic.LibList()

Returns a list of currently loaded libraries.

Return type:list [str]
bge.logic.addScene(name, overlay=1)

Loads a scene into the game engine.

Note

This function is not effective immediately, the scene is queued and added on the next logic cycle where it will be available from getSceneList

Parameters:
  • name (string) – The name of the scene
  • overlay (integer) – Overlay or underlay (optional)
bge.logic.sendMessage(subject, body="", to="", message_from="")

Sends a message to sensors in any active scene.

Parameters:
  • subject (string) – The subject of the message
  • body (string) – The body of the message (optional)
  • to (string) – The name of the object to send the message to (optional)
  • message_from (string) – The name of the object that the message is coming from (optional)
bge.logic.setGravity(gravity)

Sets the world gravity.

bge.logic.getSpectrum()

Returns a 512 point list from the sound card. This only works if the fmod sound driver is being used.

Return type:list [float], len(getSpectrum()) == 512
bge.logic.stopDSP()

Stops the sound driver using DSP effects.

Only the fmod sound driver supports this. DSP can be computationally expensive.

bge.logic.getMaxLogicFrame()

Gets the maximum number of logic frames per render frame.

Returns:The maximum number of logic frames per render frame
Return type:integer
bge.logic.setMaxLogicFrame(maxlogic)

Sets the maximum number of logic frames that are executed per render frame. This does not affect the physic system that still runs at full frame rate.

Parameters:maxlogic (integer) – The new maximum number of logic frames per render frame. Valid values: 1..5
bge.logic.getMaxPhysicsFrame()

Gets the maximum number of physics frames per render frame.

Returns:The maximum number of physics frames per render frame
Return type:integer
bge.logic.setMaxPhysicsFrame(maxphysics)

Sets the maximum number of physics timestep that are executed per render frame. Higher value allows physics to keep up with realtime even if graphics slows down the game. Physics timestep is fixed and equal to 1/tickrate (see setLogicTicRate) maxphysics/ticrate is the maximum delay of the renderer that physics can compensate.

Parameters:maxphysics (integer) – The new maximum number of physics timestep per render frame. Valid values: 1..5.
bge.logic.getLogicTicRate()

Gets the logic update frequency.

Returns:The logic frequency in Hz
Return type:float
bge.logic.setLogicTicRate(ticrate)

Sets the logic update frequency.

The logic update frequency is the number of times logic bricks are executed every second. The default is 60 Hz.

Parameters:ticrate (float) – The new logic update frequency (in Hz).
bge.logic.getPhysicsTicRate()

Gets the physics update frequency

Returns:The physics update frequency in Hz
Return type:float
bge.logic.setPhysicsTicRate(ticrate)

Sets the physics update frequency

The physics update frequency is the number of times the physics system is executed every second. The default is 60 Hz.

Parameters:ticrate (float) – The new update frequency (in Hz).

Utility functions

bge.logic.expandPath(path)

Converts a blender internal path into a proper file system path.

Use / as directory separator in path You can use ‘//’ at the start of the string to define a relative path; Blender replaces that string by the directory of the startup .blend or runtime file to make a full path name (doesn’t change during the game, even if you load other .blend). The function also converts the directory separator to the local file system format.

Parameters:path (string) – The path string to be converted/expanded.
Returns:The converted string
Return type:string
bge.logic.getAverageFrameRate()

Gets the estimated/average framerate for all the active scenes, not only the current scene.

Returns:The estimated average framerate in frames per second
Return type:float
bge.logic.getBlendFileList(path = "//")

Returns a list of blend files in the same directory as the open blend file, or from using the option argument.

Parameters:path (string) – Optional directory argument, will be expanded (like expandPath) into the full path.
Returns:A list of filenames, with no directory prefix
Return type:list
bge.logic.getRandomFloat()

Returns a random floating point value in the range [0 - 1)

bge.logic.PrintGLInfo()

Prints GL Extension Info into the console

Constants

bge.logic.KX_TRUE

True value used by some modules.

bge.logic.KX_FALSE

False value used by some modules.

Sensors

Sensor Status

bge.logic.KX_SENSOR_INACTIVE
bge.logic.KX_SENSOR_JUST_ACTIVATED
bge.logic.KX_SENSOR_ACTIVE
bge.logic.KX_SENSOR_JUST_DEACTIVATED

Property Sensor

bge.logic.KX_PROPSENSOR_EQUAL

Activate when the property is equal to the sensor value.

Value :1
bge.logic.KX_PROPSENSOR_NOTEQUAL

Activate when the property is not equal to the sensor value.

Value :2
bge.logic.KX_PROPSENSOR_INTERVAL

Activate when the property is between the specified limits.

Value :3
bge.logic.KX_PROPSENSOR_CHANGED

Activate when the property changes

Value :4
bge.logic.KX_PROPSENSOR_EXPRESSION

Activate when the expression matches

Value :5

Radar Sensor

See bge.types.KX_RadarSensor

bge.logic.KX_RADAR_AXIS_POS_X
bge.logic.KX_RADAR_AXIS_POS_Y
bge.logic.KX_RADAR_AXIS_POS_Z
bge.logic.KX_RADAR_AXIS_NEG_X
bge.logic.KX_RADAR_AXIS_NEG_Y
bge.logic.KX_RADAR_AXIS_NEG_Z

Ray Sensor

See bge.types.KX_RaySensor

bge.logic.KX_RAY_AXIS_POS_X
bge.logic.KX_RAY_AXIS_POS_Y
bge.logic.KX_RAY_AXIS_POS_Z
bge.logic.KX_RAY_AXIS_NEG_X
bge.logic.KX_RAY_AXIS_NEG_Y
bge.logic.KX_RAY_AXIS_NEG_Z

Actuators

Action Actuator

See bge.types.BL_ActionActuator

bge.logic.KX_ACTIONACT_PLAY
bge.logic.KX_ACTIONACT_PINGPONG
bge.logic.KX_ACTIONACT_FLIPPER
bge.logic.KX_ACTIONACT_LOOPSTOP
bge.logic.KX_ACTIONACT_LOOPEND
bge.logic.KX_ACTIONACT_PROPERTY

Constraint Actuator

See bge.types.KX_ConstraintActuator.option

  • Applicable to Distance constraint:

    bge.logic.KX_ACT_CONSTRAINT_NORMAL

    Activate alignment to surface

    bge.logic.KX_ACT_CONSTRAINT_DISTANCE

    Activate distance control

    bge.logic.KX_ACT_CONSTRAINT_LOCAL

    Direction of the ray is along the local axis

  • Applicable to Force field constraint:

    bge.logic.KX_ACT_CONSTRAINT_DOROTFH

    Force field act on rotation as well

  • Applicable to both:

    bge.logic.KX_ACT_CONSTRAINT_MATERIAL

    Detect material rather than property

    bge.logic.KX_ACT_CONSTRAINT_PERMANENT

    No deactivation if ray does not hit target

See bge.types.KX_ConstraintActuator.limit

bge.logic.KX_CONSTRAINTACT_LOCX

Limit X coord.

bge.logic.KX_CONSTRAINTACT_LOCY

Limit Y coord

bge.logic.KX_CONSTRAINTACT_LOCZ

Limit Z coord

bge.logic.KX_CONSTRAINTACT_ROTX

Limit X rotation

bge.logic.KX_CONSTRAINTACT_ROTY

Limit Y rotation

bge.logic.KX_CONSTRAINTACT_ROTZ

Limit Z rotation

bge.logic.KX_CONSTRAINTACT_DIRNX

Set distance along negative X axis

bge.logic.KX_CONSTRAINTACT_DIRNY

Set distance along negative Y axis

bge.logic.KX_CONSTRAINTACT_DIRNZ

Set distance along negative Z axis

bge.logic.KX_CONSTRAINTACT_DIRPX

Set distance along positive X axis

bge.logic.KX_CONSTRAINTACT_DIRPY

Set distance along positive Y axis

bge.logic.KX_CONSTRAINTACT_DIRPZ

Set distance along positive Z axis

bge.logic.KX_CONSTRAINTACT_ORIX

Set orientation of X axis

bge.logic.KX_CONSTRAINTACT_ORIY

Set orientation of Y axis

bge.logic.KX_CONSTRAINTACT_ORIZ

Set orientation of Z axis

bge.logic.KX_ACT_CONSTRAINT_FHNX

Set force field along negative X axis

bge.logic.KX_ACT_CONSTRAINT_FHNY

Set force field along negative Y axis

bge.logic.KX_ACT_CONSTRAINT_FHNZ

Set force field along negative Z axis

bge.logic.KX_ACT_CONSTRAINT_FHPX

Set force field along positive X axis

bge.logic.KX_ACT_CONSTRAINT_FHPY

Set force field along positive Y axis

bge.logic.KX_ACT_CONSTRAINT_FHPZ

Set force field along positive Z axis

Dynamic Actuator

See bge.types.KX_SCA_DynamicActuator

bge.logic.KX_DYN_RESTORE_DYNAMICS
bge.logic.KX_DYN_DISABLE_DYNAMICS
bge.logic.KX_DYN_ENABLE_RIGID_BODY
bge.logic.KX_DYN_DISABLE_RIGID_BODY
bge.logic.KX_DYN_SET_MASS

Game Actuator

See bge.types.KX_GameActuator

bge.logic.KX_GAME_LOAD
bge.logic.KX_GAME_START
bge.logic.KX_GAME_RESTART
bge.logic.KX_GAME_QUIT
bge.logic.KX_GAME_SAVECFG
bge.logic.KX_GAME_LOADCFG

Parent Actuator

bge.logic.KX_PARENT_REMOVE
bge.logic.KX_PARENT_SET

Random Distributions

See bge.types.SCA_RandomActuator

bge.logic.KX_RANDOMACT_BOOL_CONST
bge.logic.KX_RANDOMACT_BOOL_UNIFORM
bge.logic.KX_RANDOMACT_BOOL_BERNOUILLI
bge.logic.KX_RANDOMACT_INT_CONST
bge.logic.KX_RANDOMACT_INT_UNIFORM
bge.logic.KX_RANDOMACT_INT_POISSON
bge.logic.KX_RANDOMACT_FLOAT_CONST
bge.logic.KX_RANDOMACT_FLOAT_UNIFORM
bge.logic.KX_RANDOMACT_FLOAT_NORMAL
bge.logic.KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL

Scene Actuator

See bge.types.KX_SceneActuator

bge.logic.KX_SCENE_RESTART
bge.logic.KX_SCENE_SET_SCENE
bge.logic.KX_SCENE_SET_CAMERA
bge.logic.KX_SCENE_ADD_FRONT_SCENE
bge.logic.KX_SCENE_ADD_BACK_SCENE
bge.logic.KX_SCENE_REMOVE_SCENE
bge.logic.KX_SCENE_SUSPEND
bge.logic.KX_SCENE_RESUME

Sound Actuator

See bge.types.KX_SoundActuator

bge.logic.KX_SOUNDACT_PLAYSTOP
Value :1
bge.logic.KX_SOUNDACT_PLAYEND
Value :2
bge.logic.KX_SOUNDACT_LOOPSTOP
Value :3
bge.logic.KX_SOUNDACT_LOOPEND
Value :4
bge.logic.KX_SOUNDACT_LOOPBIDIRECTIONAL
Value :5
bge.logic.KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
Value :6

Various

Input Status

See bge.types.SCA_PythonKeyboard, bge.types.SCA_PythonMouse, bge.types.SCA_MouseSensor, bge.types.SCA_KeyboardSensor

bge.logic.KX_INPUT_NONE
bge.logic.KX_INPUT_JUST_ACTIVATED
bge.logic.KX_INPUT_ACTIVE
bge.logic.KX_INPUT_JUST_RELEASED

Mouse Buttons

See bge.types.SCA_MouseSensor

bge.logic.KX_MOUSE_BUT_LEFT
bge.logic.KX_MOUSE_BUT_MIDDLE
bge.logic.KX_MOUSE_BUT_RIGHT

States

See bge.types.KX_StateActuator

bge.logic.KX_STATE1
bge.logic.KX_STATE2
bge.logic.KX_STATE3
bge.logic.KX_STATE4
bge.logic.KX_STATE5
bge.logic.KX_STATE6
bge.logic.KX_STATE7
bge.logic.KX_STATE8
bge.logic.KX_STATE9
bge.logic.KX_STATE10
bge.logic.KX_STATE11
bge.logic.KX_STATE12
bge.logic.KX_STATE13
bge.logic.KX_STATE14
bge.logic.KX_STATE15
bge.logic.KX_STATE16
bge.logic.KX_STATE17
bge.logic.KX_STATE18
bge.logic.KX_STATE19
bge.logic.KX_STATE20
bge.logic.KX_STATE21
bge.logic.KX_STATE22
bge.logic.KX_STATE23
bge.logic.KX_STATE24
bge.logic.KX_STATE25
bge.logic.KX_STATE26
bge.logic.KX_STATE27
bge.logic.KX_STATE28
bge.logic.KX_STATE29
bge.logic.KX_STATE30

See bge.types.KX_StateActuator.operation

bge.logic.KX_STATE_OP_CLR

Substract bits to state mask

Value :0
bge.logic.KX_STATE_OP_CPY

Copy state mask

Value :1
bge.logic.KX_STATE_OP_NEG

Invert bits to state mask

Value :2
bge.logic.KX_STATE_OP_SET

Add bits to state mask

Value :3

2D Filter

bge.logic.RAS_2DFILTER_BLUR
Value :2
bge.logic.RAS_2DFILTER_CUSTOMFILTER

Customer filter, the code code is set via shaderText property.

Value :12
bge.logic.RAS_2DFILTER_DILATION
Value :4
bge.logic.RAS_2DFILTER_DISABLED

Disable the filter that is currently active

Value :-1
bge.logic.RAS_2DFILTER_ENABLED

Enable the filter that was previously disabled

Value :-2
bge.logic.RAS_2DFILTER_EROSION
Value :5
bge.logic.RAS_2DFILTER_GRAYSCALE
Value :9
bge.logic.RAS_2DFILTER_INVERT
Value :11
bge.logic.RAS_2DFILTER_LAPLACIAN
Value :6
bge.logic.RAS_2DFILTER_MOTIONBLUR

Create and enable preset filters

Value :1
bge.logic.RAS_2DFILTER_NOFILTER

Disable and destroy the filter that is currently active

Value :0
bge.logic.RAS_2DFILTER_PREWITT
Value :8
bge.logic.RAS_2DFILTER_SEPIA
Value :10
bge.logic.RAS_2DFILTER_SHARPEN
Value :3
bge.logic.RAS_2DFILTER_SOBEL
Value :7

Shader

bge.logic.VIEWMATRIX
bge.logic.VIEWMATRIX_INVERSE
bge.logic.VIEWMATRIX_INVERSETRANSPOSE
bge.logic.VIEWMATRIX_TRANSPOSE
bge.logic.MODELMATRIX
bge.logic.MODELMATRIX_INVERSE
bge.logic.MODELMATRIX_INVERSETRANSPOSE
bge.logic.MODELMATRIX_TRANSPOSE
bge.logic.MODELVIEWMATRIX
bge.logic.MODELVIEWMATRIX_INVERSE
bge.logic.MODELVIEWMATRIX_INVERSETRANSPOSE
bge.logic.MODELVIEWMATRIX_TRANSPOSE
bge.logic.CAM_POS

Current camera position

bge.logic.CONSTANT_TIMER

User a timer for the uniform value.

bge.logic.SHD_TANGENT

Blender Material

bge.logic.BL_DST_ALPHA
bge.logic.BL_DST_COLOR
bge.logic.BL_ONE
bge.logic.BL_ONE_MINUS_DST_ALPHA
bge.logic.BL_ONE_MINUS_DST_COLOR
bge.logic.BL_ONE_MINUS_SRC_ALPHA
bge.logic.BL_ONE_MINUS_SRC_COLOR
bge.logic.BL_SRC_ALPHA
bge.logic.BL_SRC_ALPHA_SATURATE
bge.logic.BL_SRC_COLOR
bge.logic.BL_ZERO