BGE patch: Add PyDoc for new logic bricks, set exception message on Py error, remove args on Py functions that don't take any to save CPU time

7 files changed, 457 insertions, 12 deletions

diff --git a/source/gameengine/PyDoc/BL_ShapeActionActuator.py b/source/gameengine/PyDoc/BL_ShapeActionActuator.py
new file mode 100644
index 00000000000..63cce253fa4
--- /dev/null
+++ b/source/gameengine/PyDoc/BL_ShapeActionActuator.py
@@ -0,0 +1,158 @@
+# $Id$
+# Documentation for BL_ShapeActionActuator
+from SCA_IActuator import *
+
+class BL_ShapeActionActuator(SCA_IActuator):
+	"""
+	ShapeAction Actuators apply an shape action to an mesh object.
+	"""
+	def setAction(action, reset = True):
+		"""
+		Sets the current action.
+		
+		@param action: The name of the action to set as the current action.
+		@type action: string
+		@param reset: Optional parameter indicating whether to reset the
+		              blend timer or not.  A value of 1 indicates that the
+		              timer should be reset.  A value of 0 will leave it
+		              unchanged.  If reset is not specified, the timer will
+		              be reset.
+		"""
+
+	def setStart(start):
+		"""
+		Specifies the starting frame of the animation.
+		
+		@param start: the starting frame of the animation
+		@type start: float
+		"""
+
+	def setEnd(end):
+		"""
+		Specifies the ending frame of the animation.
+		
+		@param end: the ending frame of the animation
+		@type end: float
+		"""
+	def setBlendin(blendin):
+		"""
+		Specifies the number of frames of animation to generate
+		when making transitions between actions.
+		
+		@param blendin: the number of frames in transition.
+		@type blendin: float
+		"""
+
+	def setPriority(priority):
+		"""
+		Sets the priority of this actuator.
+		
+		@param priority: Specifies the new priority.  Actuators will lower
+		                 priority numbers will override actuators with higher
+		                 numbers.
+		@type priority: integer
+		"""
+	def setFrame(frame):
+		"""
+		Sets the current frame for the animation.
+		
+		@param frame: Specifies the new current frame for the animation
+		@type frame: float
+		"""
+
+	def setProperty(prop):
+		"""
+		Sets the property to be used in FromProp playback mode.
+		
+		@param prop: the name of the property to use.
+		@type prop: string.
+		"""
+
+	def setBlendtime(blendtime):
+		"""
+		Sets the internal frame timer.
+		 
+		Allows the script to directly modify the internal timer
+		used when generating transitions between actions.  
+		
+		@param blendtime: The new time. This parameter must be in the range from 0.0 to 1.0.
+		@type blendtime: float
+		"""
+
+	def setType(mode):
+		"""
+		Sets the operation mode of the actuator
+
+		@param mode: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
+		@type mode: integer
+		"""
+	
+	def setContinue(cont):
+		"""
+		Set the actions continue option True or False. see getContinue.
+
+		@param cont: The continue option.
+		@type cont: bool
+		"""
+
+	def getType():
+		"""
+		Returns the operation mode of the actuator
+	    
+		@rtype: integer
+		@return: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
+		"""
+
+	def getContinue():
+		"""
+		When True, the action will always play from where last left off, otherwise negative events to this actuator will reset it to its start frame.
+	    
+		@rtype: bool
+		"""
+	
+	def getAction():
+		"""
+		getAction() returns the name of the action associated with this actuator.
+		
+		@rtype: string
+		"""
+	
+	def getStart():
+		"""
+		Returns the starting frame of the action.
+		
+		@rtype: float
+		"""
+	def getEnd():
+		"""
+		Returns the last frame of the action.
+		
+		@rtype: float
+		"""
+	def getBlendin():
+		"""
+		Returns the number of interpolation animation frames to be generated when this actuator is triggered.
+		
+		@rtype: float
+		"""
+	def getPriority():
+		"""
+		Returns the priority for this actuator.  Actuators with lower Priority numbers will
+		override actuators with higher numbers.
+		
+		@rtype: integer
+		"""
+	def getFrame():
+		"""
+		Returns the current frame number.
+		
+		@rtype: float
+		"""
+	def getProperty():
+		"""
+		Returns the name of the property to be used in FromProp mode.
+		
+		@rtype: string
+		"""
+
+
diff --git a/source/gameengine/PyDoc/KX_ActuatorSensor.py b/source/gameengine/PyDoc/KX_ActuatorSensor.py
new file mode 100644
index 00000000000..f9aef86f7f0
--- /dev/null
+++ b/source/gameengine/PyDoc/KX_ActuatorSensor.py
@@ -0,0 +1,24 @@
+# $Id$
+# Documentation for KX_ActuatorSensor
+from SCA_IActuator import *
+
+class KX_ActuatorSensor(SCA_ISensor):
+	"""
+	Actuator sensor detect change in actuator state of the parent object.
+	It generates a positive pulse if the corresponding actuator is activated
+	and a negative pulse if the actuator is deactivated.
+	"""
+	def getActuator():
+		"""
+		Return the Actuator with which the sensor operates.
+		
+		@rtype: string
+		"""
+	def setActuator(name):
+		"""
+		Sets the Actuator with which to operate. If there is no Actuator
+		of this name, the function has no effect.
+		
+		@param name: actuator name
+		@type name: string
+		"""
diff --git a/source/gameengine/PyDoc/KX_ConstraintActuator.py b/source/gameengine/PyDoc/KX_ConstraintActuator.py
index 9630690e572..b1c6f3c0f4e 100644
--- a/source/gameengine/PyDoc/KX_ConstraintActuator.py
+++ b/source/gameengine/PyDoc/KX_ConstraintActuator.py
@@ -4,7 +4,7 @@ from SCA_IActuator import *
 
 class KX_ConstraintActuator(SCA_IActuator):
 	"""
-	A constraint actuator limits the position or orientation of an object.
+	A constraint actuator limits the position, rotation, distance or orientation of an object.
 	"""
 	def setDamp(time):
 		"""
@@ -24,7 +24,7 @@ class KX_ConstraintActuator(SCA_IActuator):
 		"""
 		Sets the lower bound of the constraint.
 		
