Minor Fixes:
[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 accessibly through the methods in GameLogic.
12         
13         Examples::
14                 # To get a controller:
15                 import GameLogic
16                 co = GameLogic.getCurrentController()
17                 
18                 # To get the game object associated with this controller:
19                 obj = co.getOwner()
20         L{KX_GameObject} and L{KX_Camera} or L{KX_Light} methods are
21         available depending on the type of object::
22                 # To get a sensor linked to this controller.
23                 # "sensorname" is the name of the sensor as defined in the Blender interface.
24                 # +---------------------+  +--------+
25                 # | Sensor "sensorname" +--+ Python +
26                 # +---------------------+  +--------+
27                 sens = co.getSensor("sensorname")
28         
29                 # To get a list of all sensors:
30                 sensors = co.getSensors()
31
32         See the sensor's reference for available methods:
33                 - L{KX_NetworkMessageSensor}
34                 - L{KX_RaySensor}
35                 - L{KX_MouseFocusSensor}
36                 - L{KX_NearSensor}
37                 - L{KX_RadarSensor}
38                 - L{KX_TouchSensor}
39                 - L{SCA_KeyboardSensor}
40                 - L{SCA_MouseSensor}
41                 - L{SCA_PropertySensor} 
42                 - L{SCA_RandomSensor} 
43         
44         You can also access actuators linked to the controller::
45                 # To get an actuator attached to the controller:
46                 #                          +--------+  +-------------------------+
47                 #                          + Python +--+ Actuator "actuatorname" |
48                 #                          +--------+  +-------------------------+
49                 actuator = co.getActuator("actuatorname")
50                 
51                 # Activate an actuator
52                 GameLogic.addActiveActuator(actuator, True)
53                 
54         See the actuator's reference for available methods:
55                 - L{BL_ActionActuator}
56                 - L{KX_CameraActuator}
57                 - L{KX_CDActuator}
58                 - L{KX_ConstraintActuator}
59                 - L{KX_GameActuator}
60                 - L{KX_IpoActuator}
61                 - L{KX_NetworkMessageActuator}
62                 - L{KX_ObjectActuator}
63                 - L{KX_SCA_AddObjectActuator}
64                 - L{KX_SCA_EndObjectActuator}
65                 - L{KX_SCA_ReplaceMeshActuator}
66                 - L{KX_SceneActuator}
67                 - L{KX_SoundActuator}
68                 - L{KX_TrackToActuator}
69                 - L{KX_VisibilityActuator}
70                 - L{SCA_PropertyActuator}
71                 - L{SCA_RandomActuator} 
72         
73         There are also methods to access the current L{KX_Scene}::
74                 # Get the current scene
75                 scene = GameLogic.getCurrentScene()
76                 
77                 # Get the current camera
78                 cam = scene.active_camera
79
80         Matricies as used by the game engine are B{row major}::
81                 matrix[row][col] = blah
82         L{KX_Camera} has some examples using matricies.
83
84
85 @group Constants: KX_TRUE, KX_FALSE
86 @var KX_TRUE: True value used by some modules.
87 @var KX_FALSE: False value used by some modules.
88
89 @group Property Sensor: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL, KX_PROPSENSOR_INTERVAL, KX_PROPSENSOR_CHANGED, KX_PROPSENSOR_EXPRESSION
90 @var KX_PROPSENSOR_EQUAL:               Activate when the property is equal to the sensor value.
91 @var KX_PROPSENSOR_NOTEQUAL:    Activate when the property is not equal to the sensor value.
92 @var KX_PROPSENSOR_INTERVAL:    Activate when the property is between the specified limits.
93 @var KX_PROPSENSOR_CHANGED:     Activate when the property changes
94 @var KX_PROPSENSOR_EXPRESSION:  Activate when the expression matches
95
96 @group Constraint Actuator: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ
97 @var KX_CONSTRAINTACT_LOCX: See L{KX_ConstraintActuator}
98 @var KX_CONSTRAINTACT_LOCY: See L{KX_ConstraintActuator}
99 @var KX_CONSTRAINTACT_LOCZ: See L{KX_ConstraintActuator}
100 @var KX_CONSTRAINTACT_ROTX: See L{KX_ConstraintActuator}
101 @var KX_CONSTRAINTACT_ROTY: See L{KX_ConstraintActuator}
102 @var KX_CONSTRAINTACT_ROTZ: See L{KX_ConstraintActuator}
103
104 @group IPO Actuator: KX_IPOACT_PLAY, KX_IPOACT_PINGPONG, KX_IPOACT_FLIPPER, KX_IPOACT_LOOPSTOP, KX_IPOACT_LOOPEND
105 @var KX_IPOACT_PLAY:     See L{KX_IpoActuator}
106 @var KX_IPOACT_PINGPONG:         See L{KX_IpoActuator}
107 @var KX_IPOACT_FLIPPER:  See L{KX_IpoActuator}
108 @var KX_IPOACT_LOOPSTOP:         See L{KX_IpoActuator}
109 @var KX_IPOACT_LOOPEND:  See L{KX_IpoActuator}
110
111 @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
112 @var KX_RANDOMACT_BOOL_CONST:           See L{SCA_RandomActuator}
113 @var KX_RANDOMACT_BOOL_UNIFORM:         See L{SCA_RandomActuator}
114 @var KX_RANDOMACT_BOOL_BERNOUILLI:              See L{SCA_RandomActuator}
115 @var KX_RANDOMACT_INT_CONST:            See L{SCA_RandomActuator}
116 @var KX_RANDOMACT_INT_UNIFORM:          See L{SCA_RandomActuator}
117 @var KX_RANDOMACT_INT_POISSON:          See L{SCA_RandomActuator}
118 @var KX_RANDOMACT_FLOAT_CONST:          See L{SCA_RandomActuator}
119 @var KX_RANDOMACT_FLOAT_UNIFORM:                See L{SCA_RandomActuator}
120 @var KX_RANDOMACT_FLOAT_NORMAL:         See L{SCA_RandomActuator}
121 @var KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL:           See L{SCA_RandomActuator}
122
123 """
124
125
126 def getCurrentController():
127         """
128         Gets the Python controller associated with this Python script.
129         
130         @rtype: L{SCA_PythonController}
131         """
132 def getCurrentScene():
133         """
134         Gets the current Scene.
135         
136         @rtype: L{KX_Scene}
137         """
138 def addActiveActuator(actuator, activate):
139         """
140         Activates the given actuator.
141         
142         @type actuator: L{SCA_IActuator}
143         @type activate: boolean
144         @param activate: whether to activate or deactivate the given actuator.
145         """
146 def getRandomFloat():
147         """
148         Returns a random floating point value in the range [0...1)
149         """
150 def setGravity(gravity):
151         """
152         Sets the world gravity.
153         
154         @type gravity: list [fx, fy, fz]
155         """
156 def getSpectrum():
157         """
158         Returns a 512 point list from the sound card.
159         This only works if the fmod sound driver is being used.
160         
161         @rtype: list [float], len(getSpectrum()) == 512
162         """
163 def stopDSP():
164         """
165         Stops the sound driver using DSP effects.
166         
167         Only the fmod sound driver supports this.
168         DSP can be computationally expensive.
169         """
170