# Avatars

> Avatars in scripting: identifying agents, permissions, attachments, sitting, animations and teleports.

Scripts never own an avatar. They find avatars nearby or in the region, read public information about them, and act on them only with a permission the avatar has granted.

Most avatar control follows the same pattern: call [`llRequestPermissions`](/functions/llRequestPermissions/), wait for [`run_time_permissions`](/events/run_time_permissions/), then use the functions that permission unlocks. Attachments and sitting avatars grant some permissions automatically.

## Concepts

- Avatars are identified by key
  - [List the avatars](/functions/llGetAgentList/) on the parcel or region, or [count them](/functions/llGetRegionAgentCount/)
  - Names come in two forms: the legacy/[user name](/functions/llGetUsername/) and the changeable [display name](/functions/llGetDisplayName/)
  - Some lookups are asynchronous and answer in the [`dataserver`](/events/dataserver/) event
- Permissions are granted per script, to one avatar at a time
  - Request only what you need; granting is remembered until the script resets or another avatar grants
  - [Check what is granted](/functions/llGetPermissions/) and [by whom](/functions/llGetPermissionsKey/)
- Objects can [give inventory](/functions/llGiveInventory/) items or [folders](/functions/llGiveInventoryList/) to an avatar
  - The receiver may need to accept the offer, and no-copy items leave the object's inventory