-		For rotational constraints, lower is specified in degrees.
+		For rotational and orientation constraints, lower is specified in degrees.
 		
 		@type lower: float
 		"""
@@ -32,7 +32,7 @@ class KX_ConstraintActuator(SCA_IActuator):
 		"""
 		Gets the lower bound of the constraint.
 		
-		For rotational constraints, the lower bound is returned in radians.
+		For rotational and orientation constraints, the lower bound is returned in radians.
 		
 		@rtype: float
 		"""
@@ -40,7 +40,7 @@ class KX_ConstraintActuator(SCA_IActuator):
 		"""
 		Sets the upper bound of the constraint.
 		
-		For rotational constraints, upper is specified in degrees.
+		For rotational and orientation constraints, upper is specified in degrees.
 		
 		@type upper: float
 		"""
@@ -48,7 +48,7 @@ class KX_ConstraintActuator(SCA_IActuator):
 		"""
 		Gets the upper bound of the constraint.
 		
-		For rotational constraints, the upper bound is returned in radians.
+		For rotational and orientation constraints, the upper bound is returned in radians.
 		
 		@rtype: float
 		"""
@@ -60,6 +60,9 @@ class KX_ConstraintActuator(SCA_IActuator):
 		
 		@param limit: Position constraints: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, 
 		              Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY or KX_CONSTRAINTACT_ROTZ
+		              Distance contraints: KX_ACT_CONSTRAINT_DIRPX, KX_ACT_CONSTRAINT_DIRPY, KX_ACT_CONSTRAINT_DIRPZ,
+		                                   KX_ACT_CONSTRAINT_DIRNX, KX_ACT_CONSTRAINT_DIRNY, KX_ACT_CONSTRAINT_DIRNZ,
+		              Orientation constraints: KX_ACT_CONSTRAINT_ORIX, KX_ACT_CONSTRAINT_ORIY, KX_ACT_CONSTRAINT_ORIZ
 		"""
 	def getLimit():
 		"""
@@ -68,5 +71,110 @@ class KX_ConstraintActuator(SCA_IActuator):
 		See module L{GameLogic} for valid constraints.
 		
 		@return: Position constraints: KX_CONSTRAINTACT_LOCX, KX_CONSTRAINTACT_LOCY, KX_CONSTRAINTACT_LOCZ, 
-		         Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY or KX_CONSTRAINTACT_ROTZ
+		         Rotation constraints: KX_CONSTRAINTACT_ROTX, KX_CONSTRAINTACT_ROTY, KX_CONSTRAINTACT_ROTZ,
+		         Distance contraints: KX_ACT_CONSTRAINT_DIRPX, KX_ACT_CONSTRAINT_DIRPY, KX_ACT_CONSTRAINT_DIRPZ,
+		                              KX_ACT_CONSTRAINT_DIRNX, KX_ACT_CONSTRAINT_DIRNY, KX_ACT_CONSTRAINT_DIRNZ,
+		         Orientation constraints: KX_ACT_CONSTRAINT_ORIX, KX_ACT_CONSTRAINT_ORIY, KX_ACT_CONSTRAINT_ORIZ
 		"""
