llTakeControls

function

Function syntax

llTakeControls(

integer controls,// Bitfield of CONTROL_* flags to intercept. Values: ControlButton
integer accept,// Boolean. Determines whether control events are generated to trigger script handlers.
integer pass_on// Boolean. If TRUE, the keys also perform their default functions; if FALSE, default actions are suppressed.

);

Energy: 10
Permission: PERMISSION_TAKE_CONTROLS

Allows for intercepting of keyboard and mouse clicks, specifically those specified by controls, from the agent the script has permissions for.

If accept is FALSE and pass_on is FALSE, the behavior is not intuitive. In this case, the complement of the specified controls do not generate events and do not perform their normal functions. They are effectively disabled. Certain control bits (e.g. CONTROL_ROT_LEFT) are also disabled when specified, in this case.

If accept is FALSE and pass_on is TRUE, then the specified controls do not generate events but perform their normal functions.

If accept is TRUE and pass_on is FALSE, then the specified controls generate events but do not perform their normal functions.

If accept is TRUE and pass_on is TRUE, then the specified controls generate events and perform their normal functions.

llTakeControls(0, 0, 0);

Specification

Constant	Value	Description
`CONTROL_FWD`	0x00000001	Move forward control (`↑` or `W`)
`CONTROL_BACK`	0x00000002	Move back control (`↓` or `S`)
`CONTROL_LEFT`	0x00000004	Move left control (`←` or `A` [`←` or `A` in mouselook])
`CONTROL_RIGHT`	0x00000008	Move right control (`→` or `D` [`→` or `D` in mouselook])
`CONTROL_ROT_LEFT`	0x00000100	Rotate left control (`←` or `A`)
`CONTROL_ROT_RIGHT`	0x00000200	Rotate right control (`→` or `D`)
`CONTROL_UP`	0x00000010	Move up control (`PgUp` or `E`)
`CONTROL_DOWN`	0x00000020	Move down control (`PgDn` or `C`)
`CONTROL_LBUTTON`	0x10000000	Left mouse button control
`CONTROL_ML_LBUTTON`	0x40000000	Left mouse button control while in mouselook
(undocumented)	0x02000000	Avatar left rotation detected. Triggers `llGetAnimation` == “Turning Left”
(undocumented)	0x04000000	Avatar right rotation detected. Triggers `llGetAnimation` == “Turning Right”

Caveats

There appears to be no penalty for using accept = TRUE, pass_on = TRUE when there is no control event in the script (such as is used in AO’s to ensure they work on no-script land)
There is a bug in some permissions that prevents left clicks from working in mouselook if they are set to accept = FALSE, pass_on = TRUE
If you sit/are sitting on the object that has taken your controls using accept = TRUE and pass_on = TRUE, then CONTROL_FWD, CONTROL_BACK, CONTROL_ROT_LEFT, and CONTROL_ROT_RIGHT will never generate events; instead these controls will only perform their normal functions.
if the undocumented controls 0x02000000 or 0x04000000 are taken with pass_on = FALSE, then llGetAnimation will never be “Turning Left” or “Turning Right”, respectively, and those animations set by llSetAnimationOverride will never play
all control flags documented in libopenmetaverse secondlife viewer
If your viewer’s ‘Single click on land’ setting is set to ‘Move to clicked point’, then CONTROL_LBUTTON might not be sent to the server when taken by llTakeControls().

Examples

Example 1

8 collapsed lines
default
{
    state_entry()
    {
        llRequestPermissions(llGetOwner(), PERMISSION_TAKE_CONTROLS);
    }
    run_time_permissions(integer perm)
    {
        if(PERMISSION_TAKE_CONTROLS & perm)
        {
            llTakeControls(
                            CONTROL_FWD |
                            CONTROL_BACK |
                            CONTROL_LEFT |
                            CONTROL_RIGHT |
                            CONTROL_ROT_LEFT |
                            CONTROL_ROT_RIGHT |
                            CONTROL_UP |
                            CONTROL_DOWN |
                            CONTROL_LBUTTON |
                            CONTROL_ML_LBUTTON ,
                            TRUE, TRUE);

        }
10 collapsed lines
    }
    control(key id, integer level, integer edge)
    {
        integer start = level & edge;
        integer end = ~level & edge;
        integer held = level & ~edge;
        integer untouched = ~(level | edge);
        llOwnerSay(llList2CSV([level, edge, start, end, held, untouched]));
    }
}

Notes

If a script has taken controls, it and other scripts in the same prim will not be stopped if the Agent enters a “No Outside Scripts” parcel. This is done to keep vehicle control alive and AOs functional. This is an intentional feature. This only applies to the object containing the script - child objects in a linkset (wheels, particle emitters, in vehicles, child objects in huds, etc) will not inherit this immunity. To preserve functionality in child objects, llTakeControls must be issued in each scripted child as well.

Known issues

From the issue templates included by the wiki article:

SVC-3187 (bug): llTakeControls overrides existing controls
SCR-97 (bug): llTakeControls Traps repeating event when contols are changed or permission revoked