Difference between revisions of "LlReplaceEnvironment"

From Second Life Wiki
Jump to navigation Jump to search
(Clarified that overrides from llSetEnvironment are preserved after llReplaceEnvironment adds a new environement)
(Added note about asynchronous behavior)
Line 28: Line 28:
* An environment set locally on the viewer will override any environment set from this function.
* An environment set locally on the viewer will override any environment set from this function.
* A parameter override set by [[llSetEnvironment]] will be preserved after the environment is replaced by this function.  Call [[llSetEnvironment]] with an empty list parameter to clear any straggling overrides.
* A parameter override set by [[llSetEnvironment]] will be preserved after the environment is replaced by this function.  Call [[llSetEnvironment]] with an empty list parameter to clear any straggling overrides.
* The environment specified by this function is applied asynchronously, as the simulator must download the environment asset before applying it. This means that [[llGetEnvironment]] will not immediately reflect the new environment's parameters, although the delay is typically quite small.
* If a UUID is passed as the environment parameter and that UUID does not specify an environment setting or one can not be constructed, the function will return success (1) but will post a message to the debug channel.  
* If a UUID is passed as the environment parameter and that UUID does not specify an environment setting or one can not be constructed, the function will return success (1) but will post a message to the debug channel.  
|examples=
|examples=

Revision as of 14:44, 8 August 2022

Summary

Function: Integer llReplaceEnvironment( vector position, string environment, integer track_no, integer day_length, integer day_offset );

The llReplaceEnvironment function replaces the environment in a parcel or a region. Either for a single elevation track or the entire environment. The owner of the script must have permission to edit the environment on the destination parcel, or be an estate manage in the case of an entire region. In most cases errors are reported as a return value from the function (see table below). However, issues with the environment assets may be reported in the debug chat.
Returns an Integer

• vector position The position in the region of the parcel that will receive the new environment. To change the entire region use <-1, -1, -1>. The z component of the vector is ignored.
• string environment The name of an environmental setting in the object's inventory or the asset ID for an environment. NULL_KEY or empty string to remove the environment.
• integer track_no The elevation zone to change. 0 for water, 1 for ground level, 2 for sky 1000m, 3 for sky 2000m, 4 for sky 3000m. -1 to change all tracks.
• integer day_length The length in seconds for the day cycle. -1 to leave unchanged.
• integer day_offset The offset in seconds from UTC. -1 to leave unchanged.

Return Values
Value Constant Description
1 The parcel or region will attempt to change the applied environment.
ENV_NO_ENVIRONMENT -3 The environment inventory object could not be found.
ENV_THROTTLE -8 The scripts have exceeded the throttle. Wait and retry the request.
ENV_NO_PERMISSIONS -9 The script does not have permission to change the environment at the selected location.
OR
there was an attempt to remove altitude track 0 or 1 (in this case a message will also be chatted to the debug channel).

Caveats

  • An environment set locally on the viewer will override any environment set from this function.
  • A parameter override set by llSetEnvironment will be preserved after the environment is replaced by this function. Call llSetEnvironment with an empty list parameter to clear any straggling overrides.
  • The environment specified by this function is applied asynchronously, as the simulator must download the environment asset before applying it. This means that llGetEnvironment will not immediately reflect the new environment's parameters, although the delay is typically quite small.
  • If a UUID is passed as the environment parameter and that UUID does not specify an environment setting or one can not be constructed, the function will return success (1) but will post a message to the debug channel.
All Issues ~ Search JIRA for related Bugs

Examples

See Also

Deep Notes

Search JIRA for related Issues

Signature

function Integer llReplaceEnvironment( vector position, string environment, integer track_no, integer day_length, integer day_offset );