- An [attachment](#attachments) is an object worn on an avatar at an attach point
  - Scripts can [attach](/functions/llAttachToAvatar/) with [`PERMISSION_ATTACH`](/constants/PERMISSION_ATTACH/), [detach themselves](/functions/llDetachFromAvatar/), and [inspect what an avatar is wearing](/functions/llGetAttachedList/)
  - HUDs are attachments on the HUD points
- A [sit target](/functions/llSitTarget/) fixes where and how an avatar sits on a prim
  - Sitting avatars become part of the linkset, after the prims, so the link numbers after the last prim are avatars
  - [Sit flags](/functions/llSetLinkSitFlags/) control unsitting, collisions and damage while seated
- Animations
  - With [`PERMISSION_TRIGGER_ANIMATION`](/constants/PERMISSION_TRIGGER_ANIMATION/) a script can [start](/functions/llStartAnimation/) and [stop](/functions/llStopAnimation/) animations on the avatar
  - With [`PERMISSION_OVERRIDE_ANIMATIONS`](/constants/PERMISSION_OVERRIDE_ANIMATIONS/) it can [replace the default animation](/functions/llSetAnimationOverride/) for each animation state (standing, walking, flying and so on)
- Teleporting and moving
  - [`llTeleportAgent`](/functions/llTeleportAgent/) needs [`PERMISSION_TELEPORT`](/constants/PERMISSION_TELEPORT/) (or an [experience](/features/experience/))
  - Landowners can [send avatars home](/functions/llTeleportAgentHome/) or eject them (see [land](/features/land/))
  - Avatars can also be [turned](/functions/llSetAgentRot/) or [pushed](/functions/llPushObject/)

## Functions and events

- `list` [`llGetAgentList`](/functions/llGetAgentList/) `(integer scope, list options)`
- `integer` [`llGetAgentInfo`](/functions/llGetAgentInfo/) `(key id)`
- `void` [`llRequestPermissions`](/functions/llRequestPermissions/) `(key agent, integer permissions)`
- `event` [`run_time_permissions`](/events/run_time_permissions/) `(integer perm)`
- `void` [`llGiveInventory`](/functions/llGiveInventory/) `(key target, string item)`
- `void` [`llAttachToAvatar`](/functions/llAttachToAvatar/) `(integer attach_point)`
- `event` [`attach`](/events/attach/) `(key avatar)`
- `void` [`llSitTarget`](/functions/llSitTarget/) `(vector offset, rotation rot)`
- `event` [`changed`](/events/changed/) `(integer changes)`
- `void` [`llStartAnimation`](/functions/llStartAnimation/) `(string anim)`
- `void` [`llSetAnimationOverride`](/functions/llSetAnimationOverride/) `(string anim_state, string anim)`
- `void` [`llTeleportAgent`](/functions/llTeleportAgent/) `(key agent, string landmark, vector position, vector look_at)`

## [Attachments](/categories/attachments/)

An object worn at an attach point gets an [`attach`](/events/attach/) event; [`llGetAttached`](/functions/llGetAttached/) tells which point it is on.

## [Sitting](/categories/sit/)

Sitting and standing change the linkset, reported by [`changed`](/events/changed/) with [`CHANGED_LINK`](/constants/CHANGED_LINK/); [`llAvatarOnSitTarget`](/functions/llAvatarOnSitTarget/) tells who sat.

## Scripting Details

### Find and identify avatars

- `list` [`llGetAgentList`](/functions/llGetAgentList/) `(integer scope, list options)`: Requests a list of avatar UUID keys for agents currently in the region, limited by scope. Returns a list of keys or a list containing an error message string.
- `integer` [`llGetRegionAgentCount`](/functions/llGetRegionAgentCount/) `()`: Returns an integer representing the current number of avatars in the region.
- `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.).
- `vector` [`llGetAgentSize`](/functions/llGetAgentSize/) `(key avatar)`: Returns a vector representing the estimated bounding box size of the specified avatar, or ZERO_VECTOR if they are not in the same region.
- `string` [`llGetAgentLanguage`](/functions/llGetAgentLanguage/) `(key avatar)`: Returns a string representing the language code of the preferred interface language set by the avatar.
- `string` [`llGetDisplayName`](/functions/llGetDisplayName/) `(key id)`: Returns the display name string of the avatar specified by id if they are in the region or cached; returns an empty string otherwise (use llRequestDisplayName if the avatar is absent).
- `string` [`llGetUsername`](/functions/llGetUsername/) `(key id)`: Returns a string representing the unique username of the avatar specified by id if they are connected to the region or cached; returns an empty string otherwise (use llRequestUsername if the avatar is absent).
- `string` [`llKey2Name`](/functions/llKey2Name/) `(key id)`: Returns a string containing the name of the prim or avatar specified by id. The target must be a valid, rezzed entity in the current region, otherwise an empty string is returned. Avatars return their legacy name.
- `key` [`llName2Key`](/functions/llName2Key/) `(string name)`: Requests the key (UUID) of the avatar name in the current region. Returns NULL_KEY if no matching agent is present. Formats are 'First Last' or 'first.last' (assumes 'Resident' if last name is omitted; case-insensitive).
- `key` [`llRequestAgentData`](/functions/llRequestAgentData/) `(key id, integer data)`: Asynchronously requests the specified data category (DATA_*) about the agent id. Triggers a dataserver event with the results and returns a key query handle.
- `key` [`llRequestDisplayName`](/functions/llRequestDisplayName/) `(key id)`: Asynchronously requests the display name of the agent specified by id, triggering a dataserver event with the results. The agent does not need to be online or in the region. Returns a key query handle.
- `key` [`llRequestUsername`](/functions/llRequestUsername/) `(key id)`: Asynchronously requests the unique single-word username of the agent identified by id, triggering a dataserver event. The agent does not need to be online or in the region. Returns a key query handle.
- `key` [`llRequestUserKey`](/functions/llRequestUserKey/) `(string username)`: Asynchronously requests the Agent ID key (UUID) for the agent specified by their current or historical username, returning NULL_KEY if not found. Returns a key query handle for the dataserver event.
- `key` [`llGetOwner`](/functions/llGetOwner/) `()`: Returns the key (UUID) of the object's current owner.
- `integer` [`llIsFriend`](/functions/llIsFriend/) `(key agent_id)`: Returns TRUE if agent_id and the owner of the script are friends, and FALSE otherwise.
- `integer` [`llSameGroup`](/functions/llSameGroup/) `(key uuid)`: Returns TRUE if the agent or object specified by uuid is in the same region (simulator) and shares the same active group as the prim containing the script; returns FALSE otherwise.
- `list` [`llGetVisualParams`](/functions/llGetVisualParams/) `(key agentid, list params)`: Returns a list containing the values of the visual parameters requested in params for the agent specified by agentid.
- `event` [`dataserver`](/events/dataserver/) `(key queryid, string data)`: Triggered when requested data is returned to the script (e.g., from llRequestAgentData, llRequestInventoryData, or llGetNotecardLine).

### Permissions

- `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).
- `integer` [`llGetPermissions`](/functions/llGetPermissions/) `()`: Returns an integer bitfield representing the permissions (PERMISSION_*) currently granted to the script.
- `key` [`llGetPermissionsKey`](/functions/llGetPermissionsKey/) `()`: Returns the key (UUID) of the avatar that last granted or declined permissions to the script, or NULL_KEY if the permissions request was ignored or cancelled.