+	def setRotDamp(duration):
+		"""
+		Sets the time constant of the orientation constraint.
+		
+		@param duration: If the duration is negative, it is set to 0.
+		@type duration: integer
+		"""
+	def getRotDamp():
+		""" 
+		Returns the damping time for application of the constraint.
+		
+		@rtype: integer
+		"""
+	def setDirection(vector):
+		"""
+		Sets the reference direction in world coordinate for the orientation constraint
+		
+		@type vector: 3-tuple
+		"""
+	def getDirection():
+		"""
+		Returns the reference direction of the orientation constraint in world coordinate.
+		
+		@rtype: 3-tuple
+		"""
+	def setOption(option):
+		"""
+		Sets several options of the distance constraint.
+		
+		@type option: integer
+		@param option: Binary combination of the following values:
+		                64 : Activate alignment to surface
+		               128 : Detect material rather than property
+		               256 : No deactivation if ray does not hit target
+		               512 : Activate distance control
+		"""
+	def getOption():
+		"""
+		Returns the option parameter.
+		
+		@rtype: integer
+		"""
+	def setTime(duration):
+		"""
+		Sets the activation time of the actuator.
+		
+		@type duration: integer
+		@param duration: The actuator disables itself after this many frame.
+		                 If set to 0 or negative, the actuator is not limited in time.
+		"""
+	def getTime():
+		"""
+		Returns the time parameter.
+		
+		@rtype: integer
+		"""
+	def setProperty(property):
+		"""
+		Sets the name of the property or material for the ray detection of the distance constraint.
+		
+		@type property: string
+		@param property: If empty, the ray will detect any collisioning object.
+		"""
+	def getProperty():
+		"""
+		Returns the property parameter.
+		
+		@rtype: string
+		"""
+	def setDistance(distance):
+		"""
+		Sets the target distance in distance constraint.
+		
+		@type distance: float
+		"""
+	def getDistance():
+		"""
+		Returns the distance parameter.
+		
+		@rtype: float
+		"""
+	def setRayLength(length):
+		"""
+		Sets the maximum ray length of the distance constraint.
+		
+		@type length: float
+		"""
+	def getRayLength():
+		"""
+		Returns the length of the ray
+		
+		@rtype: float
+		"""
+
+
+
+
+
+
+
+
+		
diff --git a/source/gameengine/PyDoc/KX_IpoActuator.py b/source/gameengine/PyDoc/KX_IpoActuator.py
index da8d05ddd5e..1cdab829385 100644
--- a/source/gameengine/PyDoc/KX_IpoActuator.py
+++ b/source/gameengine/PyDoc/KX_IpoActuator.py
@@ -6,7 +6,7 @@ class KX_IpoActuator(SCA_IActuator):
 	"""
 	IPO actuator activates an animation.
 	"""
-	def set(mode, startframe, endframe, force):
+	def set(mode, startframe, endframe, mode):
 		"""
 		Sets the properties of the actuator.
 		
@@ -16,8 +16,8 @@ class KX_IpoActuator(SCA_IActuator):
 		@type startframe: integer
 		@param endframe: last frame to use
 		@type endframe: integer
-		@param force: interpret this ipo as a force
-		@type force: boolean (KX_TRUE, KX_FALSE)
+		@param mode: special mode
+		@type mode: integer (0=normal, 1=interpret location as force, 2=additive)
 		"""
 	def setProperty(property):
 		"""
@@ -62,6 +62,19 @@ class KX_IpoActuator(SCA_IActuator):
 		
 		@rtype: boolean
 		"""
