Torque 3D Now Supports the Leap Motion Controller

Torque 3D Now Supports the Leap Motion Controller

Back on September 20, 2012, we launched the MIT licensed version of Torque 3D on GitHub. Next on December 19, 2012, we launched the first new release under open source, version 2.0. Then on January 10, 2013, the T3D Steering Committee announced the roadmap for version 3.0. Within this roadmap was improved support for various input devices to take advantage of current and future controllers that are entering the PC market. Today we announce support of one such input device, the Leap Motion controller. I will jump right in and show off the Leap Motion support in Torque 3D, and then talk about the engine changes that have been made for new input devices in general.

The Leap Motion Controller and Torque 3D

The Leap Motion controller takes input from hands, fingers, and small tools that are moved just above it. If you are not familiar with the Leap Motion controller you should head over to their site where there are a number of videos demonstrating the product.


Through the Leap Motion SDK (currently limited to a few thousand developers), Torque 3D is able to receive this physical input and interpret it as input events that are sent to your game. The following types of input events are currently supported:

Hands and Fingers Input Events
The absolute position (in millimeters) and rotation for up to two hands and five fingers per hand. The number of supported elements may be expanded with a change of a source code constant. As the Leap Motion SDK currently doesn’t have a mapping of physical fingers to virtual fingers, the indices of these input events depend on how they are presented by the SDK. These events can be useful when you are interested in tracking a single hand or finger, or their order isn’t important.


The backpack’s position above the cube, as well as its local rotation, are being controlled by a single hand moving over the Leap Motion controller.

Hands and Fingers with Persistent ID Input Events
The Leap Motion SDK assigns an ID to each element it can see. By using this ID Torque 3D attempts to maintain the input event order such that if a particular hand or finger is associated with a specific input event index, then that association is maintained even if other hands or fingers come and go.

Hand as Thumb Stick Input Events
Based on the values returned by the Leap Motion SDK, Torque 3D can interpret the rotation of a single hand as if it were a gamepad thumb stick. Imagine that a stick is coming out of the top of your hand and as you tilt your hand, you are moving this stick. This also takes advantage of Torque 3D’s action mapping system including being able to define dead zones. This makes it very easy to jump in with using the Leap Motion if this type of input works for you application. You could, for example, move the player around in one of Torque 3D’s standard templates by using these events.

Whole Frame Input Events
With your application it is possible that the above input events don’t fit in with how you would like to use the Leap Motion controller. In this case Torque 3D provides a single input event each time it reads a frame from the Leap Motion. This frame is presented as a special SimObject (the LeapMotionFrame class) with the frame’s properties accessible using TorqueScript methods. These frames are automatically stored on the LeapMotionFrameGroup SimGroup so a short history may be accessed at any time (and old frames are recycled to become new frames).

Leap Motion Controller Wiki Page

All of this information and more in now available on the Leap Motion Wiki Page on GitHub. This includes a more thorough description of these input events, how to best use them, as well as how to add Leap Motion support to your own Torque 3D project.

Leap Motion and Torque 3D Demo Game: Marble Motion

To help demonstrate using the Leap Motion controller and Torque 3D, Ron Kapaun and I have created a small, example game called Marble Motion. You may see it in action in this short video I put together:



The Marble Motion demo is available for anyone to try out. Download the demo here:

Marble Motion Demo 1.0b

Just unzip the package and launch the executable. Be sure to have your Leap Motion controller and the Leap application running before launching the demo. If you don’t have a Leap Motion controller you may also use a Xbox 360 compatible gamepad, or the keyboard arrow keys to drive the marble around.

This demo uses Torque 3D’s standard RigidShape class for the marble physics so it may be interesting to poke around the scripts and see how it is done. It also makes use of the new ScriptTickObject class that is available on the development branch for the game’s state machine and marble handling.



Now on to a description of some of the new components in the development branch that make all of this possible.

New InputEventManager Class

Previously in Torque 3D, all input devices were hard coded within the engine. In the early days we had the keyboard, mouse, and joysticks (through DirectInput). With the introduction of the Xbox 360 in 2005, support for Xbox 360 compatible gampads (through XInput) was tacked on. Under this system all controller events we tracked in a couple of hard coded tables within the source code, which made it difficult to add new controllers.

The new InputEventManager class helps with this situation by allowing new input devices to register themselves and their input events. This class also provides methods to help new input devices broadcast their events to the Torque 3D input and action map system. Currently we are taking a staged approach such that the hard coded tables still exist for the older input devices. However, down the road it would be great to move the gamepad and joystick devices over to the new InputEventManager system.

New Input Event Types

Torque 3D categorizes its input events into various types so the receiver of the event knows the context of the information. The existing event types are: keyboard key, button, point of view hat, and axis (ranges from -1 to 1 for joysticks, thumb sticks, and mouse moves).

With the new input controllers becoming available in the marketplace these event types are not enough. The following new event types have been added:

• SI_POS: Absolute position value (Point3F)
• SI_ROT: Absolute rotation value (QuatF)
• SI_INT: Integer value (S32)
• SI_FLOAT: Float value (F32)

In order to support these new input event types, Torque 3D’s signal and journalling system had to be expanded to deal with the additional components. All of the older event types pass along a single value, but the new position (3 components) and rotation (4 components) event types require multiple values. To support these multiple components all of the signal and journal templates had to be expanded in the source code.

New ExtendedMove Class

While the Marble Motion demo doesn’t make use of it, there is a new ExtendedMove class that allows the sending of absolute position and rotation information from the client to the server. This may be useful for multiplayer games where the server needs to verify motion based on the controller’s input. This is similar to how mouse and joystick changes are passed using the standard Move class. You may read more about the ExtendedMove class on this Wiki page.

The Future

These are just the first steps at supporting the Leap Motion controller, and new input devices in general. Any community input would be much appreciated.

- Dave