### Giving items

- `void` [`llGiveInventory`](/functions/llGiveInventory/) `(key target, string item)`: Gives the specified inventory item to the target, as permitted by the permissions system. The target can be any agent or an object located in the same region.
- `void` [`llGiveInventoryList`](/functions/llGiveInventoryList/) `(key target, string folder, list items)`: Gives the list of inventory items to target as a new folder named folder. If target is an object, the items are passed directly into its inventory and no folder is created. The target must be an agent or an object in the same region.
- `integer` [`llGiveAgentInventory`](/functions/llGiveAgentInventory/) `(key agent, string folder, list items, list options)`: Gives the specified inventory items to the agent as a new folder named folder, as permitted by the permissions system. Customizes the transfer using options.

### Wearing objects

- `void` [`llAttachToAvatar`](/functions/llAttachToAvatar/) `(integer attach_point)`: Attaches the object to the avatar who has granted the PERMISSION_ATTACH permission. Takes the object into the user's inventory and attaches it at attach_point.
- `void` [`llAttachToAvatarTemp`](/functions/llAttachToAvatarTemp/) `(integer attach_point)`: Attaches the object temporarily to an avatar who has granted the PERMISSION_ATTACH permission. No permanent inventory is created, and the object disappears on detach or disconnect. Can be used on non-owners (changing ownership to the wearer).
- `void` [`llDetachFromAvatar`](/functions/llDetachFromAvatar/) `()`: Detaches the object containing the script from the avatar. Requires the PERMISSION_ATTACH runtime permission (automatically granted to attached objects). Note that the detached object is completely removed from the region and not dropped on the ground.
- `integer` [`llGetAttached`](/functions/llGetAttached/) `()`: Returns the integer attachment point (an ATTACH_* constant) that the object is attached to, or 0 if it is unattached or pending detachment.
- `list` [`llGetAttachedList`](/functions/llGetAttachedList/) `(key avatar)`: Returns a list of object keys (UUIDs) worn by the specified avatar, in the order they were attached. HUDs are not included because they are neither public nor visible. Returns a list containing an error message string on failure.
- `list` [`llGetAttachedListFiltered`](/functions/llGetAttachedListFiltered/) `(key avatar, list options)`: Returns a list of object keys (UUIDs) worn by the specified avatar, in the order they were attached, filtered by options. Returns a list containing an error message string on failure.
- `event` [`attach`](/events/attach/) `(key avatar)`: Triggered whenever the object is attached to or detached from an avatar. Passes the UUID key of the avatar if attached, or NULL_KEY if detached.
- `vector` [`llWorldPosToHUD`](/functions/llWorldPosToHUD/) `(vector world_pos)`: Returns the local position vector that places the center of the HUD object directly over the world coordinate world_pos as viewed by the current camera. Requires the PERMISSION_TRACK_CAMERA runtime permission.

### Sit targets

