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 a controller:
17 import GameLogic
18 co = GameLogic.getCurrentController()
19
20 # To get the game object associated with this controller:
21 obj = co.getOwner()
22 L{KX_GameObject} and L{KX_Camera} or L{KX_Light} methods are
23 available depending on the type of object::
24 # To get a sensor linked to this controller.
25 # "sensorname" is the name of the sensor as defined in the Blender interface.
26 # +---------------------+ +--------+
27 # | Sensor "sensorname" +--+ Python +
28 # +---------------------+ +--------+
29 sens = co.getSensor("sensorname")
30
31 # To get a list of all sensors:
32 sensors = co.getSensors()
33
34 See the sensor's reference for available methods:
35 - L{KX_NetworkMessageSensor}
36 - L{KX_RaySensor}
37 - L{KX_MouseFocusSensor}
38 - L{KX_NearSensor}
39 - L{KX_RadarSensor}
40 - L{KX_TouchSensor}
41 - L{SCA_KeyboardSensor}
42 - L{SCA_MouseSensor}
43 - L{SCA_PropertySensor}
44 - L{SCA_RandomSensor}
45
46 You can also access actuators linked to the controller::
47 # To get an actuator attached to the controller:
48 # +--------+ +-------------------------+
49 # + Python +--+ Actuator "actuatorname" |
50 # +--------+ +-------------------------+
51 actuator = co.getActuator("actuatorname")
52
53 # Activate an actuator
54 GameLogic.addActiveActuator(actuator, True)
55
56 See the actuator's reference for available methods:
57 - L{BL_ActionActuator}
58 - L{KX_CameraActuator}
59 - L{KX_CDActuator}
60 - L{KX_ConstraintActuator}
61 - L{KX_GameActuator}
62 - L{KX_IpoActuator}
63 - L{KX_NetworkMessageActuator}
64 - L{KX_ObjectActuator}
65 - L{KX_SCA_AddObjectActuator}
66 - L{KX_SCA_EndObjectActuator}
67 - L{KX_SCA_ReplaceMeshActuator}
68 - L{KX_SceneActuator}
69 - L{KX_SoundActuator}
70 - L{KX_TrackToActuator}
71 - L{KX_VisibilityActuator}
72 - L{SCA_PropertyActuator}
73 - L{SCA_RandomActuator}
74
75 Most logic brick's methods are accessors for the properties available in the logic buttons.
76 Consult the logic bricks documentation for more information on how each logic brick works.
77
78 There are also methods to access the current L{KX_Scene}::
79 # Get the current scene
80 scene = GameLogic.getCurrentScene()
81
82 # Get the current camera
83 cam = scene.active_camera
84
85 Matricies as used by the game engine are B{row major}::
86 matrix[row][col] = blah
87 L{KX_Camera} has some examples using matricies.
88
89
90 @group Constants: KX_TRUE, KX_FALSE
91 @var KX_TRUE: True value used by some modules.
92 @var KX_FALSE: False value used by some modules.
93
94 @group Property Sensor: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL, KX_PROPSENSOR_INTERVAL, KX_PROPSENSOR_CHANGED, KX_PROPSENSOR_EXPRESSION
95 @var KX_PROPSENSOR_EQUAL: Activate when the property is equal to the sensor value.
96 @var KX_PROPSENSOR_NOTEQUAL: Activate when the property is not equal to the sensor value.
97 @var KX_PROPSENSOR_INTERVAL: Activate when the property is between the specified limits.
98 @var KX_PROPSENSOR_CHANGED: Activate when the property changes
99 @var KX_PROPSENSOR_EXPRESSION: Activate when the expression matches
100
101 @group Constraint Actuator: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ
102 @var KX_CONSTRAINTACT_LOCX: See L{KX_ConstraintActuator}
103 @var KX_CONSTRAINTACT_LOCY: See L{KX_ConstraintActuator}
104 @var KX_CONSTRAINTACT_LOCZ: See L{KX_ConstraintActuator}
105 @var KX_CONSTRAINTACT_ROTX: See L{KX_ConstraintActuator}
106 @var KX_CONSTRAINTACT_ROTY: See L{KX_ConstraintActuator}
107 @var KX_CONSTRAINTACT_ROTZ: See L{KX_ConstraintActuator}
108
109 @group IPO Actuator: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
110 @var KX_IPOACT_PLAY: See L{KX_IpoActuator}
111 @var KX_IPOACT_PINGPONG: See L{KX_IpoActuator}
112 @var KX_IPOACT_FLIPPER: See L{KX_IpoActuator}
113 @var KX_IPOACT_LOOPSTOP: See L{KX_IpoActuator}
114 @var KX_IPOACT_LOOPEND: See L{KX_IpoActuator}
115
116 @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
117 @var KX_RANDOMACT_BOOL_CONST: See L{SCA_RandomActuator}
118 @var KX_RANDOMACT_BOOL_UNIFORM: See L{SCA_RandomActuator}
119 @var KX_RANDOMACT_BOOL_BERNOUILLI: See L{SCA_RandomActuator}
120 @var KX_RANDOMACT_INT_CONST: See L{SCA_RandomActuator}
121 @var KX_RANDOMACT_INT_UNIFORM: See L{SCA_RandomActuator}
122 @var KX_RANDOMACT_INT_POISSON: See L{SCA_RandomActuator}
123 @var KX_RANDOMACT_FLOAT_CONST: See L{SCA_RandomActuator}
124 @var KX_RANDOMACT_FLOAT_UNIFORM: See L{SCA_RandomActuator}
125 @var KX_RANDOMACT_FLOAT_NORMAL: See L{SCA_RandomActuator}
126 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL: See L{SCA_RandomActuator}
127
128 @group Action Actuator: KX_ACTIONACT_PLAY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND, KX_ACTIONACT_PROPERTY
129 @var KX_ACTIONACT_PLAY: See L{BL_ActionActuator}
130 @var KX_ACTIONACT_FLIPPER: See L{BL_ActionActuator}
131 @var KX_ACTIONACT_LOOPSTOP: See L{BL_ActionActuator}
132 @var KX_ACTIONACT_LOOPEND: See L{BL_ActionActuator}
133 @var KX_ACTIONACT_PROPERTY: See L{BL_ActionActuator}
134
135 @group Sound Actuator: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
136 @var KX_SOUNDACT_PLAYSTOP: See L{KX_SoundActuator}
137 @var KX_SOUNDACT_PLAYEND: See L{KX_SoundActuator}
138 @var KX_SOUNDACT_LOOPSTOP: See L{KX_SoundActuator}
139 @var KX_SOUNDACT_LOOPEND: See L{KX_SoundActuator}
140 @var KX_SOUNDACT_LOOPBIDIRECTIONAL: See L{KX_SoundActuator}
141 @var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP: See L{KX_SoundActuator}
142 """
143
144
146 """
147 Gets the Python controller associated with this Python script.
148
149 @rtype: L{SCA_PythonController}
150 """
152 """
153 Gets the current Scene.
154
155 @rtype: L{KX_Scene}
156 """
158 """
159 Activates the given actuator.
160
161 @type actuator: L{SCA_IActuator}
162 @type activate: boolean
163 @param activate: whether to activate or deactivate the given actuator.
164 """
166 """
167 Returns a random floating point value in the range [0...1)
168 """
170 """
171 Sets the world gravity.
172
173 @type gravity: list [fx, fy, fz]
174 """
176 """
177 Returns a 512 point list from the sound card.
178 This only works if the fmod sound driver is being used.
179
180 @rtype: list [float], len(getSpectrum()) == 512
181 """
183 """
184 Stops the sound driver using DSP effects.
185
186 Only the fmod sound driver supports this.
187 DSP can be computationally expensive.
188 """
190 """
191 Gets the logic update frequency.
192
193 @return: The logic frequency in Hz
194 @rtype: float
195 """
197 """
198 Sets the logic update frequency.
199
200 The logic update frequency is the number of times logic bricks are executed every second.
201 The default is 30 Hz.
202
203 @param ticrate: The new logic update frequency (in Hz).
204 @type ticrate: float
205 """
207 """
208 Gets the physics update frequency
209
210 @return: The physics update frequency in Hz
211 @rtype: float
212 """
214 """
215 Sets the physics update frequency
216
217 The physics update frequency is the number of times the physics system is executed every second.
218 The default is 60 Hz.
219
220 @param ticrate: The new update frequency (in Hz).
221 @type ticrate: float
222 """
223
225 """
226 Converts a blender internal path into a proper file system path.
227
228 Use / as directory separator in path
229 You can use '//' at the start of the string to define a relative path;
230 Blender replaces that string by the directory of the startup .blend or runtime file
231 to make a full path name (doesn't change during the game, even if you load other .blend).
232 The function also converts the directory separator to the local file system format.
233
234 @param path: The path string to be converted/expanded.
235 @type path: string
236 @return: The converted string
237 @rtype: string
238 """
239