Gimbals

A gimbal is a type of joint that can rotate on the horizontal and vertical planes, like a turret. Gimbals are useful for many different things - first and third person characters, capital ships, turrets, mechs, overhead camera controllers, and more.

The Gimbal Controller is a component that is designed to provide extended functionality for a joint of this type, enabling you to set the horizontal and vertical pivots, set rotation limits, and control the joint with easy-to-use functions.

Creating a Gimbal

To create a gimbal, add a Gimbal Controller to a gameobject, and set the Horizontal and Vertical Pivot transforms in the inspector. Usually, the Horizontal Pivot would be a child of the root transform of the gimbal, and the Vertical Pivot a child of the Horizontal Pivot. With this hierarchy, the vertical pivot is rotated when the horizontal pivot rotates.

Rotating The Gimbal

To rotate the gimbal, call the Rotate function and pass the desired angle deltas (changes in angle) that you wish to rotate the gimbal with. For example, this might be the horizontal and vertical input from the mouse.

Track A Target

To track a position in space, call the Track Position function, passing the world coordinates of the target position to the Target parameter. The gimbal will track that position automatically.

Under the Gimbal Motors header in the inspector, you can use the Proportional Coefficient to determine how fast the gimbal should rotate toward its target. The other settings there constitute a PID controller, which is a bit involved and not necessary to understand. The default settings should do a good job without modification. You can also set angular velocity limits to prevent sudden, snappy rotation when the target is far away from the gimbal's current orientation.

Returning to Idle

You can set idle angles for the horizontal and vertical pivots, and make the turret return to the idle position with a line of code. This is useful, for example, if you want a turret to return to a 45 degree raised orientation when idle.

Set the Horizontal Idle Angle and the Vertical Idle Angle in the inspector, and call the Gimbal Controller's Idle function, passing a single boolean parameter (True/False) that determines whether to snap the joint back to the idle angle, or move toward it smoothly.