control

event

Event syntax

control(

key id,// UUID of the avatar whose inputs are captured.
integer level,// A bitfield of CONTROL_* constants representing currently held controls. Values: ControlButton
integer edge// A bitfield of CONTROL_* constants representing controls that just changed state. Values: ControlButton

) { … }

Triggered to pass captured avatar control inputs into the script. The parameter level indicates held controls, and edge indicates change in controls (both are bitfields of CONTROL_* constants).

Result of llTakeControls library function call and user input.

control(key id, integer level, integer edge)
{

}

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

CONTROL_ROT_LEFT and CONTROL_ROT_RIGHT can be triggered when an object is selected or edited. If the user is running Viewer 2.0 and later, llGetAgentInfo will have AGENT_AUTOPILOT set in this case.
Sitting upon an object that takes control may also trigger CONTROL_FWD, CONTROL_BACK, CONTROL_DOWN and CONTROL_UP, depending on avatar position relative to the seat.
Autopilot control events can continue for a short time after AGENT_AUTOPILOT drops.
The ‘levels’ and ‘edges’ of the control() event both receive (CONTROL_FWD + CONTROL_BACK) (value 3) after teleport, effecting scripts that use this combination for faster movement. Calling llTakeControls() again after a llSleep(3) will filter this out.

Examples

Example 1

24 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 |
                            0, TRUE, FALSE);
                            // | 0 is for edit convenience,
                            // it does not change the mask.
        }
    }
    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

llGetRot in mouselook for an attachment returns the angle the avatar is looking in.

There are some bugs when you put two scripts in the same prim and call LlTakeControls(), the id may not be the intended one. See SVC-3187.

Known issues

From the issue templates included by the wiki article:

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