$nav
===== Function: llTakeControls =====

<code lsl2>
llTakeControls(integer controls, integer accept, integer pass_on)
</code>

Enables the user to use certain control keys or mouse button presses for interacting with a script.

Requires $lct[PERMISSION_TAKE_CONTROLS] permissions.

===== Parameters =====

=== controls ===
A bit mask of $ct[CONTROL_*] constants

=== accept ===
Whether to generate $lev[control] events for the specified controls. $lct[TRUE] = generate them; $lct[FALSE] = don't generate them.

=== pass_on ===
Whether the specified controls should still perform their normal functions (e.g. if $lct[CONTROL_FWD] is among the controls to take, whether it still moves the avatar forward). $ct[TRUE] = perform their normal functions too; $ct[FALSE] = don't perform their normal functions. Note that a value of $ct[TRUE] is not honoured for $lct[CONTROL_ML_LBUTTON]

===== Notes =====

  * Even if $prm[pass_on] is $ct[TRUE], when $lct[CONTROL_ML_LBUTTON] is in the controls, mouse clicks are blocked while in mouselook ($JIRA[SVC-4973], $JIRA[SVC-7532], declared as expected behaviour).
  * While it's possible for two scripts in the same prim to take controls from two different users, that won't work as expected: there's no way to know the originator of the control. $TODO[Expand/Test again] See the $lev[control] event for more details.

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

<code lsl2>
// Capture the forward control, but let it still move the avatar forward.
llTakeControls(CONTROL_FWD, TRUE, TRUE);

// Capture all controls that let the agent move (it can still move when pushed or falling)
llTakeControls(CONTROL_FWD|CONTROL_BACK
              |CONTROL_LEFT|CONTROL_RIGHT
              |CONTROL_UP|CONTROL_DOWN
              |CONTROL_ROT_LEFT|CONTROL_ROT_RIGHT
              , TRUE, FALSE);
</code>

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

This example will report presses of the UP and DOWN controls in chat, after permissions are granted.

<file lsl2 llTakeControls-example.lsl>
default
{
    state_entry()
    {
        llRequestPermissions(llGetOwner(), PERMISSION_TAKE_CONTROLS);
    }

    run_time_permissions(integer perms)
    {
        if (perms & PERMISSION_TAKE_CONTROLS)
            llTakeControls(CONTROL_UP | CONTROL_DOWN, TRUE, TRUE);
    }

    controls(key avatar, integer level, integer edge)
    {
        if (level & edge & CONTROL_UP)
            llOwnerSay("UP pressed");
        if (~level & edge & CONTROL_UP)
            llOwnerSay("UP released");
        if (level & edge & CONTROL_DOWN)
            llOwnerSay("DOWN pressed");
        if (~level & edge & CONTROL_DOWN)
            llOwnerSay("DOWN released");
    }
}
</file>

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

  * $lfn[llReleaseControls] to release controls that were taken with $fn[llTakeControls], and also the $ct[PERMISSION_TAKE_CONTROLS] permission
  * $lev[control] event, to be notified when controls are pressed and the $prm[accept] parameter is $ct[TRUE].
  * $lfn[llRequestPermissions], $lct[PERMISSION_TAKE_CONTROLS] and $lev[run_time_permissions] are typically needed in scripts that use this function.