* blender doesn't need the -w anymore to start in a window
[blender.git] / 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         
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
146 def getCurrentController():
147         """
148         Gets the Python controller associated with this Python script.
149         
150         @rtype: L{SCA_PythonController}
151         """
152 def getCurrentScene():
153         """
154         Gets the current Scene.
155         
156         @rtype: L{KX_Scene}
157         """
158 def addActiveActuator(actuator, activate):
159         """
160         Activates the given actuator.
161         
162         @type actuator: L{SCA_IActuator} or the actuator name as a string.
163         @type activate: boolean
164         @param activate: whether to activate or deactivate the given actuator.
165         """
166 def getRandomFloat():
167         """
168         Returns a random floating point value in the range [0...1)
169         """
170 def setGravity(gravity):
171         """
172         Sets the world gravity.
173         
174         @type gravity: list [fx, fy, fz]
175         """
176 def getSpectrum():
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         """
183 def stopDSP():
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         """
190 def getLogicTicRate():
191         """
192         Gets the logic update frequency.
193         
194         @return: The logic frequency in Hz
195         @rtype: float
196         """
197 def setLogicTicRate(ticrate):
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         """
207 def getPhysicsTicRate():
208         """
209         Gets the physics update frequency
210         
211         @return: The physics update frequency in Hz
212         @rtype: float
213         """
214 def setPhysicsTicRate(ticrate):
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         """
224 def getAverageFrameRate():
225         """
226         Gets the estimated average framerate
227         
228         @return: The estimed average framerate in frames per second
229         @rtype: float
230         """
231
232 def expandPath(path):
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
248 def getBlendFileList(path = "//"):
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         """