LSL Wiki : llTakeControls

**##llTakeControls([[integer]] controls, [[integer]] accept, [[integer]] pass_on)##**

The [[control]] functions allow an [[object]] to respond to [[userinterface user interface]] input that normally controls the [[agentandavatar avatar]]. For example, this allows creation of a [[script scripted]] [[vehicles vehicle]] that moves in response to the keyboard commands that normally move the avatar. Also, a [[ExampleGun gun]] can be created that fires in response to mouse button activity.

The **##controls##** [[parameter]] is an [[integer]] [[bitfield]] which is used to specify which user-interface controls the script is interested in. Possible [[value values]] are:

|||c **Constant** || **Hex** || **Integer** || **Description** ||
|| ##CONTROL_FWD## || 0x00000001 || 1 || forward control (W or up arrow) ||
|| ##CONTROL_BACK## || 0x00000002 || 2 || back control (S or down arrow) ||
|| ##CONTROL_LEFT## || 0x00000004 || 4 || move left control (shift + A or left arrow) ||
|| ##CONTROL_RIGHT## || 0x00000008 || 8 || move right control (shift + D or right arrow) ||
|| ##CONTROL_UP## || 0x00000010 || 16 || up control (E or ""PgUp"") ||
|| ##CONTROL_DOWN## || 0x00000020 || 32 || down control (C or ""PgDn"") || 
|| ##CONTROL_ROT_LEFT## || 0x00000100 || 256 || rotate left control (A or left arrow) ||
|| ##CONTROL_ROT_RIGHT## || 0x00000200 || 512 || rotate right control ( D or right arrow) ||
|| ##CONTROL_LBUTTON## || 0x10000000 || 268,435,456 || left mouse button control ||
|| ##CONTROL_ML_LBUTTON## || 0x40000000 || 1,073,741,824 || left mouse button control with the avatar in [[MouseLook]] **See ^Note** |||

To filter multiple button presses, combine these values using the ##|## ([[bitwise]] ##OR##) [[operators operator]]. (See [[#example below]] for an example.)

The **##accept##** and **##pass_on##** parameters take a **##[[TRUE]]##** or **##[[FALSE]]##** value and have different effects:

|||c **##accept##** || **##pass_on##** || effect ||
|| 0 || 0 || only specified controls functional...no script events ||
|| 0 || 1 || no apparent effect (all controls functional)...no script events ||
|| 1 || 0 || other controls functional no events...specified controls non-functional but generate events ||
|| 1 || 1 || all controls normal...specified controls also generate events |||

An object must have [[permissions permission]] to take controls. [[call Call]] ##[[llGetPermissions]]## to see if the object has the ##PERMISSION_TAKE_CONTROLS## permission. If it does not, you must first call ##[[llRequestPermissions]]## to request permissions from the [[user]].

After this function has been called and depending on the other parameters, the scripts's ##[[control]]## [[event]] handler will be invoked whenever a specified input is received. The [[code]] you place in the ##[[control]]## event handler determines how your object behaves in response to captured user input.

Each [[call]] to this function replaces the settings for any previous call. Unfortunately, that means a script can't completely control some inputs and let others continue to function while getting events. Fortunately there's a small glitch that is extremely handy since we can't rotate an avatar with a script. See [[#glitch below]] for more info.

When done with the controls (for example, when an attachment is removed) it is a good idea to clean up with a call to ##[[llReleaseControls]]##.

##CONTROL_ML_LBUTTON## will cause a "[[mouselook Mouselook]]" button to appear on the bottom of the [[SL]] window, but only if ##**pass_on**## is set to ##FALSE##.

%%(lsl)
llTakeControls(CONTROL_ML_LBUTTON, TRUE, FALSE); // this works.
llTakeControls(CONTROL_ML_LBUTTON, TRUE, TRUE); // this doesn't.
%%

**Note:** There seems to be a bug when taking CONTROL_ML_LBUTTON where it does not produce a [[MouseLook]] button after re-attaching even though permitted. Solution:
%%(lsl)llReleaseControls();
llRequestPermissions(llGetOwner(), PERMISSION_TAKE_CONTROLS);
llTakeControls(CONTROL_ML_LBUTTON,TRUE,FALSE);%%

=#example#=**Example** (see [[ExampleControls]] for a functioning script):

%%(lsl)
    run_time_permissions(integer perms)
    {
        integer desired_controls = 
                CONTROL_FWD |
                CONTROL_BACK |
                CONTROL_LEFT |
                CONTROL_RIGHT |
                CONTROL_ROT_LEFT |
                CONTROL_ROT_RIGHT |
                CONTROL_UP |
                CONTROL_DOWN |
                CONTROL_LBUTTON |
                CONTROL_ML_LBUTTON;

if (perms & PERMISSION_TAKE_CONTROLS) {
            llTakeControls(desired_controls, TRUE, FALSE);
        }
    }
%%

**Taking Complete Control**

=#glitch#=There is a handy glitch that can be used to work around a major shortcoming of the ##control()## system. There are many reasons why you might want to grab all the user input and not allow the standard av motion to take effect. For example, creating a custom movement solution.

The problem is that avs can not be scripted to rotate so normally using this function to grab all the input controls with **##accept##** set to ##1## and **##pass##** to ##0## will prevent a user from turning their av in normal non-mouselook view. You can leave out the right and left rotations but then you won't get events for them.

The trick is to make two calls to this function with the correct parameters. Using the following example, you'll take complete control (no normal movement) of all input except for left and right rotation which will behave normally and also generate ##control()## events:

%%(lsl)
    run_time_permissions(integer perms) {
        if (perms & PERMISSION_TAKE_CONTROLS) {
            llTakeControls(1, 1, 0); // glitch the rotation
            llTakeControls(desired_controls, 1, 0);
        }
    }
%%

Hopefully if a 'fix' is made that changes this, the fix will include the functionality we all want and need.

** Detecting loss of control **
If someone releases controls after they have been granted, a [[call Call]] to ##[[llGetPermissions]]## compared with ##PERMISSION_TAKE_CONTROLS## will show that the object no longer has permission.  This can be done with a timer event.

%%(lsl)
default
{
    touch_start(integer start_param)
    {
        llRequestPermissions(llDetectedKey(0), PERMISSION_TAKE_CONTROLS);
    }
    run_time_permissions(integer perm)
    {
        if(perm & PERMISSION_TAKE_CONTROLS)
            state controlled;
    }
}
state controlled
{
    state_entry()
    {
        integer controls = 
            CONTROL_FWD | CONTROL_BACK
            | CONTROL_LEFT | CONTROL_RIGHT
            | CONTROL_UP | CONTROL_DOWN;

llTakeControls(controls, TRUE, FALSE);
        
        llSetTimerEvent(5);
    }
    timer()
    {
        if(llGetPermissions() & PERMISSION_TAKE_CONTROLS)
            return;
        state default;
    }
}
%%

----
[[functions Functions]] | [[AgentAndAvatar Agent/Avatar]] | [[control Control]]