Difference between revisions of "LlTakeControls"

From Second Life Wiki
Jump to navigation Jump to search
m
(15 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{Issues/SVC-3187}}{{LSL_Function/permission|PERMISSION_TAKE_CONTROLS}}{{LSL_Function
{{LSL_Function
|inject-2={{Issues/SVC-3187}}{{Issues/SCR-97}}{{LSL_Function/permission|PERMISSION_TAKE_CONTROLS}}{{LSL_Function/boolean|}}{{LSL_Function/boolean|}}accept pass_on FIXME!!!
|func_id=111|func_sleep=0.0|func_energy=10.0
|func_id=111|func_sleep=0.0|func_energy=10.0
|sort=TakeControls|func=llTakeControls
|sort=TakeControls|func=llTakeControls
|p1_type=integer|p1_name=controls|p1_desc=bitfield of CONTROL_* flags
|p1_type=integer|p1_name=controls|p1_desc=bitfield of CONTROL_* flags
|p2_type=integer|p2_name=accept|p2_desc=boolean, determines whether [[control]] events are generated
|p2_type=integer|p2_subtype=boolean|p2_name=accept|p2_desc=boolean, determines whether [[control]] events are generated
|p3_type=integer|p3_name=pass_on|p3_desc=boolean, determines whether controls are disabled
|p3_type=integer|p3_subtype=boolean|p3_name=pass_on|p3_desc=boolean, determines whether controls perform their normal functions
|func_footnote=If '''accept''' is [[FALSE]] and '''pass_on''' is [[FALSE]], then the specified controls behave normally, and all other controls are disabled.<br />
|func_footnote=If {{LSLP|accept}} is [[FALSE]] and {{LSLP|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.<br />
If '''accept''' is [[FALSE]] and '''pass_on''' is [[TRUE]], then all controls behave normally.<br />
If {{LSLP|accept}} is [[FALSE]] and {{LSLP|pass_on}} is [[TRUE]], then the specified controls do not generate events but perform their normal functions.<br/>
If '''accept''' is [[TRUE]] and '''pass_on''' is [[FALSE]], then the specified controls are disabled (but generate [[control]] events), and all other controls behave normally.<br />
If {{LSLP|accept}} is [[TRUE]] and {{LSLP|pass_on}} is [[FALSE]], then the specified controls generate events but do not perform their normal functions.<br />
If '''accept''' is [[TRUE]] and '''pass_on''' is [[TRUE]], then the specified controls generate [[control]] events, and all controls behave normally.
If {{LSLP|accept}} is [[TRUE]] and {{LSLP|pass_on}} is [[TRUE]], then the specified controls generate events and perform their normal functions.
|func_desc=Allows for intercepting of keyboard and mouse clicks, specifically those specified by '''controls''', from the agent the script has permissions for.
|func_desc=Allows for intercepting of keyboard and mouse clicks, specifically those specified by {{LSLP|controls}}, from the agent the script has permissions for.
|return_text
|return_text
|spec
|spec
|caveats
|caveats=
* There appears to be no penalty for using {{LSLP|accept}} = TRUE, {{LSLP|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 {{LSLP|accept}} = FALSE, {{LSLP|pass_on}} = TRUE
* If you sit/are sitting on the object that has taken your controls using {{LSLP|accept}} = [[TRUE]] and {{LSLP|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 {{LSLP|pass_on}} = FALSE, then [[llGetAnimation]] will never be "Turning Left" or "Turning Right", respectively, and those animations set by [[llSetAnimationOverride]] will never play
|constants={{LSL_Constants/Controls}}
|constants={{LSL_Constants/Controls}}
|examples=<lsl>default
|examples=<source lang="lsl2">default
{
{
     state_entry()
     state_entry()
Line 34: Line 39:
                             CONTROL_DOWN |
                             CONTROL_DOWN |
                             CONTROL_LBUTTON |
                             CONTROL_LBUTTON |
                             CONTROL_ML_LBUTTON |
                             CONTROL_ML_LBUTTON ,
                             0, TRUE, TRUE);
                             TRUE, TRUE);
                         
         }
         }
     }
     }
Line 46: Line 52:
         llOwnerSay(llList2CSV([level, edge, start, end, held, untouched]));
         llOwnerSay(llList2CSV([level, edge, start, end, held, untouched]));
     }
     }
}</lsl>
}</source>
|helpers
|helpers
|also_functions={{LSL DefineRow||[[llReleaseControls]]}}
|also_functions={{LSL DefineRow||[[llReleaseControls]]}}
Line 52: Line 58:
|also_articles
|also_articles
|also_tests
|also_tests
|notes=If a script has taken controls, it will not be stopped if the Agent enters a No-Script Area. This is done to keep vehicle control alive and AOs functional. This is an intentional feature. These scripts will stop working if they call certain blacklisted functions.
|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.  
|cat1=Controls
|cat1=Controls
|cat2
|cat2

Revision as of 08:50, 11 April 2020

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

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