+	def setIpoAdd(add):
+		"""
+		Set whether to interpret the ipo as additive rather than absolute.
+		
+		@type add: boolean
+		@param add: KX_TRUE or KX_FALSE
+		"""
+	def getIpoAdd():
+		"""
+		Returns whether to interpret the ipo as additive rather than absolute.
+		
+		@rtype: boolean
+		"""
 	def setType(mode):
 		"""
 		Sets the operation mode of the actuator.
diff --git a/source/gameengine/PyDoc/KX_ObjectActuator.py b/source/gameengine/PyDoc/KX_ObjectActuator.py
index 532c18eea5c..db577d21e6f 100644
--- a/source/gameengine/PyDoc/KX_ObjectActuator.py
+++ b/source/gameengine/PyDoc/KX_ObjectActuator.py
@@ -6,6 +6,7 @@ class KX_ObjectActuator(SCA_IActuator):
 	"""
 	The object actuator ("Motion Actuator") applies force, torque, displacement, angular displacement,
 	velocity, or angular velocity to an object.
+	Servo control allows to regulate force to achieve a certain speed target.
 	"""
 	def getForce():
 		"""
@@ -107,15 +108,17 @@ class KX_ObjectActuator(SCA_IActuator):
 	def getLinearVelocity():
 		"""
 		Returns the linear velocity applied by the actuator.
+		For the servo control actuator, this is the target speed.
 		
 		@rtype: list [vx, vy, vz, local]
 		@return: A four item list, containing the vector velocity, and whether
 		         the velocity is applied in local coordinates (True) or world
-			 coordinates (False)
+			     coordinates (False)
 		"""
 	def setLinearVelocity(vx, vy, vz, local):
 		"""
 		Sets the linear velocity applied by the actuator.
+		For the servo control actuator, sets the target speed.
 		
 		@type vx: float
 		@param vx: the x component of the velocity vector.
@@ -124,8 +127,8 @@ class KX_ObjectActuator(SCA_IActuator):
 		@type vz: float
 		@param vz: the z component of the velocity vector.
 		@type local: boolean
-		@param local: - False: the velocity vector is applied in world coordinates.
-		              - True: the velocity vector is applied in local coordinates.
+		@param local: - False: the velocity vector is in world coordinates.
+		              - True: the velocity vector is in local coordinates.
 		"""
 	def getAngularVelocity():
 		"""
@@ -150,5 +153,100 @@ class KX_ObjectActuator(SCA_IActuator):
 		@param local: - False: the velocity vector is applied in world coordinates.
 		              - True: the velocity vector is applied in local coordinates.
 		"""