- `void` [`llSitTarget`](/functions/llSitTarget/) `(vector offset, rotation rot)`: Sets the sit target position (offset) and rotation (rot) relative to the prim's position and orientation. Clears the sit target if offset is ZERO_VECTOR.
- `void` [`llLinkSitTarget`](/functions/llLinkSitTarget/) `(integer link, vector offset, rotation rot)`: Sets the sit target position (offset) and orientation (rot) for the linked prim link, relative to the prim's own position and rotation. Clear by setting offset to <0.0, 0.0, 0.0>.
- `key` [`llAvatarOnSitTarget`](/functions/llAvatarOnSitTarget/) `()`: Returns the UUID of the avatar seated on the prim's sit target (defined via llSitTarget), or NULL_KEY if no avatar is sitting there or the prim lacks a sit target.
- `key` [`llAvatarOnLinkSitTarget`](/functions/llAvatarOnLinkSitTarget/) `(integer link)`: Returns the UUID of the avatar seated on the specified link's sit target, or NULL_KEY if no avatar is sitting there.
- `void` [`llSetSitText`](/functions/llSetSitText/) `(string text)`: Displays the string text instead of 'Sit' (or 'Sit Here') in the viewer's right-click context menu.
- `integer` [`llSitOnLink`](/functions/llSitOnLink/) `(key agent_id, integer link)`: Forces the avatar specified by agent_id (who must be participating in the experience) to sit on the sit target of the prim indicated by link. If occupied, searches down the linkset for an available sit target. Returns an integer.
- `void` [`llUnSit`](/functions/llUnSit/) `(key id)`: Forces the agent specified by id to stand up if they are sitting on the object containing the script, or are currently over land owned by the object's owner.
- `void` [`llSetLinkSitFlags`](/functions/llSetLinkSitFlags/) `(integer link, integer flags)`: Sets the sit target flags for the linked prim link inside the linkset.
- `integer` [`llGetLinkSitFlags`](/functions/llGetLinkSitFlags/) `(integer link)`: Returns an integer representing the active sit flags currently set on the linked prim specified by link.
- `event` [`changed`](/events/changed/) `(integer changes)`: Triggered when various properties of the object change. The parameter changes is a bitfield of CHANGED_* flags.

### Animations

