$nav
===== Function: llApplyRotationalImpulse =====

<code lsl2>
llApplyRotationalImpulse(vector impulse, integer local)
</code>

Apply an instant change to the angular momentum of a physical object. It has no effect on non-physical objects or on attachments.

===== Parameters =====

=== impulse ===
A $lty[vector] specifying the impulse to apply, which will add to the object's current [[http://en.wikipedia.org/wiki/Angular_momentum|angular momentum]]. The vector's direction indicates the impulse's axis and its length indicates the magnitude. The units of the angular impulse vector seem to be $lart[lindogram|lindograms]·m²/s. Like in the real world, the effect on the angular velocity depends not only on the mass of the object, but also on its shape, as it's the product of [[http://en.wikipedia.org/wiki/Moment_of_inertia|moment of inertia]] (which itself depends on the [[http://en.wikipedia.org/wiki/List_of_moments_of_inertia|shape of the object]]) and angular velocity.

=== local ===
$lty[Boolean] value indicating whether the $prm[impulse] axis' coordinates are local to the root prim (if $lct[TRUE]) or in sim coordinates (if $lct[FALSE]).

When $ct[TRUE], the $prm[impulse] axis' coordinates are local to the root prim. For example, if $prm[impulse] is `<1, 0, 0> and the X axis of the root prim is looking northwest, then the impulse will have its axis oriented in the northwest direction, aligned with the root prim's X axis.

When $ct[FALSE], the vector specifies sim coordinates, where positive X is east, positive Y is north, positive Z is up, and vice versa for negative; for example, if $prm[impulse] is `<-1, 0, 0>, the rotational impulse will have its axis pointing west, no matter how the root prim is oriented.

===== Notes =====

  * The maximum angular velocity of an object seems to be about 127 rad/s (about 1212 rpm). Note, however, that $lfn[llGetOmega] will not return a value with a magnitude greater than 62.8 rad/s (about 599.7 rpm).

===== Short examples =====

<code lsl2>
// Assuming a 1x1x1 cube with no gravity and no initial angular velocity,
// the following line will make it spin at an initial angular velocity of 0.6 rad/s
// over its local Z axis:
llApplyRotationalImpulse(<0, 0, 1>, TRUE);
// 0.6 rad/s is derived from the moment of inertia of a cube spinning over its
// axis (m*l^2/6, where l is the length of the side) and the impulse applied.
// The mass of such a cube is 10 lindograms. Measurement with llGetOmega
// indicates that it works this way.
</code>

===== Complete examples =====

This example verifies the physical accuracy of $fn[llApplyRotationalImpulse] on an undeformed box of any dimensions. Moment of inertia varies with shape, so most deformations affect the results.

<code lsl2 llApplyRotationalImpulse-test.lsl>
float IMPULSE = 1.31; // change this value to any value to test

default
{
    touch_start(integer n)
    {
        // Disable gravity, enable physics, wait for the setting to take effect
        llSetPhysicsMaterial(GRAVITY_MULTIPLIER, 0, 0, 0, 0);
        llSetStatus(STATUS_PHYSICS, TRUE);
        llSleep(0.5);

        // Begin the test
        llApplyRotationalImpulse(<0, 0, IMPULSE>, TRUE);
        llSleep(0.03); // let a simulator frame pass

        // NOTE: Rotational friction is applied almost instantly, meaning the
        // returned value will be less than the theoretical one most of the
        // times. Sometimes we're lucky and get the actual value.
        vector omega = llGetOmega();

        // Disable physics again, return to zero rotation.
        llSetStatus(STATUS_PHYSICS, FALSE);
        llSetRot(<0, 0, 0, 1>);

        // Calculate and report results.
        vector size = llGetScale();
        // Predicted omega is impulse divided by moment of inertia.
        // Moment of inertia of a box rotating on its z axis is m*(size.x²+size.y²)/12.
        float predicted = IMPULSE/(llGetMass()*(size.x*size.x+size.y*size.y)/12);
        llSay(0, "Theoretical omega: " + (string)predicted
                   + ", actual omega: " + (string)omega.z
                   + ", difference:" + (string)(predicted - omega.z)
             );
    }
}
</code>

===== See also =====

  * $lfn[llApplyImpulse] is similar but for [[http://en.wikipedia.org/wiki/Momentum|linear momentum]] instead of angular.
  * $lfn[llSetAngularVelocity] applies the rotational impulse necessary to set the given angular velocity for an object.
  * $lfn[llGetOmega] obtains the current angular velocity of the object.
  * $lfn[llTargetOmega] tries to keep a constant angular velocity.
  * $lfn[llSetTorque] applies an angular force (a torque) to an object continuously
  * $lfn[llSetForce] is the linear equivalent to $fn[llSetTorque].
  * $lfn[llSetForceAndTorque] sets both force and torque at the same time.
  * $lfn[llSetVelocity] and $lfn[llGetVel] are the linear equivalents of $fn[llSetAngularVelocity]/$fn[llGetOmega].
  * $lfn[llGetMass] returns the mass in $lart[lindogram|Lindograms] of an object.
  * $lfn[llGetMassMKS] returns the mass in kilograms of an object. Most LSL functions use $art[Lindograms], so this function is of limited use in physics calculations.
  * $lfn[llVecNorm] to obtain a unit vector from a given one.