PyDoc updates
[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 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
145 def getCurrentController():
146         """
147         Gets the Python controller associated with this Python script.
148         
149         @rtype: L{SCA_PythonController}
150         """
151 def getCurrentScene():
152         """
153         Gets the current Scene.
154         
155         @rtype: L{KX_Scene}
156         """
157 def addActiveActuator(actuator, activate):
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         """
165 def getRandomFloat():
166         """
167         Returns a random floating point value in the range [0...1)
168         """
169 def setGravity(gravity):
170         """
171         Sets the world gravity.
172         
173         @type gravity: list [fx, fy, fz]
174         """
175 def getSpectrum():
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         """
182 def stopDSP():
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         """
189 def getLogicTicRate():
190         """
191         Gets the logic update frequency.
192         
193         @return: The logic frequency in Hz
194         @rtype: float
195         """
196 def setLogicTicRate(ticrate):
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         """
206 def getPhysicsTicRate():
207         """
208         Gets the physics update frequency
209         
210         @return: The physics update frequency in Hz
211         @rtype: float
212         """
213 def setPhysicsTicRate(ticrate):
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