- `void` [`llStartAnimation`](/functions/llStartAnimation/) `(string anim)`: Starts the animation anim (inventory or built-in) on the avatar who granted the script the PERMISSION_TRIGGER_ANIMATION permission (automatically granted for attached or sat-on objects).
- `void` [`llStopAnimation`](/functions/llStopAnimation/) `(string anim)`: Stops the specified animation anim (inventory, built-in, or UUID) on the avatar who granted the script the PERMISSION_TRIGGER_ANIMATION permission (automatically granted for attached or sat-on objects).
- `string` [`llGetAnimation`](/functions/llGetAnimation/) `(key avatar)`: Returns a string representing the name of the currently playing locomotion animation for the specified avatar.
- `list` [`llGetAnimationList`](/functions/llGetAnimationList/) `(key avatar)`: Returns a list of keys (UUIDs) representing all active animations currently playing on the specified avatar.
- `void` [`llSetAnimationOverride`](/functions/llSetAnimationOverride/) `(string anim_state, string anim)`: Overrides the default animation for anim_state with anim (which must be in the object's inventory or a built-in animation). Requires the PERMISSION_OVERRIDE_ANIMATIONS permission.
- `string` [`llGetAnimationOverride`](/functions/llGetAnimationOverride/) `(string anim_state)`: Returns a string representing the name of the animation currently overriding the specified anim_state. Requires the PERMISSION_OVERRIDE_ANIMATIONS or PERMISSION_TRIGGER_ANIMATION runtime permission.
- `void` [`llResetAnimationOverride`](/functions/llResetAnimationOverride/) `(string anim_state)`: Resets the animation override for anim_state to its default value (use 'ALL' to reset all states). Requires the PERMISSION_OVERRIDE_ANIMATIONS permission.

### Teleporting and moving

- `void` [`llTeleportAgent`](/functions/llTeleportAgent/) `(key agent, string landmark, vector position, vector look_at)`: Teleports the owning agent (who must grant PERMISSION_TELEPORT) to a landmark in the object's inventory. If landmark is empty, teleports them to position within the current region. Upon arrival, the agent is turned to face look_at. Can only teleport the owner.
- `void` [`llTeleportAgentGlobalCoords`](/functions/llTeleportAgentGlobalCoords/) `(key agent, vector global_coordinates, vector region_coordinates, vector look_at)`: Teleports the owning agent (who must grant PERMISSION_TELEPORT) to region_coordinates within a target region specified by global_coordinates. Upon landing, the agent faces the direction look_at. Can only teleport the owner.
- `void` [`llTeleportAgentHome`](/functions/llTeleportAgentHome/) `(key avatar)`: Teleports the avatar (who must be standing on land owned by the script owner) directly to their designated home location without warning (similar to a God Summons).
- `void` [`llMapDestination`](/functions/llMapDestination/) `(string simname, vector pos, vector look_at)`: Opens the world map for the avatar touching or wearing the object, centered on simname with pos highlighted. Only works for attached scripts or during touch events. Note: look_at currently has no effect.
- `void` [`llSetAgentRot`](/functions/llSetAgentRot/) `(rotation rot, integer flags)`: Sets the rotation of the avatar to rot, controlled by flags.
- `void` [`llPushObject`](/functions/llPushObject/) `(key target, vector impulse, vector ang_impulse, integer is_local)`: Applies physical impulse (force) and ang_impulse (rotational force) to the specified target avatar or object.

## Additional

- [`llGetAgentList`](/functions/llGetAgentList/) — scope of the list
  - [`AGENT_LIST_PARCEL`](/constants/AGENT_LIST_PARCEL/) — agents on the same parcel as the script
  - [`AGENT_LIST_PARCEL_OWNER`](/constants/AGENT_LIST_PARCEL_OWNER/) — agents on any parcel in the region with the same owner as this parcel
  - [`AGENT_LIST_REGION`](/constants/AGENT_LIST_REGION/) — agents anywhere in the region
- [`llGetAgentInfo`](/functions/llGetAgentInfo/) — bit flags describing the avatar, for example
  - [`AGENT_SITTING`](/constants/AGENT_SITTING/) — the avatar is sitting
  - [`AGENT_FLYING`](/constants/AGENT_FLYING/) — flying or hovering
  - [`AGENT_AUTOMATED`](/constants/AGENT_AUTOMATED/) — registered with Linden Lab as an automated agent (bot)
- [`llRequestAgentData`](/functions/llRequestAgentData/) — answers in [`dataserver`](/events/dataserver/)
  - [`DATA_ONLINE`](/constants/DATA_ONLINE/) — whether the agent is online
  - [`DATA_NAME`](/constants/DATA_NAME/) — the legacy name
  - [`DATA_BORN`](/constants/DATA_BORN/) — account creation date
  - [`DATA_PAYINFO`](/constants/DATA_PAYINFO/) — payment status, a mask of [`PAYMENT_INFO_ON_FILE`](/constants/PAYMENT_INFO_ON_FILE/) and [`PAYMENT_INFO_USED`](/constants/PAYMENT_INFO_USED/)
- [`llRequestPermissions`](/functions/llRequestPermissions/) — the avatar permissions
  - [`PERMISSION_ATTACH`](/constants/PERMISSION_ATTACH/) — attach to or detach from the agent
  - [`PERMISSION_TRIGGER_ANIMATION`](/constants/PERMISSION_TRIGGER_ANIMATION/) — start or stop animations
  - [`PERMISSION_OVERRIDE_ANIMATIONS`](/constants/PERMISSION_OVERRIDE_ANIMATIONS/) — override default animations
  - [`PERMISSION_TELEPORT`](/constants/PERMISSION_TELEPORT/) — teleport the agent with `llTeleportAgent`
  - [`PERMISSION_TAKE_CONTROLS`](/constants/PERMISSION_TAKE_CONTROLS/) and [`PERMISSION_CONTROL_CAMERA`](/constants/PERMISSION_CONTROL_CAMERA/) — see [input](/features/input/) and [camera](/features/camera/)
- [`llGiveAgentInventory`](/functions/llGiveAgentInventory/) — options for the transfer
  - [`TRANSFER_DEST`](/constants/TRANSFER_DEST/) — destination root folder
  - [`TRANSFER_FLAGS`](/constants/TRANSFER_FLAGS/) — flags controlling the transfer
- [`llGetAttachedListFiltered`](/functions/llGetAttachedListFiltered/) — filter options
  - [`FILTER_INCLUDE`](/constants/FILTER_INCLUDE/) — include a specific attachment point
  - [`FILTER_FLAGS`](/constants/FILTER_FLAGS/) with [`FILTER_FLAG_HUDS`](/constants/FILTER_FLAG_HUDS/) — include HUDs with matching experiences
- [`llSetLinkSitFlags`](/functions/llSetLinkSitFlags/) — sit flags
  - [`SIT_FLAG_ALLOW_UNSIT`](/constants/SIT_FLAG_ALLOW_UNSIT/) — an avatar seated by a script may stand up manually
  - [`SIT_FLAG_SCRIPTED_ONLY`](/constants/SIT_FLAG_SCRIPTED_ONLY/) — only scripts can seat avatars here
  - [`SIT_FLAG_NO_COLLIDE`](/constants/SIT_FLAG_NO_COLLIDE/) — no collision volume while seated
  - [`SIT_FLAG_NO_DAMAGE`](/constants/SIT_FLAG_NO_DAMAGE/) — damage is not passed to the seated avatar
  - [`SIT_FLAG_SIT_TARGET`](/constants/SIT_FLAG_SIT_TARGET/) — read-only, the prim has an active sit target
- [`llSitOnLink`](/functions/llSitOnLink/) — returns a sit result, such as [`SIT_OK`](/constants/SIT_OK/) or [`SIT_NO_SIT_TARGET`](/constants/SIT_NO_SIT_TARGET/)

## Reference

Constant groups: [AgentInfo](/constants/groups/AgentInfo/) (16), [AgentData](/constants/groups/AgentData/) (6), [AgentDataPaymentInfo](/constants/groups/AgentDataPaymentInfo/) (2), [AgentListScope](/constants/groups/AgentListScope/) (3), [ScriptPermission](/constants/groups/ScriptPermission/) (13), [GiveAgentInventoryParam](/constants/groups/GiveAgentInventoryParam/) (2), [AttachPoint](/constants/groups/AttachPoint/) (56), [AttachedListFilterParam](/constants/groups/AttachedListFilterParam/) (2), [AttachedListFilterFlag](/constants/groups/AttachedListFilterFlag/) (1), [SitFlag](/constants/groups/SitFlag/) (5), [SitError](/constants/groups/SitError/) (8)

## Related

See also: [Permissions](/categories/permissions/), [LSL Permissions (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Permissions), [Inventory: giving items](/features/inventory/), [Avatar Inventory](/categories/avatar_inventory/), [Attachments](/categories/attachments/), [LSL Attachment (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Attachment), [Sit](/categories/sit/), [LSL Sit (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Sit), [Avatar Animation](/categories/avatar_animation/), [LSL Animation (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Animation), [Teleport](/categories/teleport/), [Parcels & Regions](/features/land/)

## Related features

- [Camera](/features/camera/)
- [Input](/features/input/)
- [Animesh](/features/animesh/)
- [Experience](/features/experience/)

## Categories

- [Avatar Target](/categories/avatar/)
- [Avatar Animation](/categories/avatar_animation/)
- [Attachments](/categories/attachments/)
- [Sit](/categories/sit/)
- [Teleport](/categories/teleport/)
- [Permissions](/categories/permissions/)

## On the Second Life Wiki

- [LSL Avatar](https://wiki.secondlife.com/wiki/Category:LSL_Avatar)

---

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