# Events

> The event model: states, event handlers, changes, detection and sensors.

LSL scripts are event driven. The script does nothing until something happens: a touch, a message, a timer, a collision. Then the matching event handler in the current state runs to completion.

Events wait in a queue while a handler runs. Keep handlers short; long work blocks every other event in the script.

There is no runtime subscription to events: a state receives the events it has handlers for. Think of each [state](/controls/state/) as a set of subscriptions; changing state is how a script subscribes and unsubscribes.

## Concepts

- States
  - Every script starts in the [`default`](/controls/default/) state, and each state has its own handlers
  - Changing state fires [`state_exit`](/events/state_exit/) and then [`state_entry`](/events/state_entry/), and removes listeners and sensors from the old state
  - To stop receiving an event, change to a state without that handler, or remove its source with [`llListenRemove`](/functions/llListenRemove/), [`llSensorRemove`](/functions/llSensorRemove/) or [`llSetTimerEvent(0.0)`](/functions/llSetTimerEvent/)
  - Resetting, running state and memory of scripts are covered under [Scripts](/features/script/)
- Timers: each script has one timer, firing the [`timer`](/events/timer/) event. Timers, sleeping and clocks are covered under [Time](/features/time/)
- [Changes](/events/changed/) to the object: inventory, links, owner, region, teleports, shape and more
  - Test the flags with the bitwise AND operator (&)
- Detection
  - Touch, collision, sensor and damage events can report several detections at once
  - The event's number parameter says how many; `llDetected*` functions such as [`llDetectedKey`](/functions/llDetectedKey/) read each one by index, and only inside that event
- [Sensors](/functions/llSensor/) scan a cone around the object for avatars or objects, [once or repeatedly](/functions/llSensorRepeat/)
  - The nearest results arrive in [`sensor`](/events/sensor/), or [`no_sensor`](/events/no_sensor/) when nothing is found

## Functions and events

- `event` [`state_entry`](/events/state_entry/) `()`
- `event` [`state_exit`](/events/state_exit/) `()`
- `event` [`on_rez`](/events/on_rez/) `(integer start_param)`
- `event` [`changed`](/events/changed/) `(integer changes)`
- `void` [`llSensor`](/functions/llSensor/) `(string name, key id, integer type, float radius, float arc)`
- `event` [`sensor`](/events/sensor/) `(integer num_detected)`
- `event` [`no_sensor`](/events/no_sensor/) `()`
- `key` [`llDetectedKey`](/functions/llDetectedKey/) `(integer number)`

## [Event Order](https://wiki.secondlife.com/wiki/Event_Order)

Which events are called for different actions, such as attaching, rezzing, resetting or changing state, and in which order.

## [Events by feature](/events/)

Most events belong to a feature. Start from the event index, or from the feature you are working on: [input](/features/input/), [communications](/features/communications/), [physics](/features/physics/).

## Scripting Details

- `event` [`state_entry`](/events/state_entry/) `()`: Triggered immediately whenever a new state is entered (including at script start). It is always the first event handled.
- `event` [`state_exit`](/events/state_exit/) `()`: Triggered when the state command is used to transition out of the current state. Handled before entering the new state's state_entry.
- `event` [`on_rez`](/events/on_rez/) `(integer start_param)`: Triggered when the object is rezzed into the world (by a script or user). Passes start_param from the rezzing call (or 0 if rezzed from inventory). Also triggers on attachments during login or when attached from inventory.
- `event` [`changed`](/events/changed/) `(integer changes)`: Triggered when various properties of the object change. The parameter changes is a bitfield of CHANGED_* flags.
- `void` [`llSensor`](/functions/llSensor/) `(string name, key id, integer type, float radius, float arc)`: Performs a single scan from the prim's forward vector for name and id of type within radius meters and arc radians. Results trigger a sensor or no_sensor event. Passing empty filters (blank name, 0 type, or NULL_KEY id) disables that filter.
- `void` [`llSensorRepeat`](/functions/llSensorRepeat/) `(string name, key id, integer type, float radius, float arc, float rate)`: Sets up a repeating periodic scan every rate seconds for name and id of type within radius meters and arc radians of the forward vector. Results trigger sensor or no_sensor events.
- `void` [`llSensorRemove`](/functions/llSensorRemove/) `()`: Removes the periodic sensor previously configured by llSensorRepeat.
- `event` [`sensor`](/events/sensor/) `(integer num_detected)`: Triggered when objects matching constraints of llSensor or llSensorRepeat are successfully detected. Passes num_detected, representing the number of detected targets.
- `event` [`no_sensor`](/events/no_sensor/) `()`: Triggered when active sensors (from llSensor or llSensorRepeat) complete a scan without finding any matching targets.

## Additional

- [Time](/features/time/) — timers, delays and clocks
  - [`llSetTimerEvent`](/functions/llSetTimerEvent/) — 0.0 stops further [`timer`](/events/timer/) events
  - [`llSleep`](/functions/llSleep/) — the script is inactive during this time
  - [`llMinEventDelay`](/functions/llMinEventDelay/) — minimum delay between events being handled
  - [`llGetTime`](/functions/llGetTime/), [`llResetTime`](/functions/llResetTime/), [`llGetAndResetTime`](/functions/llGetAndResetTime/) — elapsed script time
  - [`llGetUnixTime`](/functions/llGetUnixTime/), [`llGetTimestamp`](/functions/llGetTimestamp/), [`llGetDate`](/functions/llGetDate/), [`llGetWallclock`](/functions/llGetWallclock/), [`llGetGMTclock`](/functions/llGetGMTclock/) — real-world clocks
