# Controls

> lsl.dev (unofficial LSL docs). Full API: https://lsl.dev/api.json · Index for LLMs: https://lsl.dev/llms.txt

> Capturing keyboard and mouse controls: taking and releasing controls, the control event, and mouselook.

A script can capture an avatar's movement keys and left mouse button, which is how vehicles, weapons and HUDs read input. Part of the [Input](/features/input/) feature.

## Concepts

- Controls need [`PERMISSION_TAKE_CONTROLS`](/constants/PERMISSION_TAKE_CONTROLS/), [requested](/functions/llRequestPermissions/) from the avatar and granted in [`run_time_permissions`](/events/run_time_permissions/)
  - Granted without a dialog when the avatar is sitting on the object or wearing it
- [`llTakeControls`](/functions/llTakeControls/) takes **controls**, a mask of [`CONTROL_*`](/constants/groups/ControlButton/) [control buttons](/constants/groups/ControlButton/)
  - **accept** decides whether the controls raise [`control`](/events/control/) events
  - **pass_on** decides whether they still perform their normal function, such as moving the avatar
  - With both **accept** and **pass_on** [`FALSE`](/constants/FALSE/), every control *except* the specified ones is disabled
- [`llReleaseControls`](/functions/llReleaseControls/) gives the controls back and also revokes `PERMISSION_TAKE_CONTROLS`
- A script that has taken controls keeps running in "No Outside Scripts" parcels, which keeps vehicles and AOs working; this applies only to the prim holding the script
- [`control`](/events/control/) passes **id**, the avatar, plus two masks of [`CONTROL_*`](/constants/groups/ControlButton/) bits
  - **level** has a bit set for each control held down
  - **edge** has a bit set for each control that changed since the last event
- Mouselook
  - [`CONTROL_LBUTTON`](/constants/CONTROL_LBUTTON/) is the left mouse button in normal view, [`CONTROL_ML_LBUTTON`](/constants/CONTROL_ML_LBUTTON/) the same button in mouselook
  - [`llForceMouselook`](/functions/llForceMouselook/) puts avatars that sit on the prim into mouselook
  - [`llGetAgentInfo`](/functions/llGetAgentInfo/) reports [`AGENT_MOUSELOOK`](/constants/AGENT_MOUSELOOK/) while an avatar is in mouselook

## Functions and events

- `void` [`llRequestPermissions`](/functions/llRequestPermissions/) `(key agent, integer permissions)`
- `event` [`run_time_permissions`](/events/run_time_permissions/) `(integer perm)`
- `void` [`llTakeControls`](/functions/llTakeControls/) `(integer controls, integer accept, integer pass_on)`
- `void` [`llReleaseControls`](/functions/llReleaseControls/) `()`
- `event` [`control`](/events/control/) `(key id, integer level, integer edge)`
- `void` [`llForceMouselook`](/functions/llForceMouselook/) `(integer mouselook)`

## [Presses, releases and held keys](/events/control/)

Combine **level** and **edge** in the `control` event:

```lsl
integer start = level & edge;   // pressed this event
integer end = ~level & edge;    // released this event
integer held = level & ~edge;   // still held
```

## [Touch](/features/input/touch/)

Clicking objects, touch positions, click actions and touch text.

## [Game Control](/features/input/game-control/)

Controller-shaped [buttons and axes](/events/game_control/), from a game controller or translated keyboard and mouse, and game-control modes.

## Scripting Details

- `void` [`llRequestPermissions`](/functions/llRequestPermissions/) `(key agent, integer permissions)`: Requests permissions (a bitfield specified by permissions) from the agent in the same region, calling run_time_permissions if granted. This call does not pause script execution.
- `event` [`run_time_permissions`](/events/run_time_permissions/) `(integer perm)`: Triggered when an agent grants or denies runtime permissions requested by llRequestPermissions. Passes the active integer permissions bitfield perm (returns 0 if no permissions are currently granted).
- `void` [`llTakeControls`](/functions/llTakeControls/) `(integer controls, integer accept, integer pass_on)`: Intercepts inputs (keyboard/mouse clicks) from the agent, specifically those specified by controls. The boolean accept determines if events are generated, and pass_on determines if inputs also perform their default functions. Requires the PERMISSION_TAKE_CONTROLS runtime permission.
- `void` [`llReleaseControls`](/functions/llReleaseControls/) `()`: Stops taking inputs (previously acquired via llTakeControls) from the avatar, dequeuing any remaining control events and revoking the PERMISSION_TAKE_CONTROLS permission.
- `event` [`control`](/events/control/) `(key id, integer level, integer edge)`: 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).
- `void` [`llForceMouselook`](/functions/llForceMouselook/) `(integer mouselook)`: Sets whether any avatar sitting on this prim is forced into mouselook mode. Setting mouselook to TRUE forces the mode; FALSE (default) allows the avatar to keep their current camera mode.
- `integer` [`llGetAgentInfo`](/functions/llGetAgentInfo/) `(key id)`: Returns an integer bitfield containing status information about the agent specified by id (such as AGENT_FLYING, AGENT_ATTACHMENTS, AGENT_SITTING, etc.).

## Constant groups

Constant groups: [ControlButton](/constants/groups/ControlButton/) (10)

## Related

See also: [Input](/features/input/), [Permissions](/features/permissions/), [Input](/categories/input/), [LSL Controls (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Controls)
   (planned: Guide: capturing controls for a vehicle or weapon)

## Related features

- [Input](/features/input/)
- [Permissions](/features/permissions/)
- [Camera](/features/camera/)

---

From lsl.dev: https://lsl.dev/features/input/controls/