From 1c663bbc7e53cda1fe35579302574b0d98aa8db3 Mon Sep 17 00:00:00 2001
From: Benoit Bolsee <benoit.bolsee@online.be>
Date: Mon, 29 Dec 2008 16:36:58 +0000
Subject: First batch of GE API cleanup.

The principle is to replace most get/set methods of logic bricks by direct property access.
To make porting of game code easier, the properties have usually the same type and use than
the return values/parameters of the get/set methods.
More details on http://wiki.blender.org/index.php/GameEngineDev/Python_API_Clean_Up

Old methods are still available but will produce deprecation warnings on the console:

"<method> is deprecated, use the <property> property instead"

You can avoid these messages by turning on the "Ignore deprecation warnings" option in Game menu.

PyDoc is updated to include the new properties and display a deprecation warning
for the get/set methods that are being deprecated.
---
 source/gameengine/PyDoc/KX_ActuatorSensor.py    |  7 +++
 source/gameengine/PyDoc/SCA_DelaySensor.py      | 17 +++++++
 source/gameengine/PyDoc/SCA_ILogicBrick.py      |  9 ++++
 source/gameengine/PyDoc/SCA_ISensor.py          | 34 ++++++++++---
 source/gameengine/PyDoc/SCA_JoystickSensor.py   | 59 +++++++++++++++++++++-
 source/gameengine/PyDoc/SCA_KeyboardSensor.py   | 65 +++++++++++++++++++++++--
 source/gameengine/PyDoc/SCA_MouseSensor.py      | 11 +++++
 source/gameengine/PyDoc/SCA_PropertyActuator.py | 11 +++++
 source/gameengine/PyDoc/SCA_PropertySensor.py   | 17 +++++++
 source/gameengine/PyDoc/SCA_PythonController.py | 10 ++++
 source/gameengine/PyDoc/SCA_RandomActuator.py   | 32 ++++++++++++
 11 files changed, 259 insertions(+), 13 deletions(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/KX_ActuatorSensor.py b/source/gameengine/PyDoc/KX_ActuatorSensor.py
index cdfbf27576e..b0e138a8009 100644
--- a/source/gameengine/PyDoc/KX_ActuatorSensor.py
+++ b/source/gameengine/PyDoc/KX_ActuatorSensor.py
@@ -8,15 +8,22 @@ 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.
+	
+	Properties:
+	
+	@ivar actuator: the name of the actuator that the sensor is monitoring.
+	@type actuator: string
 	"""
 	def getActuator():
 		"""
+		DEPRECATED: use the actuator property
 		Return the Actuator with which the sensor operates.
 		
 		@rtype: string
 		"""
 	def setActuator(name):
 		"""
+		DEPRECATED: use the actuator property
 		Sets the Actuator with which to operate. If there is no Actuator
 		of this name, the function has no effect.
 		
diff --git a/source/gameengine/PyDoc/SCA_DelaySensor.py b/source/gameengine/PyDoc/SCA_DelaySensor.py
index 19df589ea7b..b99ed08bed5 100644
--- a/source/gameengine/PyDoc/SCA_DelaySensor.py
+++ b/source/gameengine/PyDoc/SCA_DelaySensor.py
@@ -13,9 +13,21 @@ class SCA_DelaySensor(SCA_ISensor):
 	The sensor runs the OFF-ON cycle once unless the repeat option is set: the
 	OFF-ON cycle repeats indefinately (or the OFF cycle if duration is 0).
 	Use SCA_ISensor::reset() at any time to restart sensor.
+
+	Properties:
+	
+	@ivar delay: length of the initial OFF period as number of frame, 0 for immediate trigger.
+	@type delay: integer.
+	@ivar duration: length of the ON period in number of frame after the initial OFF period.
+	                If duration is greater than 0, a negative trigger is sent at the end of the ON pulse.
+    @type duration: integer
+    @ivar repeat: 1 if the OFF-ON cycle should be repeated indefinately, 0 if it should run once.
+    @type repeat: integer
+    
 	"""
 	def setDelay(delay):
 		"""
+		DEPRECATED: use the delay property
 		Set the initial delay before the positive trigger.
 		
 		@param delay: length of the initial OFF period as number of frame, 0 for immediate trigger
@@ -23,6 +35,7 @@ class SCA_DelaySensor(SCA_ISensor):
 		"""
 	def setDuration(duration):
 		"""
+		DEPRECATED: use the duration property
 		Set the duration of the ON pulse after initial delay and the generation of the positive trigger.
 		If duration is greater than 0, a negative trigger is sent at the end of the ON pulse.
 		
@@ -31,6 +44,7 @@ class SCA_DelaySensor(SCA_ISensor):
 		"""	
 	def setRepeat(repeat):
 		"""
+		DEPRECATED: use the repeat property
 		Set if the sensor repeat mode.
 		
 		@param repeat: 1 if the OFF-ON cycle should be repeated indefinately, 0 if it should run once.
@@ -38,18 +52,21 @@ class SCA_DelaySensor(SCA_ISensor):
 		"""		
 	def getDelay():
 		"""
+		DEPRECATED: use the delay property
 		Return the delay parameter value.
 		
 		@rtype: integer
 		"""
 	def getDuration():
 		"""
+		DEPRECATED: use the duration property
 		Return the duration parameter value
 		
 		@rtype: integer
 		"""
 	def getRepeat():
 		"""
+		DEPRECATED: use the repeat property
 		Return the repeat parameter value
 		
 		@rtype: KX_TRUE or KX_FALSE
diff --git a/source/gameengine/PyDoc/SCA_ILogicBrick.py b/source/gameengine/PyDoc/SCA_ILogicBrick.py
index ea09fcaea37..18cb900f28d 100644
--- a/source/gameengine/PyDoc/SCA_ILogicBrick.py
+++ b/source/gameengine/PyDoc/SCA_ILogicBrick.py
@@ -5,6 +5,9 @@ from KX_GameObject import *
 class SCA_ILogicBrick:
 	"""
 	Base class for all logic bricks.
+	
+	@ivar executePriority: This determines the order controllers are evaluated, and actuators are activated (lower priority is executed first).
+	@type executePriority: int
 	"""
 	
 	def getOwner():
@@ -13,6 +16,8 @@ class SCA_ILogicBrick:
 		
 		@rtype: L{KX_GameObject}
 		"""
+
+	#--The following methods are deprecated--
 	def setExecutePriority(priority):
 		"""
 		Sets the priority of this logic brick.
@@ -20,6 +25,8 @@ class SCA_ILogicBrick:
 		This determines the order controllers are evaluated, and actuators are activated.
 		Bricks with lower priority will be executed first.
 		
+		Deprecated: Use the "executePriority" property instead.
+		
 		@type priority: integer
 		@param priority: the priority of this logic brick.
 		"""
@@ -27,6 +34,8 @@ class SCA_ILogicBrick:
 		"""
 		Gets the execution priority of this logic brick.
 		
+		Deprecated: Use the "executePriority" property instead.
+		
 		@rtype: integer
 		@return: this logic bricks current priority.
 		"""
diff --git a/source/gameengine/PyDoc/SCA_ISensor.py b/source/gameengine/PyDoc/SCA_ISensor.py
index 14858505e24..ab35996aa50 100644
--- a/source/gameengine/PyDoc/SCA_ISensor.py
+++ b/source/gameengine/PyDoc/SCA_ISensor.py
@@ -5,8 +5,35 @@ from SCA_ILogicBrick import *
 class SCA_ISensor(SCA_ILogicBrick):
 	"""
 	Base class for all sensor logic bricks.
+	
+	@ivar usePosPulseMode: Flag to turn positive pulse mode on and off.
+	@type usePosPulseMode: boolean
+	@ivar useNegPulseMode: Flag to turn negative pulse mode on and off.
+	@type useNegPulseMode: boolean
+	@ivar frequency: The frequency for pulse mode sensors.
+	@type frequency: int
+	@ivar level: Flag to set whether to detect level or edge transition when entering a state.
+					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.
+	@type level: boolean
+	@ivar invert: Flag to set if this sensor activates on positive or negative events.
+	@type invert: boolean
+	@ivar triggered: True if this sensor brick is in a positive state. (Read only)
+	@type triggered: boolean
+	@ivar positive: True if this sensor brick is in a positive state. (Read only)
+	@type positive: boolean
 	"""
 	
+	def reset():
+		"""
+		Reset sensor internal state, effect depends on the type of sensor and settings.
+		
+		The sensor is put in its initial state as if it was just activated.
+		"""
+		
+	#--The following methods are deprecated--
 	def isPositive():
 		"""
 		True if this sensor brick is in a positive state.
@@ -82,10 +109,3 @@ class SCA_ISensor(SCA_ILogicBrick):
 		@param level: Detect level instead of edge? (KX_TRUE, KX_FALSE)
 		@type level: boolean
 		"""
-	def reset():
-		"""
-		Reset sensor internal state, effect depends on the type of sensor and settings.
-		
-		The sensor is put in its initial state as if it was just activated.
-		"""
-
diff --git a/source/gameengine/PyDoc/SCA_JoystickSensor.py b/source/gameengine/PyDoc/SCA_JoystickSensor.py
index d1dab9afcaf..111ee7f4cfa 100644
--- a/source/gameengine/PyDoc/SCA_JoystickSensor.py
+++ b/source/gameengine/PyDoc/SCA_JoystickSensor.py
@@ -5,15 +5,58 @@ from SCA_ISensor import *
 class SCA_JoystickSensor(SCA_ISensor):
 	"""
 	This sensor detects player joystick events.
+	
+	Properties:
+	
+	@ivar axisPosition: (read-only) The state of the joysticks axis as a list of 4 values, each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing. 
+	                    The first 2 values are used by most joysticks and gamepads for directional control. 3rd and 4th values are only on some joysticks and can be used for arbitary controls.
+	                    left:[-32767, 0, ...], right:[32767, 0, ...], up:[0, -32767, ...], down:[0, 32767, ...]
+	@type axisPosition: [integer, integer, integer, integer]
+	@ivar numAxis: (read-only) The number of axes for the joystick at this index.
+	@type numAxis: integer
+	@ivar numButtons: (read-only) The number of buttons for the joystick at this index.
+	@type numButtons: integer
+	@ivar numHats: (read-only) The number of hats for the joystick at this index.
+	@type numHats: integer
+	@ivar connected: (read-only) True if a joystick is connected at this joysticks index.
+	@type connected: boolean
+	@ivar index: The joystick index to use (from 0 to 7). The first joystick is always 0.
+	@type index: integer
+	@ivar threshold: Axis threshold. Joystick axis motion below this threshold wont trigger an event. Use values between (0 and 32767), lower values are more sensitive.
+	@type threshold: integer
+	@ivar button: The button index the sensor reacts to (first button = 0). When the "All Events" toggle is set, this option has no effect.
+	@type button: integer
+	@ivar axis: The axis this sensor reacts to, as a list of two values [axisIndex, axisDirection]
+	            axisIndex: the axis index to use when detecting axis movement, 1=primary directional control, 2=secondary directional control.
+	            axisDirection: 0=right, 1=up, 2=left, 3=down
+	@type axis: [integer, integer]
+	@ivar hat: The hat the sensor reacts to, as a list of two values: [hatIndex, hatDirection]
+	            hatIndex: the hat index to use when detecting hat movement, 1=primary hat, 2=secondary hat.
+	            hatDirection: 0-11
+	@type hat: [integer, integer]
 	"""
 	
+	def getButtonActiveList():
+		"""
+		Returns a list containing the indicies of the currently pressed buttons.
+		@rtype: list
+		"""
+    def getButtonStatus(buttonIndex):
+        """
+        Returns a bool of the current pressed state of the specified button.
+        @param buttonIndex: the button index, 0=first button
+        @type buttonIndex: integer
+        @rtype: bool
+        """
 	def getIndex():
 		"""
+		DEPRECATED: use the 'index' property.
 		Returns the joystick index to use (from 1 to 8).
 		@rtype: integer
 		"""
 	def setIndex(index):
 		"""
+		DEPRECATED: use the 'index' property.
 		Sets the joystick index to use. 
 		@param index: The index of this joystick sensor, Clamped between 1 and 8.
 		@type index: integer
@@ -21,6 +64,7 @@ class SCA_JoystickSensor(SCA_ISensor):
 		"""
 	def getAxis():
 		"""
+		DEPRECATED: use the 'axis' property.
 		Returns the current axis this sensor reacts to. See L{getAxisValue()<SCA_JoystickSensor.getAxisValue>} for the current axis state.
 		@rtype: list
 		@return: 2 values returned are [axisIndex, axisDirection] - see L{setAxis()<SCA_JoystickSensor.setAxis>} for their purpose.
@@ -28,6 +72,7 @@ class SCA_JoystickSensor(SCA_ISensor):
 		"""
 	def setAxis(axisIndex, axisDirection):
 		"""
+		DEPRECATED: use the 'axis' property.
 		@param axisIndex: Set the axis index to use when detecting axis movement.
 		@type axisIndex: integer from 1 to 2
 		@param axisDirection: Set the axis direction used for detecting motion. 0:right, 1:up, 2:left, 3:down.
@@ -36,6 +81,7 @@ class SCA_JoystickSensor(SCA_ISensor):
 		"""
 	def getAxisValue():
 		"""
+		DEPRECATED: use the 'axisPosition' property.
 		Returns the state of the joysticks axis. See differs to L{getAxis()<SCA_JoystickSensor.getAxis>} returning the current state of the joystick.
 		@rtype: list
 		@return: 4 values, each spesifying the value of an axis between -32767 and 32767 depending on how far the axis is pushed, 0 for nothing. 
@@ -47,60 +93,71 @@ class SCA_JoystickSensor(SCA_ISensor):
 		"""
 	def getThreshold():
 		"""
+		DEPRECATED: use the 'threshold' property.
 		Get the axis threshold. See L{setThreshold()<SCA_JoystickSensor.setThreshold>} for details.
 		@rtype: integer
 		"""
 	def setThreshold(threshold):
 		"""
+		DEPRECATED: use the 'threshold' property.
 		Set the axis threshold.
 		@param threshold: Joystick axis motion below this threshold wont trigger an event. Use values between (0 and 32767), lower values are more sensitive.
 		@type threshold: integer
 		"""
 	def getButton():
 		"""
+		DEPRECATED: use the 'button' property.
 		Returns the button index the sensor reacts to. See L{getButtonValue()<SCA_JoystickSensor.getButtonValue>} for a list of pressed buttons.
 		@rtype: integer
 		@note: When the "All Events" toggle is set, this option has no effect.
 		"""
 	def setButton(index):
 		"""
+		DEPRECATED: use the 'button' property.
 		Sets the button index the sensor reacts to when the "All Events" option is not set.
 		@note: When the "All Events" toggle is set, this option has no effect.
 		"""
 	def getButtonValue():
 		"""
+		DEPRECATED: use the 'getButtonActiveList' method.
 		Returns a list containing the indicies of the currently pressed buttons.
 		@rtype: list
 		"""
 	def getHat():
 		"""
+		DEPRECATED: use the 'hat' property.
 		Returns the current hat direction this sensor is set to.
 		[hatNumber, hatDirection].
 		@rtype: list
 		@note: When the "All Events" toggle is set, this option has no effect.
 		"""
-	def setHat(index):
+	def setHat(index,direction):
 		"""
+		DEPRECATED: use the 'hat' property.
 		Sets the hat index the sensor reacts to when the "All Events" option is not set.
 		@type index: integer
 		"""
 	def getNumAxes():
 		"""
+		DEPRECATED: use the 'numAxis' property.
 		Returns the number of axes for the joystick at this index.
 		@rtype: integer
 		"""
 	def getNumButtons():
 		"""
+		DEPRECATED: use the 'numButtons' property.
 		Returns the number of buttons for the joystick at this index.
 		@rtype: integer
 		"""
 	def getNumHats():
 		"""
+		DEPRECATED: use the 'numHats' property.
 		Returns the number of hats for the joystick at this index.
 		@rtype: integer
 		"""
 	def isConnected():
 		"""
+		DEPRECATED: use the 'connected' property.
 		Returns True if a joystick is detected at this joysticks index.
 		@rtype: bool
 		"""
diff --git a/source/gameengine/PyDoc/SCA_KeyboardSensor.py b/source/gameengine/PyDoc/SCA_KeyboardSensor.py
index 2f741f7d6a2..f6a7a7d8a97 100644
--- a/source/gameengine/PyDoc/SCA_KeyboardSensor.py
+++ b/source/gameengine/PyDoc/SCA_KeyboardSensor.py
@@ -7,44 +7,99 @@ class SCA_KeyboardSensor(SCA_ISensor):
 	A keyboard sensor detects player key presses.
 	
 	See module L{GameKeys} for keycode values.
+	
+	@ivar key: The key code this sensor is looking for.
+	@type key: keycode from L{GameKeys} module
+	@ivar hold1: The key code for the first modifier this sensor is looking for.
+	@type hold1: keycode from L{GameKeys} module
+	@ivar hold2: The key code for the second modifier this sensor is looking for.
+	@type hold2: keycode from L{GameKeys} module
+	@ivar toggleProperty: The name of the property that indicates whether or not to log keystrokes as a string.
+	@type toggleProperty: string
+	@ivar targetProperty: The name of the property that receives keystrokes in case in case a string is logged.
+	@type targetProperty: string
+	@ivar useAllKeys: Flag to determine whether or not to accept all keys.
+	@type useAllKeys: boolean
 	"""
+	def getEventList():
+		"""
+		Get a list of pressed keys that have either been pressed, or just released, or are active this frame.
+		
+		@rtype: list of key status. [[keycode, status]]
+		@return: A list of keyboard events
+		"""
+	
+	def getKeyStatus(keycode):
+		"""
+		Get the status of a key.
+		
+		@rtype: key state (KX_NO_INPUTSTATUS, KX_JUSTACTIVATED, KX_ACTIVE or KX_JUSTRELEASED)
+		@return: The state of the given key
+		@type keycode: integer
+		@param keycode: The code that represents the key you want to get the state of
+		"""
 	
+	#--The following methods are deprecated--
 	def getKey():
 		"""
 		Returns the key code this sensor is looking for.
+		
+		Deprecated: Use the "key" property instead.
+		
+		@rtype: keycode from L{GameKeys} module
 		"""
 	
 	def setKey(keycode):
 		"""
 		Set the key this sensor should listen for.
 		
+		Deprecated: Use the "key" property instead.
+		
 		@type keycode: keycode from L{GameKeys} module
 		"""
 	
 	def getHold1():
 		"""
 		Returns the key code for the first modifier this sensor is looking for.
+		
+		Deprecated: Use the "hold1" property instead.
+		
+		@rtype: keycode from L{GameKeys} module
 		"""
 	
-	def setHold1():
+	def setHold1(keycode):
 		"""
 		Sets the key code for the first modifier this sensor should look for.
+		
+		Deprecated: Use the "hold1" property instead.
+		
+		@type keycode: keycode from L{GameKeys} module
 		"""
 	
 	def getHold2():
 		"""
 		Returns the key code for the second modifier this sensor is looking for.
+		
+		Deprecated: Use the "hold2" property instead.
+		
+		@rtype: keycode from L{GameKeys} module
 		"""
 	
-	def setHold2():
+	def setHold2(keycode):
 		"""
 		Sets the key code for the second modifier this sensor should look for.
+		
+		Deprecated: Use the "hold2" property instead.
+		
+		@type keycode: keycode from L{GameKeys} module
 		"""
 	
 	def getPressedKeys():
 		"""
 		Get a list of keys that have either been pressed, or just released this frame.
 		
+		Deprecated: Use getEventList() instead.
+		
 		@rtype: list of key status. [[keycode, status]]
 		"""
 	
@@ -52,7 +107,7 @@ class SCA_KeyboardSensor(SCA_ISensor):
 		"""
 		Get a list of currently pressed keys that have either been pressed, or just released
 		
+		Deprecated: Use getEventList() instead.
+		
 		@rtype: list of key status. [[keycode, status]]
-		"""
-	
-
+		"""
\ No newline at end of file
diff --git a/source/gameengine/PyDoc/SCA_MouseSensor.py b/source/gameengine/PyDoc/SCA_MouseSensor.py
index 06b261f67fa..9550cbb4105 100644
--- a/source/gameengine/PyDoc/SCA_MouseSensor.py
+++ b/source/gameengine/PyDoc/SCA_MouseSensor.py
@@ -5,10 +5,20 @@ from SCA_ISensor import *
 class SCA_MouseSensor(SCA_ISensor):
 	"""
 	Mouse Sensor logic brick.
+	
+	Properties:
+	
+	@ivar position: current [x,y] coordinates of the mouse, in frame coordinates (pixels)
+	@type position: [integer,interger]
+	@ivar mode: sensor mode: 1=KX_MOUSESENSORMODE_LEFTBUTTON  2=KX_MOUSESENSORMODE_MIDDLEBUTTON
+	                         3=KX_MOUSESENSORMODE_RIGHTBUTTON 4=KX_MOUSESENSORMODE_WHEELUP
+	                         5=KX_MOUSESENSORMODE_WHEELDOWN   9=KX_MOUSESENSORMODE_MOVEMENT
+	@type mode: integer
 	"""
 
 	def getXPosition():
 		"""
+		DEPRECATED: use the position property
 		Gets the x coordinate of the mouse.
 		
 		@rtype: integer
@@ -16,6 +26,7 @@ class SCA_MouseSensor(SCA_ISensor):
 		"""
 	def getYPosition():
 		"""
+		DEPRECATED: use the position property
 		Gets the y coordinate of the mouse.
 		
 		@rtype: integer
diff --git a/source/gameengine/PyDoc/SCA_PropertyActuator.py b/source/gameengine/PyDoc/SCA_PropertyActuator.py
index dc1233ddfb7..52aefcae651 100644
--- a/source/gameengine/PyDoc/SCA_PropertyActuator.py
+++ b/source/gameengine/PyDoc/SCA_PropertyActuator.py
@@ -5,9 +5,17 @@ from SCA_IActuator import *
 class SCA_PropertyActuator(SCA_IActuator):
 	"""
 	Property Actuator
+
+	Properties:
+	
+	@ivar property: the property on which to operate.
+	@type property: string
+	@ivar value: the value with which the actuator operates.
+	@type value: string
 	"""
 	def setProperty(prop):
 		"""
+		DEPRECATED: use the 'property' property
 		Set the property on which to operate. 
 		
 		If there is no property of this name, the call is ignored.
@@ -17,12 +25,14 @@ class SCA_PropertyActuator(SCA_IActuator):
 		"""
 	def getProperty():
 		"""
+		DEPRECATED: use the 'property' property
 		Returns the name of the property on which to operate.
 		
 		@rtype: string
 		"""
 	def setValue(value):
 		"""
+		DEPRECATED: use the 'value' property
 		Set the value with which the actuator operates. 
 		
 		If the value is not compatible with the type of the 
@@ -32,6 +42,7 @@ class SCA_PropertyActuator(SCA_IActuator):
 		"""
 	def getValue():
 		"""
+		DEPRECATED: use the 'value' property
 		Gets the value with which this actuator operates.
 		
 		@rtype: string
diff --git a/source/gameengine/PyDoc/SCA_PropertySensor.py b/source/gameengine/PyDoc/SCA_PropertySensor.py
index 22de8d8b986..949ffd3b703 100644
--- a/source/gameengine/PyDoc/SCA_PropertySensor.py
+++ b/source/gameengine/PyDoc/SCA_PropertySensor.py
@@ -5,10 +5,22 @@ from SCA_ISensor import *
 class SCA_PropertySensor(SCA_ISensor):
 	"""
 	Activates when the game object property matches.
+	
+	Properties:
+	
+	@ivar type: type of check on the property: 
+	            KX_PROPSENSOR_EQUAL(1), KX_PROPSENSOR_NOTEQUAL(2), KX_PROPSENSOR_INTERVAL(3), 
+	            KX_PROPSENSOR_CHANGED(4), KX_PROPSENSOR_EXPRESSION(5)
+	@type type: integer
+	@ivar property: the property with which the sensor operates.
+	@type property: string
+	@ivar value: the value with which the sensor compares to the value of the property.
+	@type value: string
 	"""
 	
 	def getType():
 		"""
+		DEPRECATED: use the type property
 		Gets when to activate this sensor.
 		
 		@return: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL,
@@ -18,6 +30,7 @@ class SCA_PropertySensor(SCA_ISensor):
 
 	def setType(checktype):
 		"""
+		DEPRECATED: use the type property
 		Set the type of check to perform.
 		
 		@type checktype: KX_PROPSENSOR_EQUAL, KX_PROPSENSOR_NOTEQUAL,
@@ -27,6 +40,7 @@ class SCA_PropertySensor(SCA_ISensor):
 	
 	def getProperty():
 		"""
+		DEPRECATED: use the property property
 		Return the property with which the sensor operates.
 		
 		@rtype: string
@@ -34,6 +48,7 @@ class SCA_PropertySensor(SCA_ISensor):
 		"""
 	def setProperty(name):
 		"""
+		DEPRECATED: use the property property
 		Sets the property with which to operate.  If there is no property
 		of that name, this call is ignored.
 		
@@ -41,6 +56,7 @@ class SCA_PropertySensor(SCA_ISensor):
 		"""
 	def getValue():
 		"""
+		DEPRECATED: use the value property
 		Return the value with which the sensor compares to the value of the property.
 		
 		@rtype: string
@@ -48,6 +64,7 @@ class SCA_PropertySensor(SCA_ISensor):
 		"""
 	def setValue(value):
 		"""
+		DEPRECATED: use the value property
 		Set the value with which the sensor operates. If the value
 		is not compatible with the type of the property, the subsequent
 		action is ignored.
diff --git a/source/gameengine/PyDoc/SCA_PythonController.py b/source/gameengine/PyDoc/SCA_PythonController.py
index 6d91736d636..06f2b7e9d1d 100644
--- a/source/gameengine/PyDoc/SCA_PythonController.py
+++ b/source/gameengine/PyDoc/SCA_PythonController.py
@@ -6,6 +6,14 @@ class SCA_PythonController(SCA_IController):
 	"""
 	A Python controller uses a Python script to activate it's actuators,
 	based on it's sensors.
+	
+	Properties:
+	
+	@ivar script: the Python script this controller executes
+	@type script: string, read-only
+	@ivar state: the controllers state bitmask.
+	             This can be used with the GameObject's state to test if the controller is active.
+	@type state: integer
 	"""
 
 	def getSensors():
@@ -36,6 +44,7 @@ class SCA_PythonController(SCA_IController):
 		"""
 	def getScript():
 		"""
+		DEPRECATED: use the script property
 		Gets the Python script this controller executes.
 		
 		@rtype: string
@@ -48,6 +57,7 @@ class SCA_PythonController(SCA_IController):
 		"""
 	def getState():
 		"""
+		DEPRECATED: use the state property
 		Get the controllers state bitmask, this can be used with the GameObject's state to test if the the controller is active.
 		This for instance will always be true however you could compare with a previous state to see when the state was activated.
 		GameLogic.getCurrentController().getState() & GameLogic.getCurrentController().getOwner().getState()
diff --git a/source/gameengine/PyDoc/SCA_RandomActuator.py b/source/gameengine/PyDoc/SCA_RandomActuator.py
index 353b398b1ff..000a1af7846 100644
--- a/source/gameengine/PyDoc/SCA_RandomActuator.py
+++ b/source/gameengine/PyDoc/SCA_RandomActuator.py
@@ -5,9 +5,35 @@ from SCA_IActuator import *
 class SCA_RandomActuator(SCA_IActuator):
 	"""
 	Random Actuator
+	
+	Properties:
+	
+	@ivar seed: Seed of the random number generator.
+	            Equal seeds produce equal series. If the seed is 0, 
+	            the generator will produce the same value on every call.
+	@type seed: integer
+	@ivar para1: the first parameter of the active distribution. 
+	             Refer to the documentation of the generator types for the meaning
+	             of this value.
+	@type para1: float, read-only
+	@ivar para2: the second parameter of the active distribution. 
+	             Refer to the documentation of the generator types for the meaning
+	             of this value.
+	@type para2: float, read-only
+	@ivar distribution: distribution type:
+	                    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
+	@type distribution: integer, read-only
+	@ivar property: the name of the property to set with the random value.
+	                If the generator and property types do not match, the assignment is ignored.
+	@type property: string
+
 	"""
 	def setSeed(seed):
 		"""
+		DEPRECATED: use the seed property
 		Sets the seed of the random number generator.
 		
 		Equal seeds produce equal series. If the seed is 0, 
@@ -17,12 +43,14 @@ class SCA_RandomActuator(SCA_IActuator):
 		"""
 	def getSeed():
 		"""
+		DEPRECATED: use the seed property
 		Returns the initial seed of the generator.
 		
 		@rtype: integer
 		"""
 	def getPara1():
 		"""
+		DEPRECATED: use the para1 property
 		Returns the first parameter of the active distribution. 
 		
 		Refer to the documentation of the generator types for the meaning
@@ -32,6 +60,7 @@ class SCA_RandomActuator(SCA_IActuator):
 		"""
 	def getPara2():
 		"""
+		DEPRECATED: use the para2 property
 		Returns the second parameter of the active distribution. 
 		
 		Refer to the documentation of the generator types for the meaning
@@ -41,6 +70,7 @@ class SCA_RandomActuator(SCA_IActuator):
 		"""
 	def getDistribution():
 		"""
+		DEPRECATED: use the distribution property
 		Returns the type of random distribution.
 		
 		@rtype: distribution type
@@ -51,6 +81,7 @@ class SCA_RandomActuator(SCA_IActuator):
 		"""
 	def setProperty(property):
 		"""
+		DEPRECATED: use the property property
 		Set the property to which the random value is assigned. 
 		
 		If the generator and property types do not match, the assignment is ignored.
@@ -60,6 +91,7 @@ class SCA_RandomActuator(SCA_IActuator):
 		"""
 	def getProperty():
 		"""
+		DEPRECATED: use the property property
 		Returns the name of the property to set.
 		
 		@rtype: string
-- 
cgit v1.2.3


From 8bd7aa0a01ee53172bb4fd1bd2de1b318c4ea80c Mon Sep 17 00:00:00 2001
From: Benoit Bolsee <benoit.bolsee@online.be>
Date: Wed, 21 Jan 2009 13:54:53 +0000
Subject: BGE API cleanup: action actuator.

---
 source/gameengine/PyDoc/BL_ActionActuator.py | 52 ++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 10 deletions(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/BL_ActionActuator.py b/source/gameengine/PyDoc/BL_ActionActuator.py
index b68d3014115..5d6ea51060b 100644
--- a/source/gameengine/PyDoc/BL_ActionActuator.py
+++ b/source/gameengine/PyDoc/BL_ActionActuator.py
@@ -5,7 +5,49 @@ from SCA_IActuator import *
 class BL_ActionActuator(SCA_IActuator):
 	"""
 	Action Actuators apply an action to an actor.
+	
+	@ivar action: The name of the action to set as the current action.
+	@type action: string
+	@ivar start: Specifies the starting frame of the animation.
+	@type start: float
+	@type end: Specifies the ending frame of the animation.
+	@type end: float
+	@ivar blendin: Specifies the number of frames of animation to generate when making transitions between actions.
+	@type blendin: float
+	@ivar priority: Sets the priority of this actuator. Actuators will lower
+		                 priority numbers will override actuators with higher
+		                 numbers.
+	@type priority: integer
+	@ivar frame: Sets the current frame for the animation.
+	@type frame: float
+	@ivar property: Sets the property to be used in FromProp playback mode.
+	@type property: string
+	@ivar blendTime: Sets the internal frame timer. This property must be in
+						the range from 0.0 to 1.0.
+	@type blendTime: float
+	@ivar type: The operation mode of the actuator.
+					KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER,
+					KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
+	@type type: integer
+	@ivar continue: The actions continue option, True or False.
+					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.
+	@type: boolean
+	@ivar frameProperty: The name of the property that is set to the current frame number.
+	@type frameProperty: string
 	"""
+	def setChannel(channel, matrix, mode = False):
+		"""
+		@param channel: A string specifying the name of the bone channel.
+		@type channel: string
+		@param matrix: A 4x4 matrix specifying the overriding transformation
+		               as an offset from the bone's rest position.
+		@type matrix: list [[float]]
+		@param mode: True for armature/world space, False for bone space
+		@type mode: boolean
+		"""
+
+	#--The following methods are deprecated--
 	def setAction(action, reset = True):
 		"""
 		Sets the current action.
@@ -154,16 +196,6 @@ class BL_ActionActuator(SCA_IActuator):
 		
 		@rtype: string
 		"""
-	def setChannel(channel, matrix, mode = False):
-		"""
-		@param channel: A string specifying the name of the bone channel.
-		@type channel: string
-		@param matrix: A 4x4 matrix specifying the overriding transformation
-		               as an offset from the bone's rest position.
-		@type matrix: list [[float]]
-		@param mode: True for armature/world space, False for bone space
-		@type mode: boolean
-		"""
 	def setFrameProperty(prop):
 		"""
 		@param prop: A string specifying the property of the object that will be updated with the action frame number.
-- 
cgit v1.2.3


From 8a95c67a50918a928f45fffd53e084428fcff9d8 Mon Sep 17 00:00:00 2001
From: Benoit Bolsee <benoit.bolsee@online.be>
Date: Thu, 22 Jan 2009 17:40:47 +0000
Subject: BGE API cleanup: shape action actuator.

---
 source/gameengine/PyDoc/BL_ActionActuator.py      | 23 ++++++++-
 source/gameengine/PyDoc/BL_ShapeActionActuator.py | 63 +++++++++++++++++------
 2 files changed, 69 insertions(+), 17 deletions(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/BL_ActionActuator.py b/source/gameengine/PyDoc/BL_ActionActuator.py
index 5d6ea51060b..3e95befe16b 100644
--- a/source/gameengine/PyDoc/BL_ActionActuator.py
+++ b/source/gameengine/PyDoc/BL_ActionActuator.py
@@ -23,7 +23,7 @@ class BL_ActionActuator(SCA_IActuator):
 	@ivar property: Sets the property to be used in FromProp playback mode.
 	@type property: string
 	@ivar blendTime: Sets the internal frame timer. This property must be in
-						the range from 0.0 to 1.0.
+						the range from 0.0 to blendin.
 	@type blendTime: float
 	@ivar type: The operation mode of the actuator.
 					KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER,
@@ -50,6 +50,7 @@ class BL_ActionActuator(SCA_IActuator):
 	#--The following methods are deprecated--
 	def setAction(action, reset = True):
 		"""
+		DEPRECATED: use the 'action' property
 		Sets the current action.
 		
 		@param action: The name of the action to set as the current action.
@@ -63,6 +64,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def setStart(start):
 		"""
+		DEPRECATED: use the 'start' property
 		Specifies the starting frame of the animation.
 		
 		@param start: the starting frame of the animation
@@ -71,6 +73,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def setEnd(end):
 		"""
+		DEPRECATED: use the 'end' property
 		Specifies the ending frame of the animation.
 		
 		@param end: the ending frame of the animation
@@ -78,6 +81,7 @@ class BL_ActionActuator(SCA_IActuator):
 		"""
 	def setBlendin(blendin):
 		"""
+		DEPRECATED: use the 'blendin' property
 		Specifies the number of frames of animation to generate
 		when making transitions between actions.
 		
@@ -87,6 +91,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def setPriority(priority):
 		"""
+		DEPRECATED: use the 'priority' property
 		Sets the priority of this actuator.
 		
 		@param priority: Specifies the new priority.  Actuators will lower
@@ -96,6 +101,7 @@ class BL_ActionActuator(SCA_IActuator):
 		"""
 	def setFrame(frame):
 		"""
+		DEPRECATED: use the 'frame' property
 		Sets the current frame for the animation.
 		
 		@param frame: Specifies the new current frame for the animation
@@ -104,6 +110,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def setProperty(prop):
 		"""
+		DEPRECATED: use the 'property' property
 		Sets the property to be used in FromProp playback mode.
 		
 		@param prop: the name of the property to use.
@@ -112,6 +119,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def setBlendtime(blendtime):
 		"""
+		DEPRECATED: use the 'blendTime' property
 		Sets the internal frame timer.
 		 
 		Allows the script to directly modify the internal timer
@@ -123,6 +131,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def setType(mode):
 		"""
+		DEPRECATED: use the 'type' property
 		Sets the operation mode of the actuator
 
 		@param mode: KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER, KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
@@ -131,6 +140,7 @@ class BL_ActionActuator(SCA_IActuator):
 	
 	def setContinue(cont):
 		"""
+		DEPRECATED: use the 'continue' property
 		Set the actions continue option True or False. see getContinue.
 
 		@param cont: The continue option.
@@ -139,6 +149,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def getType():
 		"""
+		DEPRECATED: use the 'type' property
 		Returns the operation mode of the actuator
 	    
 		@rtype: integer
@@ -147,6 +158,7 @@ class BL_ActionActuator(SCA_IActuator):
 
 	def getContinue():
 		"""
+		DEPRECATED: use the 'continue' property
 		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
@@ -154,6 +166,7 @@ class BL_ActionActuator(SCA_IActuator):
 	
 	def getAction():
 		"""
+		DEPRECATED: use the 'action' property
 		getAction() returns the name of the action associated with this actuator.
 		
 		@rtype: string
@@ -161,24 +174,28 @@ class BL_ActionActuator(SCA_IActuator):
 	
 	def getStart():
 		"""
+		DEPRECATED: use the 'start' property
 		Returns the starting frame of the action.
 		
 		@rtype: float
 		"""
 	def getEnd():
 		"""
+		DEPRECATED: use the 'end' property
 		Returns the last frame of the action.
 		
 		@rtype: float
 		"""
 	def getBlendin():
 		"""
+		DEPRECATED: use the 'blendin' property
 		Returns the number of interpolation animation frames to be generated when this actuator is triggered.
 		
 		@rtype: float
 		"""
 	def getPriority():
 		"""
+		DEPRECATED: use the 'priority' property
 		Returns the priority for this actuator.  Actuators with lower Priority numbers will
 		override actuators with higher numbers.
 		
@@ -186,23 +203,27 @@ class BL_ActionActuator(SCA_IActuator):
 		"""
 	def getFrame():
 		"""
+		DEPRECATED: use the 'frame' property
 		Returns the current frame number.
 		
 		@rtype: float
 		"""
 	def getProperty():
 		"""
+		DEPRECATED: use the 'property' property
 		Returns the name of the property to be used in FromProp mode.
 		
 		@rtype: string
 		"""
 	def setFrameProperty(prop):
 		"""
+		DEPRECATED: use the 'frameProperty' property
 		@param prop: A string specifying the property of the object that will be updated with the action frame number.
 		@type prop: string
 		"""
 	def getFrameProperty():
 		"""
+		DEPRECATED: use the 'frameProperty' property
 		Returns the name of the property that is set to the current frame number.
 		
 		@rtype: string
diff --git a/source/gameengine/PyDoc/BL_ShapeActionActuator.py b/source/gameengine/PyDoc/BL_ShapeActionActuator.py
index a26b276a2da..209ff4e5580 100644
--- a/source/gameengine/PyDoc/BL_ShapeActionActuator.py
+++ b/source/gameengine/PyDoc/BL_ShapeActionActuator.py
@@ -4,10 +4,38 @@ from SCA_IActuator import *
 
 class BL_ShapeActionActuator(SCA_IActuator):
 	"""
-	ShapeAction Actuators apply an shape action to an mesh object.
+	ShapeAction Actuators apply an shape action to an mesh object.\
+
+	@ivar action: The name of the action to set as the current shape action.
+	@type action: string
+	@ivar start: Specifies the starting frame of the shape animation.
+	@type start: float
+	@type end: Specifies the ending frame of the shape animation.
+	@type end: float
+	@ivar blendin: Specifies the number of frames of animation to generate when making transitions between actions.
+	@type blendin: float
+	@ivar priority: Sets the priority of this actuator. Actuators will lower
+		                 priority numbers will override actuators with higher
+		                 numbers.
+	@type priority: integer
+	@ivar frame: Sets the current frame for the animation.
+	@type frame: float
+	@ivar property: Sets the property to be used in FromProp playback mode.
+	@type property: string
+	@ivar blendTime: Sets the internal frame timer. This property must be in
+						the range from 0.0 to blendin.
+	@type blendTime: float
+	@ivar type: The operation mode of the actuator.
+					KX_ACTIONACT_PLAY, KX_ACTIONACT_PROPERTY, KX_ACTIONACT_FLIPPER,
+					KX_ACTIONACT_LOOPSTOP, KX_ACTIONACT_LOOPEND
+	@type type: integer
+	@ivar frameProperty: The name of the property that is set to the current frame number.
+	@type frameProperty: string
+	
 	"""
 	def setAction(action, reset = True):
 		"""
+		DEPRECATED: use the 'action' property
 		Sets the current action.
 		
 		@param action: The name of the action to set as the current action.
@@ -21,6 +49,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 
 	def setStart(start):
 		"""
+		DEPRECATED: use the 'start' property
 		Specifies the starting frame of the animation.
 		
 		@param start: the starting frame of the animation
@@ -29,6 +58,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 
 	def setEnd(end):
 		"""
+		DEPRECATED: use the 'end' property
 		Specifies the ending frame of the animation.
 		
 		@param end: the ending frame of the animation
@@ -36,6 +66,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 		"""
 	def setBlendin(blendin):
 		"""
+		DEPRECATED: use the 'blendin' property
 		Specifies the number of frames of animation to generate
 		when making transitions between actions.
 		
@@ -45,6 +76,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 
 	def setPriority(priority):
 		"""
+		DEPRECATED: use the 'priority' property
 		Sets the priority of this actuator.
 		
 		@param priority: Specifies the new priority.  Actuators will lower
@@ -54,6 +86,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 		"""
 	def setFrame(frame):
 		"""
+		DEPRECATED: use the 'frame' property
 		Sets the current frame for the animation.
 		
 		@param frame: Specifies the new current frame for the animation
@@ -62,6 +95,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 
 	def setProperty(prop):
 		"""
+		DEPRECATED: use the 'property' property
 		Sets the property to be used in FromProp playback mode.
 		
 		@param prop: the name of the property to use.
@@ -70,6 +104,7 @@ class BL_ShapeActionActuator(SCA_IActuator):
 
 	def setBlendtime(blendtime):
 		"""
+		DEPRECATED: use the 'blendTime' property
 		Sets the internal frame timer.
 		 
 		Allows the script to directly modify the internal timer
@@ -81,37 +116,25 @@ class BL_ShapeActionActuator(SCA_IActuator):
 
 	def setType(mode):
 		"""
+		DEPRECATED: use the 'type' property
 		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():
 		"""
+		DEPRECATED: use the 'type' property
 		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():
 		"""
+		DEPRECATED: use the 'action' property
 		getAction() returns the name of the action associated with this actuator.
 		
 		@rtype: string
@@ -119,24 +142,28 @@ class BL_ShapeActionActuator(SCA_IActuator):
 	
 	def getStart():
 		"""
+		DEPRECATED: use the 'start' property
 		Returns the starting frame of the action.
 		
 		@rtype: float
 		"""
 	def getEnd():
 		"""
+		DEPRECATED: use the 'end' property
 		Returns the last frame of the action.
 		
 		@rtype: float
 		"""
 	def getBlendin():
 		"""
+		DEPRECATED: use the 'blendin' property
 		Returns the number of interpolation animation frames to be generated when this actuator is triggered.
 		
 		@rtype: float
 		"""
 	def getPriority():
 		"""
+		DEPRECATED: use the 'priority' property
 		Returns the priority for this actuator.  Actuators with lower Priority numbers will
 		override actuators with higher numbers.
 		
@@ -144,23 +171,27 @@ class BL_ShapeActionActuator(SCA_IActuator):
 		"""
 	def getFrame():
 		"""
+		DEPRECATED: use the 'frame' property
 		Returns the current frame number.
 		
 		@rtype: float
 		"""
 	def getProperty():
 		"""
+		DEPRECATED: use the 'property' property
 		Returns the name of the property to be used in FromProp mode.
 		
 		@rtype: string
 		"""
 	def setFrameProperty(prop):
 		"""
+		DEPRECATED: use the 'frameProperty' property
 		@param prop: A string specifying the property of the object that will be updated with the action frame number.
 		@type prop: string
 		"""
 	def getFrameProperty():
 		"""
+		DEPRECATED: use the 'frameProperty' property
 		Returns the name of the property that is set to the current frame number.
 		
 		@rtype: string
-- 
cgit v1.2.3


From 59e96a2831ef52bff36f900bb4bb31fffe072f7d Mon Sep 17 00:00:00 2001
From: Benoit Bolsee <benoit.bolsee@online.be>
Date: Sat, 7 Feb 2009 20:35:16 +0000
Subject: BGE Py API cleanup: Camera Actuator.

---
 source/gameengine/PyDoc/KX_CameraActuator.py | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/KX_CameraActuator.py b/source/gameengine/PyDoc/KX_CameraActuator.py
index 9a9abaf3d57..c4d5c9bcbfc 100644
--- a/source/gameengine/PyDoc/KX_CameraActuator.py
+++ b/source/gameengine/PyDoc/KX_CameraActuator.py
@@ -6,6 +6,15 @@ class KX_CameraActuator(SCA_IActuator):
 	"""
 	Applies changes to a camera.
 	
+	@ivar min: minimum distance to the target object maintained by the actuator
+	@type min: float
+	@ivar max: maximum distance to stay from the target object
+	@type max: float
+	@ivar height: height to stay above the target object
+	@type height: float
+	@ivar xy: axis this actuator is tracking, true=X, false=Y
+	@type xy: boolean
+	
 	@author: snail
 	"""
 	def getObject(name_only = 1):
-- 
cgit v1.2.3


From c597863783e1001dca599e6dcbc28048f0ef4ce1 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Thu, 19 Feb 2009 10:34:51 +0000
Subject: "object" and "objectLastCreated" attribute for actuators, deprecates
 getObject/setObject() & getLastCreatedObject() also removed some warnings

---
 source/gameengine/PyDoc/KX_CameraActuator.py        | 3 ++-
 source/gameengine/PyDoc/KX_ParentActuator.py        | 3 +++
 source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py | 4 ++++
 source/gameengine/PyDoc/KX_TrackToActuator.py       | 2 ++
 4 files changed, 11 insertions(+), 1 deletion(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/KX_CameraActuator.py b/source/gameengine/PyDoc/KX_CameraActuator.py
index c4d5c9bcbfc..6ffc55a5854 100644
--- a/source/gameengine/PyDoc/KX_CameraActuator.py
+++ b/source/gameengine/PyDoc/KX_CameraActuator.py
@@ -14,7 +14,8 @@ class KX_CameraActuator(SCA_IActuator):
 	@type height: float
 	@ivar xy: axis this actuator is tracking, true=X, false=Y
 	@type xy: boolean
-	
+	@ivar object: the object this actuator tracks.
+	@type object: KX_GameObject or None
 	@author: snail
 	"""
 	def getObject(name_only = 1):
diff --git a/source/gameengine/PyDoc/KX_ParentActuator.py b/source/gameengine/PyDoc/KX_ParentActuator.py
index 6d6e0937257..7b5625ec82d 100644
--- a/source/gameengine/PyDoc/KX_ParentActuator.py
+++ b/source/gameengine/PyDoc/KX_ParentActuator.py
@@ -5,6 +5,9 @@ from SCA_IActuator import *
 class KX_ParentActuator(SCA_IActuator):
 	"""
 	The parent actuator can set or remove an objects parent object.
+	
+	@ivar object: the object this actuator sets the parent too.
+	@type object: KX_GameObject or None
 	"""
 	def setObject(object):
 		"""
diff --git a/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py b/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py
index c3b2e947ddb..56068fa641a 100644
--- a/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py
+++ b/source/gameengine/PyDoc/KX_SCA_AddObjectActuator.py
@@ -5,6 +5,10 @@ from SCA_IActuator import *
 class KX_SCA_AddObjectActuator(SCA_IActuator):
 	"""
 	Edit Object Actuator (in Add Object Mode)
+	@ivar object: the object this actuator adds.
+	@type object: KX_GameObject or None
+	@ivar objectLastCreated: the last added object from this actuator (read only).
+	@type objectLastCreated: KX_GameObject or None
 	
 	@warning: An Add Object actuator will be ignored if at game start, the linked object doesn't exist
 		  (or is empty) or the linked object is in an active layer.
diff --git a/source/gameengine/PyDoc/KX_TrackToActuator.py b/source/gameengine/PyDoc/KX_TrackToActuator.py
index 948302991b7..730ab21166b 100644
--- a/source/gameengine/PyDoc/KX_TrackToActuator.py
+++ b/source/gameengine/PyDoc/KX_TrackToActuator.py
@@ -13,6 +13,8 @@ class KX_TrackToActuator(SCA_IActuator):
 		
 		C{ERROR: GameObject I{OBName} no object in EditObjectActuator I{ActuatorName}}
 
+	@ivar object: the object this actuator tracks.
+	@type object: KX_GameObject or None
 	"""
 	def setObject(object):
 		"""
-- 
cgit v1.2.3


From 6c7c38a4e4892677f8e7db2b41115209901a2d35 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Tue, 24 Feb 2009 05:50:45 +0000
Subject: BGE Py API * Made GameLogic.addActiveActuator(actu, bool) to raise an
 error if the actuator is not in the list. Before it would allow any value as
 the actuator and fail silently (makes debugging scripts more difficult).

* Allow the actuator to be a string which is convenient if you dont want to change the settings of the actuator.
* Added activate/deactivate functions to the controller, this is more logical since the GameLogic.addActiveActuator() function is running through the controller anyway.

GameLogic.addActiveActuator(controller.getActuator("SomeAct"), True)
...can be replaced with...
controller.activate("SomeAct")
---
 source/gameengine/PyDoc/GameLogic.py            |  2 +-
 source/gameengine/PyDoc/KX_Scene.py             |  2 ++
 source/gameengine/PyDoc/SCA_PythonController.py | 12 +++++++++++-
 3 files changed, 14 insertions(+), 2 deletions(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/GameLogic.py b/source/gameengine/PyDoc/GameLogic.py
index 9dab7db6081..f743acf06fe 100644
--- a/source/gameengine/PyDoc/GameLogic.py
+++ b/source/gameengine/PyDoc/GameLogic.py
@@ -159,7 +159,7 @@ def addActiveActuator(actuator, activate):
 	"""
 	Activates the given actuator.
 	
-	@type actuator: L{SCA_IActuator}
+	@type actuator: L{SCA_IActuator} or the actuator name as a string.
 	@type activate: boolean
 	@param activate: whether to activate or deactivate the given actuator.
 	"""
diff --git a/source/gameengine/PyDoc/KX_Scene.py b/source/gameengine/PyDoc/KX_Scene.py
index 4a0a7a9556d..24b81bbf55e 100644
--- a/source/gameengine/PyDoc/KX_Scene.py
+++ b/source/gameengine/PyDoc/KX_Scene.py
@@ -39,6 +39,8 @@ class KX_Scene:
 		
 	@ivar name: The scene's name
 	@type name: string
+	@type objects: A list of objects in the scene.
+	@type objects: list [L{KX_GameObject}]
 	@ivar active_camera: The current active camera
 	@type active_camera: L{KX_Camera}
 	@ivar suspended: True if the scene is suspended.
diff --git a/source/gameengine/PyDoc/SCA_PythonController.py b/source/gameengine/PyDoc/SCA_PythonController.py
index 06f2b7e9d1d..9684b41d481 100644
--- a/source/gameengine/PyDoc/SCA_PythonController.py
+++ b/source/gameengine/PyDoc/SCA_PythonController.py
@@ -15,7 +15,17 @@ class SCA_PythonController(SCA_IController):
 	             This can be used with the GameObject's state to test if the controller is active.
 	@type state: integer
 	"""
-
+	def activate(actuator):
+		"""
+		Activates an actuator attached to this controller.
+		@type actuator: actuator or the actuator name as a string
+		"""
+	def deactivate(actuator):
+		"""
+		Deactivates an actuator attached to this controller.
+		@type actuator: actuator or the actuator name as a string
+		"""
+		
 	def getSensors():
 		"""
 		Gets a list of all sensors attached to this controller.
-- 
cgit v1.2.3


From adaa4b0fd0c7dde64b9610b68188052d4d8a628c Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Tue, 24 Feb 2009 12:38:56 +0000
Subject: Making KX_GameObject names read only. This was committed in revision
 2832 but never accounted for existing object name hashes which existed since
 revision 2.

Its possible to update the names elsewhere but unlikely anyone ever used this successfully so removing.
---
 source/gameengine/PyDoc/KX_GameObject.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/KX_GameObject.py b/source/gameengine/PyDoc/KX_GameObject.py
index efeffab2eed..4f389a1ae4f 100644
--- a/source/gameengine/PyDoc/KX_GameObject.py
+++ b/source/gameengine/PyDoc/KX_GameObject.py
@@ -7,7 +7,7 @@ class KX_GameObject:
 	
 	Properties assigned to game objects are accessible as attributes of this class.
 	
-	@ivar name: The object's name.
+	@ivar name: The object's name. (Read only)
 	@type name: string.
 	@ivar mass: The object's mass (provided the object has a physics controller). Read only.
 	@type mass: float
-- 
cgit v1.2.3


From 6bfb8ca6b09e983fe757c9590b462b113ad28b72 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Thu, 26 Feb 2009 04:17:23 +0000
Subject: - Attributes for the collision sensor: propertyName, materialCheck,
 pulseCollisions, objectHit and objectHitList. Removed a check in Python API
 touch.setProperty() for the property name on the sensor owner before allowing
 the name to be set - it makes no sense and isnt checked when creating the
 sensor. - SCA_DelaySensor.py indent error making epydoc fail.

---
 source/gameengine/PyDoc/KX_TouchSensor.py  | 32 ++++++++++++++++++++----------
 source/gameengine/PyDoc/SCA_DelaySensor.py |  7 +++----
 2 files changed, 24 insertions(+), 15 deletions(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/KX_TouchSensor.py b/source/gameengine/PyDoc/KX_TouchSensor.py
index f2cc101af10..4f020930c4c 100644
--- a/source/gameengine/PyDoc/KX_TouchSensor.py
+++ b/source/gameengine/PyDoc/KX_TouchSensor.py
@@ -1,13 +1,26 @@
 # $Id$
 # Documentation for KX_TouchSensor
 from SCA_ISensor import *
+from KX_GameObject import *
 
 class KX_TouchSensor(SCA_ISensor):
 	"""
 	Touch sensor detects collisions between objects.
+	
+	@ivar propertyName: The name of the property or material this sensor detects (depending on the materialCheck property).
+	@type propertyName: string
+	@ivar materialCheck: when enabled this sensor checks for object materials rather then properties.
+	@type materialCheck: bool
+	@ivar pulseCollisions: The last collided object.
+	@type pulseCollisions: bool
+	@ivar objectHit: The last collided object. (Read Only)
+	@type objectHit: L{KX_GameObject} or None
+	@ivar objectHitList: A list of colliding objects. (Read Only)
+	@type objectHitList: list
 	"""
 	def setProperty(name):
 		"""
+		DEPRECATED: use the propertyName property
 		Set the property or material to collide with. Use
 		setTouchMaterial() to switch between properties and
 		materials.
@@ -15,22 +28,25 @@ class KX_TouchSensor(SCA_ISensor):
 		"""
 	def getProperty():
 		"""
+		DEPRECATED: use the propertyName property
 		Returns the property or material to collide with. Use
 		getTouchMaterial() to find out whether this sensor
-		looks for properties or materials.
+		looks for properties or materials. (B{deprecated})
 		
 		@rtype: string
 		"""
 
 	def getHitObject():
 		"""
-		Returns the last object hit by this touch sensor.
+		DEPRECATED: use the objectHit property
+		Returns the last object hit by this touch sensor. (B{deprecated})
 		
 		@rtype: L{KX_GameObject}
 		"""
 	def getHitObjectList():
 		"""
-		Returns a list of all objects hit in the last frame.
+		DEPRECATED: use the objectHitList property
+		Returns a list of all objects hit in the last frame. (B{deprecated})
 		
 		Only objects that have the requisite material/property are listed.
 		
@@ -38,13 +54,7 @@ class KX_TouchSensor(SCA_ISensor):
 		"""
 	def getTouchMaterial():
 		"""
+		DEPRECATED: use the materialCheck property
 		Returns KX_TRUE if this sensor looks for a specific material,
-		KX_FALSE if it looks for a specific property.
-		"""
-	def setTouchMaterial(flag):
-		"""
-		Set flag to KX_TRUE to switch on positive pulse mode,
-		KX_FALSE to switch off positive pulse mode.
-		
-		@type flag: KX_TRUE or KX_FALSE.
+		KX_FALSE if it looks for a specific property. (B{deprecated})
 		"""
diff --git a/source/gameengine/PyDoc/SCA_DelaySensor.py b/source/gameengine/PyDoc/SCA_DelaySensor.py
index b99ed08bed5..6560df6573e 100644
--- a/source/gameengine/PyDoc/SCA_DelaySensor.py
+++ b/source/gameengine/PyDoc/SCA_DelaySensor.py
@@ -20,10 +20,9 @@ class SCA_DelaySensor(SCA_ISensor):
 	@type delay: integer.
 	@ivar duration: length of the ON period in number of frame after the initial OFF period.
 	                If duration is greater than 0, a negative trigger is sent at the end of the ON pulse.
-    @type duration: integer
-    @ivar repeat: 1 if the OFF-ON cycle should be repeated indefinately, 0 if it should run once.
-    @type repeat: integer
-    
+	@type duration: integer
+	@ivar repeat: 1 if the OFF-ON cycle should be repeated indefinately, 0 if it should run once.
+	@type repeat: integer
 	"""
 	def setDelay(delay):
 		"""
-- 
cgit v1.2.3


From 6c409ed541d84b662d16ee34e9128cc64d27d0d8 Mon Sep 17 00:00:00 2001
From: Benoit Bolsee <benoit.bolsee@online.be>
Date: Sat, 28 Feb 2009 21:00:27 +0000
Subject: BGE API cleanup: apply patch from Moguri: Near, Radar, Touch sensor
 updated.

---
 source/gameengine/PyDoc/GameLogic.py      |  8 ++++++++
 source/gameengine/PyDoc/KX_NearSensor.py  |  5 +++++
 source/gameengine/PyDoc/KX_RadarSensor.py | 18 ++++++++++++++++++
 source/gameengine/PyDoc/KX_Scene.py       | 13 +++++++++++++
 source/gameengine/PyDoc/KX_TouchSensor.py | 19 +++++++++++--------
 5 files changed, 55 insertions(+), 8 deletions(-)

(limited to 'source/gameengine/PyDoc')

diff --git a/source/gameengine/PyDoc/GameLogic.py b/source/gameengine/PyDoc/GameLogic.py
index f743acf06fe..0524a9df355 100644
--- a/source/gameengine/PyDoc/GameLogic.py
+++ b/source/gameengine/PyDoc/GameLogic.py
@@ -140,6 +140,14 @@ Documentation for the GameLogic Module.
 @var KX_SOUNDACT_LOOPEND:		    See L{KX_SoundActuator}
 @var KX_SOUNDACT_LOOPBIDIRECTIONAL:	    See L{KX_SoundActuator}
 @var KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP:    See L{KX_SoundActuator}
+
+@group Radar Sensor: KX_RADAR_AXIS_POS_X, KX_RADAR_AXIS_POS_Y, KX_RADAR_AXIS_POS_Z, KX_RADAR_AXIS_NEG_X, KX_RADAR_AXIS_NEG_Y, KX_RADAR_AXIS_NEG_Z
+@var KX_RADAR_AXIS_POS_X:		    See L{KX_RadarSensor}
+@var KX_RADAR_AXIS_POS_Y:		    See L{KX_RadarSensor}
+@var KX_RADAR_AXIS_POS_Z:		    See L{KX_RadarSensor}
+@var KX_RADAR_AXIS_NEG_X:		    See L{KX_RadarSensor}
+@var KX_RADAR_AXIS_NEG_Y:		    See L{KX_RadarSensor}
+@var KX_RADAR_AXIS_NEG_Z:		    See L{KX_RadarSensor}
 """
 
 
diff --git a/source/gameengine/PyDoc/KX_NearSensor.py b/source/gameengine/PyDoc/KX_NearSensor.py
index fef2e4b2acc..a8c408827fe 100644
--- a/source/gameengine/PyDoc/KX_NearSensor.py
+++ b/source/gameengine/PyDoc/KX_NearSensor.py
@@ -5,5 +5,10 @@ from KX_TouchSensor import *
 class KX_NearSensor(KX_TouchSensor):
 	"""
 	A near sensor is a specialised form of touch sensor.
+	
+	@ivar distance: The near sensor activates when an object is within this distance.
+	@type distance: float
+	@ivar resetDistance: The near sensor deactivates when the object exceeds this distance.
+	@type resetDistance: float
 	"""
 
diff --git a/source/gameengine/PyDoc/KX_RadarSensor.py b/source/gameengine/PyDoc/KX_RadarSensor.py
index 64be858371a..b68bf4ea0f3 100644
--- a/source/gameengine/PyDoc/KX_RadarSensor.py
+++ b/source/gameengine/PyDoc/KX_RadarSensor.py
@@ -5,8 +5,26 @@ from KX_NearSensor import *
 class KX_RadarSensor(KX_NearSensor):
 	"""
 	Radar sensor is a near sensor with a conical sensor object.
+	
+	@ivar coneOrigin: The origin of the cone with which to test. The origin
+						is in the middle of the cone.
+						(Read only)
+	@type coneOrigin: list of floats [x, y, z]
+	@ivar coneTarget: The center of the bottom face of the cone with which to test.
+						(Read only)
+	@type coneTarget: list of floats [x, y, z]
+	@ivar distance: The height of the cone with which to test.
+	@type distance: float
+	@ivar angle: The angle of the cone (in degrees) with which to test.
+	@type angle: float from 0 to 360
+	@ivar axis: The axis on which the radar cone is cast
+	@type axis: int from 0 to 5
+		KX_RADAR_AXIS_POS_X, KX_RADAR_AXIS_POS_Y, KX_RADAR_AXIS_POS_Z,
+		KX_RADAR_AXIS_NEG_X, KX_RADAR_AXIS_NEG_Y, KX_RADAR_AXIS_NEG_Z
 	"""
 	
+	
+	#--The following methods are deprecated, please use properties instead.
 	def getConeOrigin():
 		"""
 		Returns the origin of the cone with which to test. The origin
diff --git a/source/gameengine/PyDoc/KX_Scene.py b/source/gameengine/PyDoc/KX_Scene.py
index 24b81bbf55e..5e357e6eefc 100644
--- a/source/gameengine/PyDoc/KX_Scene.py
+++ b/source/gameengine/PyDoc/KX_Scene.py
@@ -70,3 +70,16 @@ class KX_Scene:
 		@rtype: string
 		"""
 
+	def addObject(object, other, time=0)
+		"""
+		Adds an object to the scene like the Add Object Actuator would, and returns the created object.
+		
+		@param object: The object to add
+		@type object: L{KX_GameObject} or string
+		@param other: The object's center to use when adding the object
+		@type other: L{KX_GameObject} or string
+		@param time: The lifetime of the added object, in frames. A time of 0 means the object will last forever.
+		@type time: int
+		
+		@rtype: L{KX_GameObject}
+		"""
diff --git a/source/gameengine/PyDoc/KX_TouchSensor.py b/source/gameengine/PyDoc/KX_TouchSensor.py
index 4f020930c4c..d7277be4c2a 100644
--- a/source/gameengine/PyDoc/KX_TouchSensor.py
+++ b/source/gameengine/PyDoc/KX_TouchSensor.py
@@ -7,10 +7,11 @@ class KX_TouchSensor(SCA_ISensor):
 	"""
 	Touch sensor detects collisions between objects.
 	
-	@ivar propertyName: The name of the property or material this sensor detects (depending on the materialCheck property).
-	@type propertyName: string
-	@ivar materialCheck: when enabled this sensor checks for object materials rather then properties.
-	@type materialCheck: bool
+	@ivar property: The property or material to collide with.
+	@type property: string
+	@ivar useMaterial: Determines if the sensor is looking for a property or material.
+						KX_True = Find material; KX_False = Find property
+	@type useMaterial: boolean
 	@ivar pulseCollisions: The last collided object.
 	@type pulseCollisions: bool
 	@ivar objectHit: The last collided object. (Read Only)
@@ -18,24 +19,26 @@ class KX_TouchSensor(SCA_ISensor):
 	@ivar objectHitList: A list of colliding objects. (Read Only)
 	@type objectHitList: list
 	"""
+		
+	#--The following methods are deprecated, please use properties instead.
 	def setProperty(name):
 		"""
-		DEPRECATED: use the propertyName property
+		DEPRECATED: use the property property
 		Set the property or material to collide with. Use
 		setTouchMaterial() to switch between properties and
 		materials.
 		@type name: string
 		"""
+		
 	def getProperty():
 		"""
-		DEPRECATED: use the propertyName property
+		DEPRECATED: use the property property
 		Returns the property or material to collide with. Use
 		getTouchMaterial() to find out whether this sensor
 		looks for properties or materials. (B{deprecated})
 		
 		@rtype: string
 		"""
-
 	def getHitObject():
 		"""
 		DEPRECATED: use the objectHit property
@@ -54,7 +57,7 @@ class KX_TouchSensor(SCA_ISensor):
 		"""
 	def getTouchMaterial():
 		"""
-		DEPRECATED: use the materialCheck property
+		DEPRECATED: use the useMaterial property
 		Returns KX_TRUE if this sensor looks for a specific material,
 		KX_FALSE if it looks for a specific property. (B{deprecated})
 		"""
-- 
cgit v1.2.3