fix typo in GameLogic documentation
[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         There are also methods to access the current L{KX_Scene}::
76                 # Get the current scene
77                 scene = GameLogic.getCurrentScene()
78                 
79                 # Get the current camera
80                 cam = scene.active_camera
81
82         Matricies as used by the game engine are B{row major}::
83                 matrix[row][col] = blah
84         L{KX_Camera} has some examples using matricies.
85
86
87 @group Constants: KX_TRUE, KX_FALSE
88 @var KX_TRUE: True value used by some modules.
89 @var KX_FALSE: False value used by some modules.
90
91 @group Property Sensor: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL, KX_PROPSENSOR_INTERVAL, KX_PROPSENSOR_CHANGED, KX_PROPSENSOR_EXPRESSION
92 @var KX_PROPSENSOR_EQUAL:               Activate when the property is equal to the sensor value.
93 @var KX_PROPSENSOR_NOTEQUAL:    Activate when the property is not equal to the sensor value.
94 @var KX_PROPSENSOR_INTERVAL:    Activate when the property is between the specified limits.
95 @var KX_PROPSENSOR_CHANGED:     Activate when the property changes
96 @var KX_PROPSENSOR_EXPRESSION:  Activate when the expression matches
97
98 @group Constraint Actuator: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ
99 @var KX_CONSTRAINTACT_LOCX: See L{KX_ConstraintActuator}
100 @var KX_CONSTRAINTACT_LOCY: See L{KX_ConstraintActuator}
101 @var KX_CONSTRAINTACT_LOCZ: See L{KX_ConstraintActuator}
102 @var KX_CONSTRAINTACT_ROTX: See L{KX_ConstraintActuator}
103 @var KX_CONSTRAINTACT_ROTY: See L{KX_ConstraintActuator}
104 @var KX_CONSTRAINTACT_ROTZ: See L{KX_ConstraintActuator}
105
106 @group IPO Actuator: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
107 @var KX_IPOACT_PLAY:     See L{KX_IpoActuator}
108 @var KX_IPOACT_PINGPONG:         See L{KX_IpoActuator}
109 @var KX_IPOACT_FLIPPER:  See L{KX_IpoActuator}
110 @var KX_IPOACT_LOOPSTOP:         See L{KX_IpoActuator}
111 @var KX_IPOACT_LOOPEND:  See L{KX_IpoActuator}
112
113 @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
114 @var KX_RANDOMACT_BOOL_CONST:           See L{SCA_RandomActuator}
115 @var KX_RANDOMACT_BOOL_UNIFORM:         See L{SCA_RandomActuator}
116 @var KX_RANDOMACT_BOOL_BERNOUILLI:              See L{SCA_RandomActuator}
117 @var KX_RANDOMACT_INT_CONST:            See L{SCA_RandomActuator}
118 @var KX_RANDOMACT_INT_UNIFORM:          See L{SCA_RandomActuator}
119 @var KX_RANDOMACT_INT_POISSON:          See L{SCA_RandomActuator}
120 @var KX_RANDOMACT_FLOAT_CONST:          See L{SCA_RandomActuator}
121 @var KX_RANDOMACT_FLOAT_UNIFORM:                See L{SCA_RandomActuator}
122 @var KX_RANDOMACT_FLOAT_NORMAL:         See L{SCA_RandomActuator}
123 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL:           See L{SCA_RandomActuator}
124
125 @group Action Actuator: KX_ACTIONACT_PLAY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND, KX_ACTIONACT_PROPERTY
126 @var KX_ACTIONACT_PLAY:     See L{BL_ActionActuator}
127 @var KX_ACTIONACT_FLIPPER:  See L{BL_ActionActuator}
128 @var KX_ACTIONACT_LOOPSTOP: See L{BL_ActionActuator}
129 @var KX_ACTIONACT_LOOPEND:  See L{BL_ActionActuator}
130 @var KX_ACTIONACT_PROPERTY: See L{BL_ActionActuator}
131
132 @group Sound Actuator: KX_SOUNDACT_PLAYSTOP, KX_SOUNDACT_PLAYEND, KX_SOUNDACT_LOOPSTOP, KX_SOUNDACT_LOOPEND, KX_SOUNDACT_LOOPBIDIRECTIONAL, KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
133 @var KX_SOUNDACT_PLAYSTOP:                  See L{KX_SoundActuator}
134 @var KX_SOUNDACT_PLAYEND:                   See L{KX_SoundActuator}
135 @var KX_SOUNDACT_LOOPSTOP:                  See L{KX_SoundActuator}
136 @var KX_SOUNDACT_LOOPEND:                   See L{KX_SoundActuator}
137 @var KX_SOUNDACT_LOOPBIDIRECTIONAL:         See L{KX_SoundActuator}
138 @var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP:    See L{KX_SoundActuator}
139 """
140
141
142 def getCurrentController():
143         """
144         Gets the Python controller associated with this Python script.
145         
146         @rtype: L{SCA_PythonController}
147         """
148 def getCurrentScene():
149         """
150         Gets the current Scene.
151         
152         @rtype: L{KX_Scene}
153         """
154 def addActiveActuator(actuator, activate):
155         """
156         Activates the given actuator.
157         
158         @type actuator: L{SCA_IActuator}
159         @type activate: boolean
160         @param activate: whether to activate or deactivate the given actuator.
161         """
162 def getRandomFloat():
163         """
164         Returns a random floating point value in the range [0...1)
165         """
166 def setGravity(gravity):
167         """
168         Sets the world gravity.
169         
170         @type gravity: list [fx, fy, fz]
171         """
172 def getSpectrum():
173         """
174         Returns a 512 point list from the sound card.
175         This only works if the fmod sound driver is being used.
176         
177         @rtype: list [float], len(getSpectrum()) == 512
178         """
179 def stopDSP():
180         """
181         Stops the sound driver using DSP effects.
182         
183         Only the fmod sound driver supports this.
184         DSP can be computationally expensive.
185         """
186