Table of Contents

• Setup Instructions
• Importing the Script (Advanced)
• Movement Systems
  • Static Movement
  • Dynamic Movement
• Property Hooks
  • Core
  • Mouselook
  • Static Movement
  • Dynamic Movement
• Class Methods
• Config Properties
• Changelog

Setup Instructions [top]

1. Open or Paste the script in Blender's Text Editor and give it a good name
• Example: "mousemove.py"
• It is recommended to add ".py" to the end
• You may want to use the Format > Convert Whitespaces > To Spaces feature in the Text Editor. This will prevent any indentation related errors.
2. Select the Object you want to add the script to. This will be called the "Script Object" for the purpose of these instructions.
3. In the Logic Editor, add an Always sensor and enable True level triggering [```]
• True level triggering on an Always sensor will update the script on every Logic tick.
4. Add a Python controller, and connect it with the Always sensor.
5. Follow the Script Execution Mode or Module Execution Mode steps below.

Note: As of update 2.61, you can use any sensor to trigger the Python controller.

Script Execution Mode

Your Python controller should be set to Script mode by default. Click inside the Text box next to the Script button on the controller and select the MouseMove script from the list.

Module Execution Mode

Recommended only for those who have experience with this method.

Module Execution mode requires your script to have ".py" at the end of its name. If your script name is "mousemove", add ".py" at the end ( = "mousemove.py").

1. Change the drop-down button on the Python controller from Script to Module.
2. Enter the script name into the Python controller. Instead of typing ".py" at the end, type ".main"
   • If your script name is "mousemove.py", you would enter "mousemove.main":
     

Final Note: For both Script and Module execution modes, the Mouselook feature is enabled by default. To disable it, add a Boolean property called "mmc.mouselook" and set it to False.

See the Property Hooks section for information on how to enable and modify features of the script.

Importing the Script (Advanced) [top]

For this part, I'll assume that you, the reader, are fairly familiar with using Python.

1. Import the MouseMove script
2. Create an instance of the "Core" class from the script:
   • mousemove.Core(object)
   • The object parameter requires either a KX_GameObject or a SCA_PythonController object.
     • Note: If object is a KX_GameObject, the Dynamic Movement system will not recognize any Collision or Ray sensors attached to the object for proper collision detection. Pass the SCA_PythonController object that has the sensors attached to it if you want proper collision detection.
3. Call the "main" method on your instance of the Core class to keep the script running

Example:

See the Callable Methods section for information about the methods of the Core class.

Movement Systems [top]

There are two movement systems in this script. These systems are designed to be easy to set up and allow the player to move through a scene. Each system contains its own Property Hooks, which are used to modify certain functions of the script.

Static Movement [top]

The Static Movement system is made for a non-parented Static object. This system will not work if the object is parented to another object, or if the object is not a Static physics type.

This movement system was designed for the Camera object to fly through a scene, but it will work with any static object. The default setting of the "cameramode" property puts foward movement along the -Z axis for optimal Camera movement, but disabling this property will set the forward axis to +Y.

Setup:

1. Follow the basic Setup instructions if you haven't already
2. To enable this feature, add the following property to the script object:
   • "mmc.static"; Boolean type; Set to True
3. For forward movement on the +Y axis, add:
• "sm.cameramode"; Boolean type; Set to False

Dynamic Movement [top]

The Dynamic Movement system enables the user to interact with the physical world of the game engine using a dynamic physics-type object as a "body".

Foward movement is along the +Y axis, so make sure your "body" object's original forward orientation is along the +Y axis. You can set the object's current rotation values as its origin rotation with Ctrl + A > Rotation in the 3D viewport. Also ensure that your object is not scaled to negative values. This will invert movement in certain directions.

Setup:

1. Follow the basic Setup instructions if you haven't already
2. Make sure your object is set to Dynamic or Rigid Body in the Physics settings
3. To enable this feature, add the following property:
   • "mmc.dynamic"; Boolean type; Set to True

Collision Detection:

Collision Detection is optional, but will offer you realistic interaction with the world, such as not being able to jump while mid-air.

1. Add a Collision sensor and a Ray sensor to your "body" object
2. Connect the Collision and Ray sensors to the Python controller that uses this script
   • If you're working from within another script, using the Advanced Method, you can add an AND controller to the "body" object and connect the Collision and Ray sensors to it.
3. Do Not modify any of the settings on the Collision and Ray sensors, except for the Property name text field. Modifying any other settings will prevent the sensors from being recognized by the script.

Property Hooks [top]

Property hooks are regular properties in the Logic Editor that can be added to the object using this script. They have unique names for easy identification, and provide values to the script to modify features in real-time from within the Game engine. Property hooks can be easily controlled with logic bricks, which is especially helpful for non-programmers.

Property hook names are case-insensitive, so capitalization does not matter. The Property hooks for each system of the script are listed below. Each property hook begins with a prefix unique to its system.

MouseMove Core Properties [top]

All MouseMove Core property hooks begin with "mmc.", which stands for "MouseMove Core".

Mouselook Properties [top]

All Mouselook property hooks begin with "ml.", which stands for "Mouselook".

Static Movement Properties [top]

All Static Movement property hooks begin with "sm.", which stands for "Static Movement".

Dynamic Movement Properties [top]

All Dynamic Movement property hooks begin with "dm.", which stands for "Dynamic Movement".

Callable Methods [top]

If you import the script and create an instance of the Core class, you will be able to call certain methods from it to modify features of the script. This is a more advanced alternative to using Property Hooks.

In the following methods, use any of the Property Hook names as the propertyName parameter (not case sensitive).

Config Properties (Advanced) [top]

The Config Properties are a set of default properties used by the MouseMove script. They are contained in the CONFIG string variable near the top of the script. The CONFIG variable gets parsed by the __init__ method of the Core class to extract the default properties and their data types.

The purpose of the Config Properties are to provide default values for the MouseMove script when custom values are either not specified in Property Hooks, or the specified properties are not the right data type (i.e., a string is given instead of the required numeric value). The Config Properties also make it very easy for anyone modifying the script to define and retrieve Property Hook values without having to hard-code in failsafes for dealing with case-sensitivity or invalid values.

The default variables defined in the Config Properties cannot be removed without causing errors. However, new variables can be added by those who wish to modify the MouseMove script.

Property Categories:
The Config Properties are categorized by which feature of the MouseMove script they belong to. There are four default categories:

• "mcc" - MouseMove Core
• "ml" - Mouselook
• "sm" - Static Movement
• "dm" - Dynamic Movement

You may notice that the Property Hooks all begin with one of these names listed above. All properties in the CONFIG variable are defined in one of these four categories.

Data Types:
The Data Types of properties, as mentioned before, "cast" the values to a certain data type. This means that a property casted to a certain data type will only allow Property Hooks of that same data type to override the default value.
The data type names used for casting variables in the Config Properties are:

Creating New Properties:
To create a new property that can be used in the MouseMove script, either pick one of the four pre-existing categories to define it in, or create a new Category and define the property there. The syntax is as follows:

Example from the MouseMove script:

Syntax Rules:

• When starting a Category, the left curly bracket { goes on the same line as the Category name.
• When ending a Category, the right curly bracket } goes on its own line.
• Data Type names are wrapped in parentheses:
  • Boolean type = (bool)
• Each defined property goes on its own line
• An equals sign goes between the Property Name and its Value:
  • (type) prop = value
• Spaces in Category and Property names are allowed, but these are whitespace-sensitive:
  • "run    speed" is not the same as "run speed"
• Extra spacing between syntax is disregarded:
  • (type)   prop  =    value is the same as (type) prop = value
  • This does not refer to the spaces in Category or Property names, which are whitespace sensitive.
• Comments can start on any line, using the # symbol, and are ignored by the parser code
• Leaving the Value field empty will print an error message and not register the property.
• Typing a value that doesn't match its casted Data Type will not register the property.
• Using an invalid Data Type for casting will print an error message and not register the property.
• A Property Hook name is the Category + . + Property Name:
  • category.propName
• Category and Property names are not case-sensitive
• Do Not remove the triple quotes ( """ ) from the CONFIG variable - the script will break!

Changelog [top]

Update 2.7

• Renamed from "[FPS] Mouselook + Movement Script" to "MouseMove Script"
• Rewrote entire script - bugs may be expected
• New property system: default properties in CONFIG string variable at top of script
  • The contents of CONFIG get parsed and used to check object properties
  • See Config Properties
• All Property Hooks renamed and modified! Check the Property Hooks section for complete details.
  • "enable" -> "mmc.mouselook" (See other Mouselook Property Hooks)
  • "cursor" -> "mmc.cursor"
  • "layout" -> "mmc.lefthanded"; (IJKL keyboard layout)
  • "lmove" -> "mmc.static"; (See other Static Movement Property Hooks)
  • "dmove" -> "mmc.dynamic"; (See other Dynamic Movement Property Hooks)
• New Property Hook features:
  • "mmc.lefthanded"
  • "ml.capupper"
  • "ml.caplower"
  • "ml.caporigin"
  • "sm.cameramode"
  • "dm.runspeed"
  • "dm.movemidair"
• New/modified Callable Methods (previously known as "callable functions")
• Improved the Mouselook Cap system. If the object is past the capping range, it will be snapped to the correct orientation, rather than being allowed free rotation outside of the range as before.
  • See the ml.cap properties in the Mouselook Property Hooks for more information.

Update 2.61:

• Removed dependency on Mouse Movement sensor. Use any sensor to trigger the Mouselook script.
  • Use an Always sensor with True Level Triggering enabled to run on every frame
• Location Move Controls: Readded E and Q as alternative Fly Up/Down keys (U and O for Layout 2)
• Added mouselook.setCenter() to the list of callable functions
  • Sets the mouse cursor to the center of the screen.

Update 2.6:

• Cleaned up the code
• Property Tags no longer case-sensitive
• Mouselook class in mouselook.py can be instantiated as an object
  • Run the main() function on the object to update it
• Callable functions on the Mouselook class object for changing mouselook properties (Advanced)
• Location Move Controls: Space = Fly Up; Ctrl = Fly Down; Shift = Speed Up
• Dynamic Move Controls: Shift = Run; Ctrl = Slow movement