BGE: New Mouse Actuator

Disclaimer: The author of this patch is Geoffrey Gollmer (gomer). I only updated the patch to the current git master status, reworked several parts to fit well with current coding style and applied several fixes.

This actuator allows users to show/hide the mouse cursor using logic bricks, as well as control object rotation with a mouse in the BGE.
The mouse rotation is flexible enough to allow any type of mouse look, as well as banking for flight controls.

{F94520}

{F91859}

Blend file for testing Mouse actuator (with default parameters and crosshair): {F94920}

Reviewers: moguri

Reviewed By: moguri

CC: gomer, lordodin

Differential Revision: https://developer.blender.org/D559

2 files changed, 114 insertions, 0 deletions

diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index b37806437a9..4e0d317e4bf 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -72,6 +72,7 @@ See the actuator's reference for available methods
    * :class:`~bge.types.KX_CameraActuator`
    * :class:`~bge.types.KX_ConstraintActuator`
    * :class:`~bge.types.KX_GameActuator`
+   * :class:`~bge.types.KX_MouseActuator`
    * :class:`~bge.types.KX_NetworkMessageActuator`
    * :class:`~bge.types.KX_ObjectActuator`
    * :class:`~bge.types.KX_ParentActuator`
@@ -764,6 +765,16 @@ See :class:`bge.types.KX_GameActuator`
 .. data:: KX_GAME_SAVECFG
 .. data:: KX_GAME_LOADCFG
 
+.. _mouse-actuator:
+
+---------------
+Mouse Actuator
+---------------
+
+.. data:: KX_ACT_MOUSE_OBJECT_AXIS_X
+.. data:: KX_ACT_MOUSE_OBJECT_AXIS_Y
+.. data:: KX_ACT_MOUSE_OBJECT_AXIS_Z
+
 ---------------
 Parent Actuator
 ---------------
diff --git a/doc/python_api/rst/bge_types/bge.types.KX_MouseActuator.rst b/doc/python_api/rst/bge_types/bge.types.KX_MouseActuator.rst
new file mode 100644
index 00000000000..cc3ce49d0a5
--- /dev/null
+++ b/doc/python_api/rst/bge_types/bge.types.KX_MouseActuator.rst
@@ -0,0 +1,103 @@
+KX_MouseActuator(SCA_IActuator)
+====================================
+
+.. module:: bge.types
+
+base class --- :class:`SCA_IActuator`
+
+.. class:: KX_MouseActuator(SCA_IActuator)
+
+   The mouse actuator gives control over the visibility of the mouse cursor and rotates the parent object according to mouse movement.
+
+   .. method:: reset()
+
+      Undoes the rotation caused by the mouse actuator.
+
+   .. attribute:: visible
+
+      The visibility of the mouse cursor.
+
+      :type: boolean
+
+   .. attribute:: use_axis_x
+
+      Mouse movement along the x axis effects object rotation.
+
+      :type: boolean
+
+   .. attribute:: use_axis_y
+
+      Mouse movement along the y axis effects object rotation.
+
+      :type: boolean
+
+   .. attribute:: threshold
+
+      Amount of movement from the mouse required before rotation is triggered.
+
+      :type: list (vector of 2 floats)
+
+      The values in the list should be between 0.0 and 0.5.
+
+   .. attribute:: reset_x
+
+      Mouse is locked to the center of the screen on the x axis.
+
+      :type: boolean
+
+   .. attribute:: reset_y
+
+      Mouse is locked to the center of the screen on the y axis.
+
+      :type: boolean
+
+   .. attribute:: object_axis
+
+      The object's 3D axis to rotate with the mouse movement. ([x, y])
+
+      :type: list (vector of 2 integers from 0 to 2)
+
+      * KX_ACT_MOUSE_OBJECT_AXIS_X
+      * KX_ACT_MOUSE_OBJECT_AXIS_Y
+      * KX_ACT_MOUSE_OBJECT_AXIS_Z
+
+   .. attribute:: local_x
+
+      Rotation caused by mouse movement along the x axis is local.
+
+      :type: boolean
+
+   .. attribute:: local_y
+
+      Rotation caused by mouse movement along the y axis is local.
+
+      :type: boolean
+
+   .. attribute:: sensitivity
+
+      The amount of rotation caused by mouse movement along the x and y axis.
+
+      :type: list (vector of 2 floats)
+
+      Negative values invert the rotation.
+
+   .. attribute:: limit_x
+
+      The minimum and maximum angle of rotation caused by mouse movement along the x axis in degrees.
+      limit_x[0] is minimum, limit_x[1] is maximum.
+
+      :type: list (vector of 2 floats)
+
+   .. attribute:: limit_y
+
+      The minimum and maximum angle of rotation caused by mouse movement along the y axis in degrees.
+      limit_y[0] is minimum, limit_y[1] is maximum.
+
+      :type: list (vector of 2 floats)
+
+   .. attribute:: angle
+
+      The current rotational offset caused by the mouse actuator in degrees.
+
+      :type: list (vector of 2 floats)
+