# Touch

> Clicking objects: touch events, where a prim was touched, click actions and touch text.

Clicking an object raises touch events in its scripts, and the detected functions tell who touched, which prim and exactly where. Touch needs no permission. Part of the [Input](/features/input/) feature.

## Touch events

- [`touch_start`](/events/touch_start/) is triggered when an avatar first touches the object, [`touch`](/events/touch/) continuously while it touches, and [`touch_end`](/events/touch_end/) when it stops
  - Each passes **num_detected**, the number of touching agents; read [who touched](/functions/llDetectedKey/) with the detected functions
  - [`llDetectedLinkNumber`](/functions/llDetectedLinkNumber/) gives the link number of the touched prim: 0 for an unlinked object, 1 for the root, 2 and up for child prims
- By default touches only trigger events in the touched child prim; child prims can [pass touches to the root](/functions/llPassTouches/) (see the [pass modes](/constants/groups/PassMode/))

Constant groups: [PassMode](/constants/groups/PassMode/) (3)

## Touch position

Each function takes the **index** of the detected touch.

- [Face](/functions/llDetectedTouchFace/): the index of the clicked face, or [`TOUCH_INVALID_FACE`](/constants/TOUCH_INVALID_FACE/)
- [Surface coordinates](/functions/llDetectedTouchST/) (s, t) and [texture coordinates](/functions/llDetectedTouchUV/) (u, v, affected by repeats and rotation), typically in [0.0, 1.0], or [`TOUCH_INVALID_TEXCOORD`](/constants/TOUCH_INVALID_TEXCOORD/)
- [Position](/functions/llDetectedTouchPos/) in region coordinates, or screen-space coordinates on a HUD
- [Surface normal](/functions/llDetectedTouchNormal/) and [binormal](/functions/llDetectedTouchBinormal/), which together give the tangent space
  - Position, normal and binormal return [`TOUCH_INVALID_VECTOR`](/constants/TOUCH_INVALID_VECTOR/) when the touch position is not valid

## Touch functions and events

- `event` [`touch_start`](/events/touch_start/) `(integer num_detected)`: Triggered when an avatar first touches the object. Passes num_detected, representing the number of touching agents.
- `event` [`touch`](/events/touch/) `(integer num_detected)`: Triggered continuously while an avatar touches the object. Passes num_detected, representing the number of touching agents.
- `event` [`touch_end`](/events/touch_end/) `(integer num_detected)`: Triggered when an avatar stops touching the object. Passes num_detected, representing the number of touching agents.
- `integer` [`llDetectedTouchFace`](/functions/llDetectedTouchFace/) `(integer index)`: Returns the integer index of the face clicked by the avatar in the touch event specified by index.
- `vector` [`llDetectedTouchST`](/functions/llDetectedTouchST/) `(integer index)`: Returns the surface coordinates (<s, t, 0.0>) where the prim was touched, specified by index. X and Y contain the horizontal (s) and vertical (t) face coordinates, typically in the interval [0.0, 1.0]. Returns TOUCH_INVALID_TEXCOORD if coordinates cannot be determined.
- `vector` [`llDetectedTouchUV`](/functions/llDetectedTouchUV/) `(integer index)`: Returns the texture coordinates (<u, v, 0.0>) where the prim was touched, specified by index. X and Y contain the horizontal (u) and vertical (v) texture coordinates, typically in the interval [0.0, 1.0] (affected by repeats and rotation). Returns TOUCH_INVALID_TEXCOORD if coordinates cannot be determined.
- `vector` [`llDetectedTouchPos`](/functions/llDetectedTouchPos/) `(integer index)`: Returns the vector position where the object was touched (specified by index) in region coordinates, or in screen-space coordinates if the object is attached as a HUD.
- `vector` [`llDetectedTouchNormal`](/functions/llDetectedTouchNormal/) `(integer index)`: Returns the surface normal vector (perpendicular to the surface) at the touched location specified by index. Can be used with llDetectedTouchBinormal to determine the tangent space.
- `vector` [`llDetectedTouchBinormal`](/functions/llDetectedTouchBinormal/) `(integer index)`: Returns the surface binormal vector (tangent to the surface, pointing along the positive T (V) direction of tangent space) at the touched location specified by index. Can be used with llDetectedTouchNormal to determine the tangent space.
- `integer` [`llDetectedLinkNumber`](/functions/llDetectedLinkNumber/) `(integer number)`: Returns the link number (integer) of the triggered event (touches and collisions only) specified by number. Returns 0 for non-linked objects, 1 for the root prim, and 2+ for child prims. Returns 0 if not supported by the event.
- `key` [`llDetectedKey`](/functions/llDetectedKey/) `(integer number)`: Returns the key (UUID) of the detected object or avatar specified by number, or NULL_KEY if number is not a valid index.
- `void` [`llPassTouches`](/functions/llPassTouches/) `(integer pass)`: Sets the pass-touches attribute. If pass is TRUE, touch events are passed from child prims to the root; if FALSE (default), they only trigger events in the affected child prim.
- `void` [`llSetClickAction`](/functions/llSetClickAction/) `(integer action)`: Sets the action (a CLICK_ACTION_* flag) performed when an avatar left-clicks the prim.
- `void` [`llSetTouchText`](/functions/llSetTouchText/) `(string text)`: Displays the string text instead of 'Touch' in the right-click context menu.

See also: [Touch](/categories/touch/), [LSL Touch Position (Second Life Wiki)](https://wiki.secondlife.com/wiki/LSL_Touch_Position), [Script library: touch detection (Second Life Wiki)](https://wiki.secondlife.com/wiki/CatTouchDetection)
   (planned: Recipe: buttons on one prim with touch positions)

## Click actions and touch text

- [`llSetClickAction`](/functions/llSetClickAction/) sets what a left-click on the prim does, with an **action** from the `CLICK_ACTION_*` [click actions](/constants/groups/ClickAction/)
  - Per prim through [`llSetLinkPrimitiveParamsFast`](/functions/llSetLinkPrimitiveParamsFast/) with [`PRIM_CLICK_ACTION`](/constants/PRIM_CLICK_ACTION/), followed by a `CLICK_ACTION_*` constant
- [`llSetTouchText`](/functions/llSetTouchText/) shows **text** instead of "Touch" in the right-click menu

Constant groups: [ClickAction](/constants/groups/ClickAction/) (11)

---

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