Experience

An experience groups scripts under one identity. An avatar accepts the experience once, and from then on its scripts can animate, teleport, attach to or take controls from that avatar without asking again, wherever the experience is allowed.

Scripts join an experience when they are compiled with it selected. Experiences also bring a shared key-value store and abilities that ordinary scripts do not have.

Experience scripts use the same events and permission flow as ordinary scripts: llRequestExperiencePermissions takes the place of the per-object prompt.

Concepts

Experience permissions
- Ask the avatar to accept the experience, or grant silently if they already have
- The answer arrives in experience_permissions or experience_permissions_denied
- Check whether an avatar is in the experience and it can run here; read granted permissions
Experience details and errors
- Read the experience a script belongs to
- Turn error codes into messages
Persistent key-value storage
- A store shared by all scripts in the experience, across objects and regions
- All calls are asynchronous; results arrive in dataserver
- Limits (Experience Tools):
  - Each key may be a maximum of 1011 bytes
  - Each value may be a maximum of 4095 bytes
  - Total stored data is restricted to 128 MiB
Abilities through an experience
- Seat an avatar on an object, attach temporary items, teleport the avatar and set an environment for that avatar alone
- llSitOnLink and the per-avatar environment functions require an experience

Functions and events

`void`	`llRequestExperiencePermissions(key agent, string name)`
`event`	`experience_permissions(key agent_id)`
`event`	`experience_permissions_denied(key agent_id, integer reason)`
`integer`	`llAgentInExperience(key agent)`
`list`	`llGetExperienceDetails(key experience_id)`
`key`	`llReadKeyValue(string k)`
`key`	`llUpdateKeyValue(string k, string v, integer checked, string original_value)`
`integer`	`llSitOnLink(key agent_id, integer link)`

Experience Tools

The archived wiki category for experience tools and the functions that use them.

Key-value store

Each call returns a query key; match it in dataserver to read the result.

Scripting Details

`void`	`llRequestExperiencePermissions(key agent, string name)` Requests permission from the specified agent to participate in the experience. These permissions are persistent and apply grid-wide across all scripts in the experience, automatically triggering experience_permissions or experience_permissions_denied.
`event`	`experience_permissions(key agent_id)` Triggered when the agent specified by agent_id approves an experience permissions request (interactively or automatically if previously approved).
`event`	`experience_permissions_denied(key agent_id, integer reason)` Triggered when the agent specified by agent_id denies experience permissions, or when permission is blocked for other reasons (specified by the error code reason).
`integer`	`llAgentInExperience(key agent)` Returns TRUE if the specified agent is in the experience and the experience can run in the current region/location; returns FALSE otherwise.
`integer`	`llGetPermissions()` Returns an integer bitfield representing the permissions (PERMISSION_*) currently granted to the script.
`list`	`llGetExperienceDetails(key experience_id)` Returns a list of details for the specified experience_id, formatted as [string experience_name, key owner_id, key experience_id, integer state, string state_message, key group_id].
`string`	`llGetExperienceErrorMessage(integer error)` Returns a text description of the specified experience error code, or a description of XP_ERROR_UNKNOWN_ERROR if the error is invalid.
`integer`	`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`	`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).
`integer`	`llReplaceAgentEnvironment(key agent_id, float transition, string environment)` Replaces the region and parcel environment seen by the specified agent_id as part of an experience, transitioning the settings over transition seconds. Passing NULL_KEY or an empty string for environment restores defaults.
`integer`	`llSetAgentEnvironment(key agent_id, float transition, list params)` Sets an individual agent's environmental settings using the attributes in params over a duration of transition seconds. Must be used as part of an experience; passing an empty list removes overrides.
`void`	`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.

Additional

Key-value store calls — all return a query handle for dataserver
- llCreateKeyValue — create a key-value pair
- llReadKeyValue — read a value
- llUpdateKeyValue — update a value; a checked update can fail with XP_ERROR_RETRY_UPDATE
- llDeleteKeyValue — delete a pair
- llKeysKeyValue — list keys from an index
- llKeyCountKeyValue — count keys
- llDataSizeKeyValue — used and total storage
llGetExperienceErrorMessage — error codes (all errors)
- XP_ERROR_NONE — no error was detected
- XP_ERROR_NOT_PERMITTED — not allowed to run for this agent, or permissions were denied
- XP_ERROR_KEY_NOT_FOUND — requested key does not exist
- XP_ERROR_QUOTA_EXCEEDED — a write failed because the data quota is met
llGetPermissions — permissions granted (ScriptPermission)
- PERMISSION_TELEPORT — teleport the agent with llTeleportAgent
- PERMISSION_ATTACH — attach to the agent, also required by llAttachToAvatarTemp
- PERMISSION_TRIGGER_ANIMATION — start or stop animations
- PERMISSION_TAKE_CONTROLS — intercept the agent’s controls

Constant groups

Constant groups ScriptPermission 13 ExperienceError 19

See also Feature Avatars Feature Environments SL Wiki Experience Tools SL Wiki LSL ExperiencePlanned Guide: creating an experience and compiling scripts to it