- [Scripts](/features/script/) — resetting and controlling scripts
  - [`llResetScript`](/functions/llResetScript/), [`llResetOtherScript`](/functions/llResetOtherScript/) — reset this or another script
  - [`llSetScriptState`](/functions/llSetScriptState/), [`llGetScriptState`](/functions/llGetScriptState/) — stop, start and check other scripts in the prim
  - [`llGetScriptName`](/functions/llGetScriptName/) — the script's own name
- [`changed`](/events/changed/) — the changes bitfield ([all flags](/constants/groups/ChangeType/))
  - [`CHANGED_INVENTORY`](/constants/CHANGED_INVENTORY/) — prim inventory changed by someone with modify rights
  - [`CHANGED_LINK`](/constants/CHANGED_LINK/) — number of prims or seated avatars changed
  - [`CHANGED_OWNER`](/constants/CHANGED_OWNER/) — the object changed owners
  - [`CHANGED_REGION`](/constants/CHANGED_REGION/) — the object changed regions
  - [`CHANGED_TELEPORT`](/constants/CHANGED_TELEPORT/) — the avatar this object is attached to teleported
- Detected functions — [`llDetectedKey`](/functions/llDetectedKey/), [`llDetectedName`](/functions/llDetectedName/), [`llDetectedOwner`](/functions/llDetectedOwner/), [`llDetectedGroup`](/functions/llDetectedGroup/), [`llDetectedPos`](/functions/llDetectedPos/), [`llDetectedRot`](/functions/llDetectedRot/), [`llDetectedVel`](/functions/llDetectedVel/), [`llDetectedLinkNumber`](/functions/llDetectedLinkNumber/) (touches and collisions), [`llDetectedGrab`](/functions/llDetectedGrab/) (touches only)
  - [`llDetectedType`](/functions/llDetectedType/) — bitfield of types ([`DetectType`](/constants/groups/DetectType/))
  - [`AGENT`](/constants/AGENT/) — an avatar
  - [`ACTIVE`](/constants/ACTIVE/) — physical objects and agents
  - [`PASSIVE`](/constants/PASSIVE/) — non-physical objects
  - [`SCRIPTED`](/constants/SCRIPTED/) — has at least one active script
- Common event sources
  - [`touch_start`](/events/touch_start/), [`collision_start`](/events/collision_start/), [`control`](/events/control/) — [input](/features/input/) and [physics](/features/physics/)
  - [`listen`](/events/listen/), [`link_message`](/events/link_message/), [`http_request`](/events/http_request/) — [communications](/features/communications/)
  - [`dataserver`](/events/dataserver/) — requested data returned to the script
  - [`run_time_permissions`](/events/run_time_permissions/) — an agent granted or denied permissions
- Script health (see [Scripts](/features/script/))
  - [`llGetFreeMemory`](/functions/llGetFreeMemory/), [`llGetUsedMemory`](/functions/llGetUsedMemory/) — free and used script memory
  - [`llScriptProfiler`](/functions/llScriptProfiler/) — [`PROFILE_SCRIPT_MEMORY`](/constants/PROFILE_SCRIPT_MEMORY/) tracks peak memory while active
  - [`llGetSimStats`](/functions/llGetSimStats/) — region statistics such as [`SIM_STAT_SCRIPT_MS`](/constants/SIM_STAT_SCRIPT_MS/) (script time per frame) and [`SIM_STAT_SCRIPT_EPS`](/constants/SIM_STAT_SCRIPT_EPS/) (script events per second)
  - [`llGetRegionFPS`](/functions/llGetRegionFPS/), [`llGetRegionTimeDilation`](/functions/llGetRegionTimeDilation/) — region performance
  - [`llGetEnergy`](/functions/llGetEnergy/) — remaining physics energy of the object
  - [`llScriptDanger`](/functions/llScriptDanger/) — whether a position is over public or sandbox land, or land that restricts building or outside scripts

## Constant groups

Constant groups: [ChangeType](/constants/groups/ChangeType/) (13), [DetectType](/constants/groups/DetectType/) (7), [ScriptProfileMode](/constants/groups/ScriptProfileMode/) (2), [SimulatorStat](/constants/groups/SimulatorStat/) (27)

## Related

See also: [default](/controls/default/), [state](/controls/state/), [LSL State (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_State)
   (planned: Guide: switching event handlers with states)

See also: [Scripts](/features/script/), [Time](/features/time/), [Detected](/categories/detected/), [Sensor](/categories/sensor/), [Script](/categories/script/), [Time](/categories/time/)

See also: [All events](/events/), [Input](/features/input/), [Communications](/features/communications/), [Physics](/features/physics/), [LSL Events (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Events), [Event Order (Second Life Wiki)](https://wiki.secondlife.com/wiki/Event_Order)

## Related features

- [Input](/features/input/)
- [Communications](/features/communications/)
- [Physics](/features/physics/)

## Categories

- [Detected](/categories/detected/)
- [Sensor](/categories/sensor/)

---

From lsl.dev: https://lsl.dev/features/events/