Angular Velocities in Unity

Recently I was at a hackathon, and as you do at hackathons I decided that I wanted to make the companion robot for our game float around using actual physics. A long time ago I used to be into Kerbal Space Program, and back then I wrote a script in-game that simulated a suicide burn landing like SpaceX rockets do, and I decided for this project I wanted my robot’s entire movement system to use that math, and you can see the result here:

However this was a lot harder to get working then I expected, since as I found out, for the 5+ years I’ve been doing Unity physics I never actually learned how angular velocity works inside of physics engines, and it’s never explicitly stated in the Unity documentation how it works!

How everyone (except physics majors) think angular velocity is represented.

The angularVelocity member of a Unity Rigidbody returns a Vector3, and the docs say:

The angular velocity vector of the rigidbody measured in radians per second.

And this is all the docs give you to work with. So, unless you notice that their example is doing something weird with the magnitude of this vector, you’re probably going to jump to assuming that this means, the rotation around the x, y, and z axis in radians per second in global space. Where to get how fast around each one of these axis your rotating, you’d just go angularVelocity.[x/y/z]. But this is NOT how it works at all apparently.

What it Actually is

If you look at the docs for Rigidbody.angularVelocity and Rigidbody.AddTourqe(), there’s a term that doesn’t stick out.

Angular Velocity Vector

Turns out that “Angular Velocity Vector” is a very specific term from physics, where the normalized version of said vector is the axis that the object is rotating around, and the magnitude of that vector is the speed that it’s rotating around that vector. And if google this term exactly, you get a ton of resources on it, but if you look up “angular velocity unity” or any variation of that, you don’t get any of those resources (Hopefully this article fixes that)

But once you realize that, you realize that angular velocity is actually pretty easy to work with

What angular velocity vectors allow you to do

Rotation around an axis

Now that we know angularVelocity doesn’t give us the speed we’re rotating around any global axis, what if we still want to get that? Super easy: Just take the dot product of angularVelocity and a normalized axis that you want the radians-per second of!

For instance in my reality hack project, I get the local per-axis rotation of my floating robot like this:

Rigidbody rb = GetComponent<Rigidbody>();
Vector3 v = rb.angularVelocity;

Vector3 components = new Vector3 {
    x = Vector3.Dot(rb.rotation * Vector3.right, v), 
    y = Vector3.Dot(rb.rotation * Vector3.up, v), 
    z = Vector3.Dot(rb.rotation * Vector3.forward, v) 
} * Mathf.Rad2Deg;

And you don’t have to overthink adding angular velocities together either, you can just add them together like regular vectors, and the result will function as expected. So after I do my physics math I apply whatever forces I calculated like this:

rb.AddTorque(transform.right * components.x + transform.up * components.y + transform.forward * components.z, ForceMode.Acceleration);

Oh and one final footgun! angularVelocity is in radians-per-second, but AddTorque() uses degrees per second. Truly a Unity moment.

Hope this helped!

I wrote this because if this article had been searchable it would have saved me 4+ hours of messing with things like different order of Euler angles and other random stuff to try to get stuff working. Hopefully this helps you much faster if you didn’t just ask a LLM like I probably should have.