+	def getDamping():
+		"""
+		Returns the damping parameter of the servo controller.
+		
+		@rtype: integer
+		@return: the time constant of the servo controller in frame unit.
+		"""
+	def setDamping(damp):
+		"""
+		Sets the damping parameter of the servo controller.
+		
+		@type damp: integer
+		@param damp: the damping parameter in frame unit.
+		"""
+	def getForceLimitX():
+		"""
+		Returns the min/max force limit along the X axis used by the servo controller.
+		
+		@rtype: list [min, max, enabled]
+		@return: A three item list, containing the min and max limits of the force as float
+		         and whether the limits are active(true) or inactive(true)
+		"""
+	def setForceLimitX(min, max, enable):
+		"""
+		Sets the min/max force limit along the X axis and activates or deactivates the limits in the servo controller.
+		
+		@type min: float
+		@param min: the minimum value of the force along the X axis.
+		@type max: float
+		@param max: the maximum value of the force along the X axis.
+		@type enable: boolean
+		@param enable: - True: the force will be limited to the min/max
+		               - False: the force will not be limited		               
+		"""
+	def getForceLimitY():
+		"""
+		Returns the min/max force limit along the Y axis used by the servo controller.
+		
+		@rtype: list [min, max, enabled]
+		@return: A three item list, containing the min and max limits of the force as float
+		         and whether the limits are active(true) or inactive(true)
+		"""
+	def setForceLimitY(min, max, enable):
+		"""
+		Sets the min/max force limit along the Y axis and activates or deactivates the limits in the servo controller.
+		
+		@type min: float
+		@param min: the minimum value of the force along the Y axis.
+		@type max: float
+		@param max: the maximum value of the force along the Y axis.
+		@type enable: boolean
+		@param enable: - True: the force will be limited to the min/max
+		               - False: the force will not be limited		               
+		"""
+	def getForceLimitZ():
+		"""
+		Returns the min/max force limit along the Z axis used by the servo controller.
+		
+		@rtype: list [min, max, enabled]
+		@return: A three item list, containing the min and max limits of the force as float
+		         and whether the limits are active(true) or inactive(true)
+		"""
+	def setForceLimitZ(min, max, enable):
+		"""
+		Sets the min/max force limit along the Z axis and activates or deactivates the limits in the servo controller.
+		
+		@type min: float
+		@param min: the minimum value of the force along the Z axis.
+		@type max: float
+		@param max: the maximum value of the force along the Z axis.
+		@type enable: boolean
+		@param enable: - True: the force will be limited to the min/max
+		               - False: the force will not be limited		               
+		"""
+	def getPID():
+		"""
+		Returns the PID coefficient of the servo controller.
+		
+		@rtype: list [P, I, D]
+		@return: A three item list, containing the PID coefficient as floats:
+		         P : proportional coefficient
+		         I : Integral coefficient
+		         D : Derivate coefficient
+		"""
+	def setPID(P, I, D):
+		"""
+		Sets the PID coefficients of the servo controller.
+		
+		@type P: flat
+		@param P: proportional coefficient
+		@type I: float
+		@param I: Integral coefficient
+		@type D: float
+		@param D: Derivate coefficient
+		"""
 
 
diff --git a/source/gameengine/PyDoc/KX_StateActuator.py b/source/gameengine/PyDoc/KX_StateActuator.py
new file mode 100644
index 00000000000..fb6ae5a3621
--- /dev/null
+++ b/source/gameengine/PyDoc/KX_StateActuator.py
@@ -0,0 +1,26 @@
+# $Id$
+# Documentation for KX_StateActuator
+from SCA_IActuator import *
+
+class KX_StateActuator(SCA_IActuator):
+	"""
+	State actuator changes the state mask of parent object.
+	"""
+	def setOperation(op):
+		"""
+		Set the type of bit operation to be applied on object state mask.
+		Use setMask() to specify the bits that will be modified.
+		
+		@param op: bit operation (0=Copy, 1=Add, 2=Substract, 3=Invert)
+		@type op: integer
+		"""
+	def setMask(mask):
+		"""
+		Set the value that defines the bits that will be modified by the operation.
+		The bits that are 1 in the value will be updated in the object state,
+		the bits that are 0 are will be left unmodified expect for the Copy operation
+		which copies the value to the object state.
+		
+		@param mask: bits that will be modified
+		@type mask: integer
+		"""
diff --git a/source/gameengine/PyDoc/SCA_ISensor.py b/source/gameengine/PyDoc/SCA_ISensor.py
index b96d8c8c075..0ebc2debb31 100644
--- a/source/gameengine/PyDoc/SCA_ISensor.py
+++ b/source/gameengine/PyDoc/SCA_ISensor.py
@@ -59,4 +59,22 @@ class SCA_ISensor(SCA_ILogicBrick):
 		@type invert: boolean
 		@param invert: true if activates on negative events; false if activates on positive events.
 		"""
+	def getLevel():
+		"""
+		Returns whether this sensor is a level detector or a edge detector.
+		It makes a difference only in case of logic state transition (state actuator).
+		A level detector will immediately generate a pulse, negative or positive
+		depending on the sensor condition, as soon as the state is activated.
+		A edge detector will wait for a state change before generating a pulse.
+		
+		@rtype: boolean
+		@return: true if sensor is level sensitive, false if it is edge sensitive
+		"""
+	def setLevel(level):
+		"""
+		Set whether to detect level or edge transition when entering a state.
+		
+		@param level: Detect level instead of edge? (KX_TRUE, KX_FALSE)
+		@type level: boolean
+		"""