1
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
76 Most logic brick's methods are accessors for the properties available in the logic buttons.
77 Consult the logic bricks documentation for more information on how each logic brick works.
78
79 There are also methods to access the current L{KX_Scene}::
80 # Get the current scene
81 scene = GameLogic.getCurrentScene()
82
83 # Get the current camera
84 cam = scene.active_camera
85
86 Matricies as used by the game engine are B{row major}::
87 matrix[row][col] = blah
88 L{KX_Camera} has some examples using matricies.
89
90
91 @group Constants: KX_TRUE, KX_FALSE
92 @var KX_TRUE: True value used by some modules.
93 @var KX_FALSE: False value used by some modules.
94
95 @group Property Sensor: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL, KX_PROPSENSOR_INTERVAL, KX_PROPSENSOR_CHANGED, KX_PROPSENSOR_EXPRESSION
96 @var KX_PROPSENSOR_EQUAL: Activate when the property is equal to the sensor value.
97 @var KX_PROPSENSOR_NOTEQUAL: Activate when the property is not equal to the sensor value.
98 @var KX_PROPSENSOR_INTERVAL: Activate when the property is between the specified limits.
99 @var KX_PROPSENSOR_CHANGED: Activate when the property changes
100 @var KX_PROPSENSOR_EXPRESSION: Activate when the expression matches
101
102 @group Constraint Actuator: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ
103 @var KX_CONSTRAINTACT_LOCX: See L{KX_ConstraintActuator}
104 @var KX_CONSTRAINTACT_LOCY: See L{KX_ConstraintActuator}
105 @var KX_CONSTRAINTACT_LOCZ: See L{KX_ConstraintActuator}
106 @var KX_CONSTRAINTACT_ROTX: See L{KX_ConstraintActuator}
107 @var KX_CONSTRAINTACT_ROTY: See L{KX_ConstraintActuator}
108 @var KX_CONSTRAINTACT_ROTZ: See L{KX_ConstraintActuator}
109
110 @group IPO Actuator: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
111 @var KX_IPOACT_PLAY: See L{KX_IpoActuator}
112 @var KX_IPOACT_PINGPONG: See L{KX_IpoActuator}
113 @var KX_IPOACT_FLIPPER: See L{KX_IpoActuator}
114 @var KX_IPOACT_LOOPSTOP: See L{KX_IpoActuator}
115 @var KX_IPOACT_LOOPEND: See L{KX_IpoActuator}
116
117 @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
118 @var KX_RANDOMACT_BOOL_CONST: See L{SCA_RandomActuator}
119 @var KX_RANDOMACT_BOOL_UNIFORM: See L{SCA_RandomActuator}
120 @var KX_RANDOMACT_BOOL_BERNOUILLI: See L{SCA_RandomActuator}
121 @var KX_RANDOMACT_INT_CONST: See L{SCA_RandomActuator}
122 @var KX_RANDOMACT_INT_UNIFORM: See L{SCA_RandomActuator}
123 @var KX_RANDOMACT_INT_POISSON: See L{SCA_RandomActuator}
124 @var KX_RANDOMACT_FLOAT_CONST: See L{SCA_RandomActuator}
125 @var KX_RANDOMACT_FLOAT_UNIFORM: See L{SCA_RandomActuator}
126 @var KX_RANDOMACT_FLOAT_NORMAL: See L{SCA_RandomActuator}
127 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL: See L{SCA_RandomActuator}
128
129 @group Action Actuator: KX_ACTIONACT_PLAY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND, KX_ACTIONACT_PROPERTY
130 @var KX_ACTIONACT_PLAY: See L{BL_ActionActuator}
131 @var KX_ACTIONACT_FLIPPER: See L{BL_ActionActuator}
132 @var KX_ACTIONACT_LOOPSTOP: See L{BL_ActionActuator}
133 @var KX_ACTIONACT_LOOPEND: See L{BL_ActionActuator}
134 @var KX_ACTIONACT_PROPERTY: See L{BL_ActionActuator}
135
136 @group Sound Actuator: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
137 @var KX_SOUNDACT_PLAYSTOP: See L{KX_SoundActuator}
138 @var KX_SOUNDACT_PLAYEND: See L{KX_SoundActuator}
139 @var KX_SOUNDACT_LOOPSTOP: See L{KX_SoundActuator}
140 @var KX_SOUNDACT_LOOPEND: See L{KX_SoundActuator}
141 @var KX_SOUNDACT_LOOPBIDIRECTIONAL: See L{KX_SoundActuator}
142 @var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP: See L{KX_SoundActuator}
143 """
144
145
147 """
148 Gets the Python controller associated with this Python script.
149
150 @rtype: L{SCA_PythonController}
151 """
153 """
154 Gets the current Scene.
155
156 @rtype: L{KX_Scene}
157 """
159 """
160 Activates the given actuator.
161
162 @type actuator: L{SCA_IActuator}
163 @type activate: boolean
164 @param activate: whether to activate or deactivate the given actuator.
165 """
167 """
168 Returns a random floating point value in the range [0...1)
169 """
171 """
172 Sets the world gravity.
173
174 @type gravity: list [fx, fy, fz]
175 """
177 """
178 Returns a 512 point list from the sound card.
179 This only works if the fmod sound driver is being used.
180
181 @rtype: list [float], len(getSpectrum()) == 512
182 """
184 """
185 Stops the sound driver using DSP effects.
186
187 Only the fmod sound driver supports this.
188 DSP can be computationally expensive.
189 """
191 """
192 Gets the logic update frequency.
193
194 @return: The logic frequency in Hz
195 @rtype: float
196 """
198 """
199 Sets the logic update frequency.
200
201 The logic update frequency is the number of times logic bricks are executed every second.
202 The default is 30 Hz.
203
204 @param ticrate: The new logic update frequency (in Hz).
205 @type ticrate: float
206 """
208 """
209 Gets the physics update frequency
210
211 @return: The physics update frequency in Hz
212 @rtype: float
213 """
215 """
216 Sets the physics update frequency
217
218 The physics update frequency is the number of times the physics system is executed every second.
219 The default is 60 Hz.
220
221 @param ticrate: The new update frequency (in Hz).
222 @type ticrate: float
223 """
225 """
226 Gets the estimated average framerate
227
228 @return: The estimed average framerate in frames per second
229 @rtype: float
230 """
231
233 """
234 Converts a blender internal path into a proper file system path.
235
236 Use / as directory separator in path
237 You can use '//' at the start of the string to define a relative path;
238 Blender replaces that string by the directory of the startup .blend or runtime file
239 to make a full path name (doesn't change during the game, even if you load other .blend).
240 The function also converts the directory separator to the local file system format.
241
242 @param path: The path string to be converted/expanded.
243 @type path: string
244 @return: The converted string
245 @rtype: string
246 """
247
249 """
250 Returns a list of blend files in the same directory as the open blend file, or from using the option argument.
251
252 @param path: Optional directory argument, will be expanded (like expandPath) into the full path.
253 @type path: string
254 @return: A list of filenames, with no directory prefix
255 @rtype: list
256 """
257