llTakeControls

From Second Life Wiki
Jump to navigation Jump to search

Summary

Function: llTakeControls( integer controls, integer accept, integer pass_on );

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

• integer controls bitfield of CONTROL_* flags
• integer accept boolean, determines whether control events are generated
• integer pass_on boolean, determines whether controls perform their normal functions

To run this function the script must request the PERMISSION_TAKE_CONTROLS permission with llRequestPermissions. 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.

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 (⇧ Shift- or ⇧ Shift-A [ or A in mouselook])
CONTROL_RIGHT 0x00000008 Move right control (⇧ Shift- or ⇧ Shift-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

Permissions
  • Once the PERMISSION_TAKE_CONTROLS permission is granted, it can be revoked from inside the script (with llReleaseControls or a new llRequestPermissions call), or if the user chooses Release Keys from the viewer. The script will also lose this permission on reset, or if the object is deleted, detached, or dropped.
  • 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
  • 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().

Important Issues

~ All Issues ~ Search JIRA for related Bugs
   llTakeControls overrides existing controls
   llTakeControls Traps repeating event when contols are changed or permission revoked

Examples

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);
                           
        }
    }
    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.

See Also

Events

•  run_time_permissions Permission receiving event
•  control

Functions

•  llGetPermissions Get the permissions granted
•  llGetPermissionsKey Get the agent who granted permissions
•  llRequestPermissions Request permissions
•  llReleaseControls

Articles

•  Script permissions

Deep Notes

All Issues

~ Search JIRA for related Issues
   llTakeControls overrides existing controls
   llTakeControls Traps repeating event when contols are changed or permission revoked

Signature

function void llTakeControls( integer controls, integer accept, integer pass_on );