Second Life Wiki - User contributions [en]

PRIM SIZE

2012-01-03T07:02:38Z

Batche Manen: Update for 64m prim scale allowance

<onlyinclude>{{#if:

{{#vardefine:size_const|{{LSL Const|PRIM_SIZE|integer|7|c=Used to {{GetSet|{{{1|}}}|get|set|/}} the prim's size}}}}

{{#vardefine:p_size_desc|ranges from 0.01 to 64.0 for x, y and z}}

}}</onlyinclude>{{#if:

}}{{LSL Constant
|name=PRIM_SIZE
|type=integer
|value=7
|desc=Returns or sets the prim's size.
|pa={{LSL Constant/List|i_front=[ {{#var:size_const}}, |i_end= ]
|text=When used with [[llSetPrimitiveParams]] & [[llSetLinkPrimitiveParams]]
|i1_type=vector|i1_name=size
|toc=llSetPrimitiveParams
}}
|pb={{LSL Constant/List|i_front=[[llGetPrimitiveParams]]([ {{#var:size_const}}|i_end= ]);|
|r_front=Returns the list [ |r_end= ]
|text
|r1_type=vector|r1_name=size
|toc=llGetPrimitiveParams
}}
|examples=
<lsl>//Changing the prim size and rotation
default
{
touch_start(integer total_number)
{
llSetPrimitiveParams([
PRIM_SIZE, <0.25,0.5,1.0>,
PRIM_ROTATION, <1.0, 0.0, 0.0, 0.0>
]);
}
} </lsl>
|constants=
|functions=
{{LSL DefineRow||[[llGetPrimitiveParams]]|}}
{{LSL DefineRow||[[llSetPrimitiveParams]]|}}
{{LSL DefineRow||[[llSetLinkPrimitiveParams]]|}}
{{LSL DefineRow||[[llGetScale]]|}}
{{LSL DefineRow||[[llSetScale]]|}}
|events=
|location
|cat1=Prim
|cat2
|cat3
|cat4
}}

LlSetScale

2012-01-03T07:00:10Z

Batche Manen: Update for 64m prim scale allowance

{{LSL Function
|func_id=47|func_sleep=0.0|func_energy=10.0
|func=llSetScale
|p1_type=vector|p1_name=size|p1_desc
|func_desc=Sets the size of the prim according to '''{{LSL Param|size}}'''
|func_footnote=The components of '''{{LSL Param|size}}''' ('''x''', '''y''' & '''z''') each need to be in the range {{Interval|center=component|gte=0.01|lte=64.0}}{{Footnote|handle=interval}}, if they are out of the range they are rounded to the nearest endpoint.
|spec
|caveats=
*This function only changes the size of the ''prim'' that the script is in. '''Not''' the entire object.
*If the prim is part of a link set, rescaling will fail if the new size is too large or small to satisfy the [[Linkability Rules|linkability rules]].
*Does not work on [[STATUS_PHYSICS|physical]] prims.
|constants
|examples=
<lsl>
//A basic door that opens and closes when an avatar collides with it.
//Not very effective, as it would be better to use llSetStatus(STATUS_PHANTOM, 1)...
//But, it works.
vector startingSize;
default {
state_entry() {
startingSize = llGetScale();
}
collision_start(integer i) {
llSetScale(<0.1, 0.1, 0.1>); //Shrink
llSetPos(llGetPos() + <0.0,0.0,10.0>); //Hide us
llSetTimerEvent(3.0);
}
timer() {
llSetTimerEvent(0.0);
llSetScale(startingSize); //Go back to normal size
llSetPos(llGetPos() - <0.0,0.0,10.0>); //And where we started
}
} //Code by Xaviar Czervik.
</lsl>
|helpers
|also_functions={{LSL DefineRow||[[llGetScale]]|Gets the prims size}}
{{LSL DefineRow||[[llSetPrimitiveParams]]|Sets prims attributes}}
{{LSL DefineRow||[[llGetPrimitiveParams]]|Gets prims attributes}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Prim
|cat2
|cat3
|cat4
|}}

LSL Protocol/Restrained Love Relay/Specification

2010-08-22T11:30:58Z

Batche Manen: Removed leftover !vision or !visionclear from Messages from in-world object to Relay (Formal Requirements), actual explanation of them was removed 17th April '09

{{Restrained Love Relay Specs TOC}}

'''VERSION 1.100'''

Written and maintained by {{User|Marine Kelley}}.

==Audience==

This document is meant for people who want to create or modify '''in-world objects''' to use the features of someone else's [http://realrestraint.blogspot.com RestrainedLove viewer], typically '''cages''' and '''pieces of furniture''', which per definition are usually not owned by that person.

==Introduction==

The [http://realrestraint.blogspot.com RestrainedLove viewer] only executes commands issued through [[llOwnerSay]] () messages. Therefore, in order to issue commands to someone using the viewer who does not own the object, that person must wear an attachment that '''relays''' commands after some '''security checks'''.

==Why this spec ?==

Many cages and furniture creators are interested in using its features such as sit, outfit, tp etc. These objects can be found in public places, or owned by friends... but as they are usually not owned by the user, the relay has to implement some basic security in order to avoid [[griefing]]. On top of it, the user does not want to be forced to switch to another relay when going to the next piece of furniture.

This is the purpose of this specification: To lay common rules so all the relays implementing it are compatible with all the furnitures implementing it too. Without such a specification, one cage/furniture would talk to the relay specifically made to operate with it and that's all, eventually making the creator stay behind because people rather use standard objects than proprietary closed ones.

==Basic principle==

Here is a sample use case:

# User is wearing a Relay
# User enters a cage in a public area
# Cage sends a chat message on a known private channel (for instance "@tploc=n")
# Relay receives the message, decides to repeat the command to the user and blocks their ability to teleport from the map with an [[llOwnerSay]] ("@tploc=n");
# User is allowed to get out after some time, the cage issues a "!release" command

Without the relay, the cage could never prevent the user from teleporting since it doesn't belong to them.

==Requirements==

Here are the informal requirements for a relay (formal requirements below).

===Security===
Any object sending commands over the channel the relay listens to is likely to harm the user if there is no security implemented in the former. For instance, one could [[rez]] an object that sends a "@remoutfit=force" command over the chat channel to force an avatar to get naked in front of everyone without a warning. Of course nobody wants that, so basic security is needed.

===User-friendliness===
Security often implies control (access lists, switch, permissions...) so the user must be given some basic control over what kind of objects are allowed to issue commands.

===Versatility===
Some users will prefer wearing a dedicated attachment that they can unwear any time they want, others will be required to have the relay locked on them so they cannot detach them, others will want the script only... It is important to keep those differences in mind when deciding about the permissions of the relay. However, it is the user's responsibility to choose the relay that suits their needs best.

===Licensing===
According to the level of complexity and support of the relay, the creator is allowed to either provide it for free (open/close source) or to sell it, as long as it implements all the formal requirements.

==Common questions==

===How hard is it to implement such a specification?===
That depends on what you do. Furniture/cage makers will find it very easy for it only comes down to sending commands over a chat channel and getting feedback. Relay makers will find it harder but then again, that depends on the level of security and user-friendliness they wish to offer. But make no mistake, the relay is what does almost all the job (along with the viewer), because there will be many more kinds of furnitures and cages than relays around.

===Why do other people need to write such a relay?===
Couldn't you write it yourself and publish it?

Of course I could, and there is even a working code for a basic relay at [[LSL Protocol/Restrained Love Relay/Reference Implementation|Reference Implementation]]. However:
* The protocol is likely to improve because nobody sees the future
* One object only would not suit everyone's needs
* It would have to implement perfect security and perfect user-friendliness, in all cases
* It would of course have to be perfectly scripted, without any bug whatsoever

The security and user-friendliness are the key parts here. Some users will prefer to be safe from [[griefing]], others will prefer a good user interface, others will like a lot of features, others will want to move the script elsewhere... Everyone has their own tastes so there can be no one-size-fits-all relay.

==Protocol==

In-world objects send chat message over a channel (common to every relay and furniture), that the relay(s) acknowledges or not. If the message is a correct command and passes whatever security checks the relay implements, the latter repeats it as an [[llOwnerSay]] ().

When the session ends, possibly after several relogs, the object clears all the restrictions it has put the user under.

===Example===

Here is a basic example of messages exchanged between an avatar (id "9213...") and a world object (id "7adf...") :

Object : CmdTest,9213f69a-ed7d-4a70-907a-7dba88c8831a,@tploc=n
Relay executes llOwnerSay ("@tploc=n");
Relay : CmdTest,7adf6218-ab26-8566-8387-660133840794,@tploc=n,ok

Object : BunchoCommands,9213f69a-ed7d-4a70-907a-7dba88c8831a,@tploc=n|@tplm=n|@tplure=n|@remoutfit:shoes=force
Relay executes llOwnerSay ("@tploc=n");
Relay executes llOwnerSay ("@tplm=n");
Relay executes llOwnerSay ("@tplure=n");
Relay : BunchoCommands,7adf6218-ab26-8566-8387-660133840794,@tploc=n,ok
Relay : BunchoCommands,7adf6218-ab26-8566-8387-660133840794,@tplm=n,ok
Relay : BunchoCommands,7adf6218-ab26-8566-8387-660133840794,@tplure=n,ok
Relay : BunchoCommands,7adf6218-ab26-8566-8387-660133840794,@remoutfit:shoes=force,ok

After a relog :
Relay : ping,7adf6218-ab26-8566-8387-660133840794,ping,ping
Object : ping,9213f69a-ed7d-4a70-907a-7dba88c8831a,!pong (UUID found with llGetOwnerKey(id), where id is the sender-parameter of the listen-event)

==Formal requirements==

===Common requirements to the Relay and the in-world object===

* The chat channel used by both the Relay and the in-world object is '''-1812221819'''. That's "RLVRS" ("RestrainedLove Viewer Relay Script") translated from alphabet to numbers.

* Messages on the channel are described here in a pseudo [http://en.wikipedia.org/wiki/Backus-Naur_form Backus-Naur Form] :

** '''''Messages from in-world object to Relay (3 tokens) :'''''
*** ''message'' ::= <cmd_name>''','''<user_uuid>''','''<list_of_commands>
*** ''list_of_commands'' ::= <command>['''|'''<list_of_commands>] (list_of_commands is *lowercase*)
*** ''command'' ::= <rl_command> or <metacommand>
*** ''rl_command'' ::= '''@'''behav[''':'''option]['''='''param]
*** ''metacommand'' ::= '''!version''' or '''!release''' or '''!pong''' or '''!implversion''' or '''!handover/'''<handoverparameter> or '''!who/'''<whoparameter>

** '''''Messages from Relay to in-world object (4 tokens) :'''''
*** ''message'' ::= <cmd_name>''','''<object_uuid>''','''<command>''','''<reply> (cmd_name is equal to the one in the incoming message)
*** ''reply'' ::= '''ok''' or '''ko''' or '''ping''' or <protocol_version> or <implementation_version>
*** ''protocol_version'' ::= integer (it is the version of the ''specification'', not of the script)

* The effect of the "!release" metacommand is to wipe out all the restrictions issued by the object which sends it.
* The effect of the "!version" metacommand is to send the version of the protocol the Relay implements. See below.
* The effect of the "ping" message from the Relay to the object is to check the latter is still available. If not, release the user to avoid having orphaned rules.
* Notice that acknowledgments do not apply to the list of commands but to one command only. Therefore a list of N commands gives N acknowledgment messages in return (at most).

'''In plain English :'''
* <cmd_name> is the name of the command, decided by the object. It will be used to find out which command has been acknowledged, therefore it must be repeated '''exactly''' by the Relay (without changing its case). An exception to the freedom of choice of the <cmd_name> token is the "ping" reserved name, see below.
* <user_uuid> is the [[UUID]] of the '''avatar''' owning the Relay.
* <object_uuid> is the [[UUID]] of the '''in-world object'''. Notice that we never need the [[UUID]] of the Relay as it's usually an attachment, prone to change its id after each relog.
* <list_of_commands> is a list of RL commands separated by pipes ('|'). It can be a single command (meaning no pipe present).
* <command> is either a regular RL command (@behav:option=param) or a metacommand, aimed at the Relay itself (!version, !release and !pong)
* Commands are separated by pipes ('|') here, but if they must be sent in the same [[llOwnerSay]] to the viewer they must be separated by commas (',') and with only one ''''@'''' sign at the beginning of the whole message. This is on purpose, to force the Relay to parse them and check them one by one, as well as facilitate the parsing of the whole message coming from the in-world object.
* Everyone listening on the relay channel must have enough script memory available to handle a complete chat message which is limited to 1,000 character (2,000 bytes + processing).

===="!release" metacommand====
* This metacommand is meant to make the Relay clear all the restrictions linked to the object issuing it. It is better to use it than to issue "counter-commands" to lift every restriction one by one without forgetting any.
* If the relay cancels an active session (for example because of a safeword being called), it has to send a !release,ok message.

===="!version" metacommand====
* When receiving this metacommand, the Relay must send a special acknowledgment that contains the version of the ''protocol'' it implements, on '''4 digits'''. This number must be an integer, equal to the version of this specification, written just after the title on this very page, times 1000. For instance, "1.120" would translate to "1120". It makes it easier to compare versions without fear of losing information with a float cast to a string and back to a float.
* Do not mistake the version of the ''protocol'' with the version (@version) of the ''viewer'' or the version of the ''scripts'' (!implversion).

===="ping" relay message and "!pong" object metacommand====
* When logging on, the relay will reapply all the stored restrictions but it only makes sense if the in-world object is still around and available for use. It could have been reset, crashed, or used by someone else while the primary user was offline. To let the relay apply the restrictions would therefore make no sense. That's why the relay has to ask the object if it's still around and available, and if no appropriate answer is received in a timely fashion then it must lift all the restrictions issued by it before, in order to start fresh again. Notice that "ping" is a simple word (to stay consistent with "ok" and "ko") while "!pong" is a metacommand.

The relay message must be "ping,<object_uuid>,ping,ping" and the object message must be "ping,<user_uuid>,!pong". This allows the object to keep a listener open with a static filter, to reduce lag. <user_uuid> can be retrieved by a [[llGetOwnerKey]]() call.

===Other metacommands===
The following metacommands are deemed "optional" and relays do not have to implement them to be considered RLV compliant. They are mostly tied to the specific implementation of a particular relay that a particular furniture needs to interrogate. Furniture must not rely on the implementation of any of these commands to work.

====="!implversion" metacommand=====
* The relay ''implementation'' should identify itself with a string.
* The is just like !version with the exception that !implversion is not about the ''protocol'' but about the implementation of it and may contain a string
* This version string is not intended for automatic checks but to help debugging problems
* Think of this as the signature of that particular relay
* The string must not contain any "," or "!" characters

===Deprecated metacommands===
The following metacommands used to belong to the specification without much discussion and without permission. They are mentioned here for reference but never meant to be part of the specification. They might be reinstated one day if they prove themselves useful, but at the time of this writing it would make no sense to consider a relay to be out of spec if it didn't implement those metacommands.

====="!who" metacommand=====
* Syntax: !who/<uuid>
* This is an information message from the world telling the relay which avatar is controlling it.
* Traps that are automatically triggered by the victim should use the uuid of the victim instead of the person who has setup the trap, perhaps hours ago
* 00000000-0000-0000-0000-000000000000 (NULL_KEY) is valid, meaning an unkown avatar
* Note: The content of this message is obviously only as trustworthy as the world object is
''Note from Marine : This metacommand may be designed to check the avatar operating the object to make griefing harder... but if this command is only as trustworthy as the object is, I don't see that as an improvement security-wise. Otherwise the idea has merit.''

====="!handover" metacommand=====
* Syntax: !handover/<key>/<type>
* Allows one world object to tell the relay it should accept commands from another world object instead without asking for permissions again. (For example a kidnapper object may do a force tpto to another sim where an other world object is waiting for the victim.
** (key) is the id of the target object
** (type) : 0 lift all restrictions of the source object, 1 keep them, it is the responsibility of the target object to keep them in mind
* The relay must ignore further "/"-parameters for future extension of the command.
* The relay must ignore any following commands on the same chat line
* The source object should send !handover/(key)/(type)|!release, so that relays that don't support !handover will release the restrictions and the next object can start normally.
* The relay must ensure with the !ping meachnism that the target object is available.
* The target object, however, might not be able to see the ping: For example because of a slow intersim teleport. In this case the target object must send a !pong on arrival of the victim anyway.
''Note from Marine : This metacommand is particularly interesting, and is likely to go to the Other Metacommands section in the future, or even in the main spec. It needs to be designed thoroughly first, though. I don't think it needs to be so complex, but it sure needs some checking.''

===Relay requirements===
* Send the exact @behav:option=param part in an [[llOwnerSay]] ()
* Retain a list of restrictions and their sources for when the user relogs.
* Force sit if unsit is prevented when relogging.
* When relogging, send a "ping" message (see above) to check the in-world object is still available. If no message after a few seconds (not necessarily a "!pong", any message aimed at the relay can do), release the rules linked to this object.
* The user must have access to the version of the specification and the version of the implemenation (dialog, message, object name...) to check everything works correctly.
* The relay must silently ignore commands to remove non-existing restrictions without spamming the user with pointless "ask for permission dialogs"
* Relays must accept !release even if the world object is out of range.
* Relays must send a !release,ok if they cancel an active session (for example because of an safeword)
* Relays must ensure that it preserves the order of commands. For example: If a restriction is queued in the Ask-dialog, the lifting of the restriction must not be executed immediately unless the pending restriction in the ask-dialog-queue is removed, too.

===In-world object requirements===
* If a world object sent any restrictions, it must end the session with !release even if the relay did not respond with "ok" unless all commands have been "ko"-ed. The relay may have delayed the execution to ask permission from the user who may confirm them after the session has already ended
* When receiving a "ping" message from a relay, reply with a "!pong" message (as described above) aimed at the avatar owning it, provided they are still restricted by the object.
* Never rely on an answer from the Relay, requests can be denied silently, the Relay can be unworn, the avatar can TP out or crash... => use timeouts.
* Don't poll the [[dataserver]] for online status, the Relay takes care of the relog part.
* World objects should not spam the relay channel. For example: Querying every minute the relay version of every person near although nobody shows any signs to actually use the object.

== History ==

You can find the change history of this specification at [[LSL Protocol/Restrained Love Relay/Change History|Change History]],

[[Category:RestrainedLove]]

LSL Protocol/RestrainedLoveAPI

2010-07-29T14:30:31Z

Batche Manen: Updated the example under @getstatus to actually be correct for RLV post- v1.16 when the return was changed to prepended itself with a /

{{LSL Header|ml=*}}
=Restrained Love viewer v1.23 Specification=

By [[User:Marine Kelley|Marine Kelley]]

==Audience==

This document is for people who wish to modify or create their own [[LSL]] scripts to use the features of the [http://realrestraint.blogspot.com RestrainedLove viewer]. It does not explain [[LSL]] concepts such as messages and events, nor universal concepts such as [[UUID]]s.

This document contains the specification for RestrainedLove viewer itself. If you need information about the RestrainedLove viewer relay(RLV relay), please see the [[LSL_Protocol/Restrained_Love_Relay/Specification|RLV relay specification]]

==Introduction==

The [http://realrestraint.blogspot.com RestrainedLove viewer] executes certain behaviours when receiving special messages from scripts in-world. These messages are mostly calls to the [[llOwnerSay]]() [[LSL]] function.

==Architecture==

The [http://realrestraint.blogspot.com RestrainedLove viewer] intercepts every [[llOwnerSay]] message sent to the viewer. Lines that begin with an at-sign (''''@'''') are parsed as RLV commands. Other lines are forwarded to the user in the Local Chat window, as usual. For instance, a call to [[llOwnerSay]] ("@detach=n") sends the ''detach'' command with parameter ''n'' to the viewer on behalf of the object running the script.

The syntax of a message is:

: <code>@<command1>[:option1]=<param1>,<command2>[:option2]=<param2>,...,<commandN>[:optionN]=<paramN></code>

Note that there is only one '@' sign, placed at the beginning of the message. The viewer interprets this as "this entire [[llOwnerSay]]() message contains one or more commands to execute". For documentation purposes, commands are always presented with the leading ''''@''''. However, it is an error to put the ''''@'''' in front of each command within a multi-command message, and the the subsequent commands will fail.

: Historical Note: Prior to Version '''1.10''', RLV only allowed one command per message. Version '''1.10''' added the ability to include multiple commands in one message, to avoid spamming users who are not using this viewer.

If at least one command fails (e.g. a typo), the viewer says "... fails command : ... " and prints the entire message. However, correct commands are still parsed and executed, only the incorrect ones are ignored.

Many of these commands determine the subsequent ''behaviour'' of the object or avatar. For example, the '''@detach=n''' command locks the given object, making it undetachable. Some commands set ''global behaviours'', which aren't limited to the object sending the command. For example, the '''@sendchat=n''' command will prevent the user from talking in local chat.

'''NOTE''' about commands with exceptions, such as @sendim or @sendchannel... @(rule):(exception)=n actually (and counter-intuitively) '''adds an exception''' for the given rule. @sendchannel:1=n, for example, '''allows''' chat on channel 1. This has been the source of at least two scripters' confusion. =add (which means the same as =n) and =rem (which means =y) exist for the purpose of adding and removing exceptions, respectively. Use them.

{{hint|mode=warning|desc=These behaviours are '''not''' persistent between sessions. Since an object changes its [[UUID]] every time it [[rez]]zes, the object ''must'' resend its status (undetachable, preventing IMs...) in the [[on_rez]]() event as well as whenever it changes its status.}}

==List of commands==

'''Note:''' These commands are not case-sensitive but are spacing-sensitive. In other words, "@detach = n" will '''not''' work.

'''Notation convention:''' Parameters in [square brackets] are optional parameters that can be omitted. The pipe | and slash / signs separate options from which one must be used. <angle brackets> enclose parameters that are mandatory.

* '''''Automated version checking''''' : "@version=<channel_number>"
''Implemented in v1.0b''
Makes the viewer automatically say its version immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

'''Warning''' : when logging in, the [[on_rez]] event of all the attachments occurs way before the avatar can actually send chat messages (about half the way through the login progress bar). This means the timeout should be long enough, like 30 seconds to one minute in order to receive the automatic reply from the viewer.

'''Warning 2''' : On 02/22/2010, Linden Lab has released their Third Party Viewer policy which forbids using the term "Life" in the name of Third Party Viewers. Therefore "Restrained Life" had to be renamed to "Restrained Love". However, for compatibility purposes, this @version command still works and will keep working, however you are encouraged to '''not''' use it in new scripts, and to '''not''' show the terms "Restrained Life" to the user anywhere. For new scripts, please use @versionnew below instead.

* '''''Automated version checking''''' : "@versionnew=<channel_number>"
''Implemented in v1.23''
Makes the viewer automatically say its version immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

This command is the successor of @version and replaces it, although @version is kept for ascending compatibility purposes. It returns "RestrainedLove viewer v... (SL ...)" ("RestrainedLove" is in one word).

'''Warning''' : when logging in, the [[on_rez]] event of all the attachments occurs way before the avatar can actually send chat messages (about half the way through the login progress bar). This means the timeout should be long enough, like 30 seconds to one minute in order to receive the automatic reply from the viewer.

* '''''Automated version number checking''''' : "@versionnum=<channel_number>"
''Implemented in v1.21''
Makes the viewer automatically say its version number immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. This command is less cumbersome than @version, since the script does not have to parse the response, it gets the version number immediately.

The version number is a mere integer that represents the version of the viewer. If the version is X.Y.Z.P, then the number will be X.10^6 + Y.10^4 + Z.10^2 + P. For example, 1.21.1 would be 1210100.

* '''''Automated version checking, second way''''' : llGetAgentLanguage (key id) '''''DEPRECATED: DO NOT USE !'''''
''Implemented in v1.16''
When calling this LSL function, the result is obtained immediately (no need to use a listener and a timer), is exactly equal to the one given by "@version" and cannot be hidden by the user. This string takes the place of the language returned by the regular SL viewer, which could answer values like "en-us", "fr", "ko" etc. Or nothing at all, if the user chose to hide their language setting. Being optional in the regular viewer, it cannot be trusted by a script, so "hijacking" this feature for the much more useful synchronous version checking in the RLV makes sense. IMPORTANT NOTE: this feature cannot be implemented in viewers prior to v1.21, even when they do implement RestrainedLove v1.16, so make sure you do fall back to the @version method whenever llGetAgentLanguage() returns an empty string. ALSO NOTE: In RestrainedLove 1.16, llGetAgentLanguage() will return an empty string when called by on_rez during login unless the call is delayed by several seconds (how many seconds may vary). FINAL NOTE: This feature was removed from v1.16.1 (and v1.16b, for the Cool SL Viewer).

* '''''Manual version checking''''' : "@version"
''Implemented in v1.0a''
This command must be sent in IM from an avatar to the user (will not work from objects). The viewer automatically answers its version to the sender in IM, but neither the message nor the answer appears in the user's IM window, so it's totally stealthy.

* '''''Render an object detachable/nondetachable''''' : "@detach=<y/n>"
''Implemented in v1.0a''
When called with the "n" option, the object sending this message (which must be an attachment) will be made nondetachable. It can be detached again when the "y" option is called.

* '''''Unlock/Lock an attachment point''''' : "@detach:<attach_point_name>=<y/n>"
''Implemented in v1.20''
When called with the "n" option, the attachment point of name <attach_point_name> will be locked either full (if it is occupied by an object at that time) or empty (if not). Any object that is occupying this point when the restriction is issued will be considered as undetachable, exactly like if it had issued a "@detach=n" command itself. If the point is empty it will stay that way, no item will be able to be attached there, and llAttachToAvatar() calls will fail (the object will be attached, then detached right away).

* '''''Unlock/Lock an attachment point empty''''' : "@addattach[:<attach_point_name>]=<y/n>"
''Implemented in v1.22''
When called with the "n" option, the attachment point of name <attach_point_name> will be locked empty. Any object that is occupying this point when the restriction is issued can be detached, but nothing can be attached there. If the point is empty it will stay that way, no item will be able to be attached there, and llAttachToAvatar() calls will fail (the object will be attached, then detached right away). If <attach_point_name> is not specified, then all the attachment points will be concerned. This command is the counterpart to @addoutfit, for attachments.

* '''''Unlock/Lock an attachment point full''''' : "@remattach[:<attach_point_name>]=<y/n>"
''Implemented in v1.22''
When called with the "n" option, the attachment point of name <attach_point_name> will be locked full. Any object that is occupying this point when the restriction is issued will be rendered undetachable. If the point is empty it will allow the user to wear something, but then that object will become undetachable too, no item will be able to replace it, and llAttachToAvatar() calls will fail (the object will be attached, then detached right away). If <attach_point_name> is not specified, then all the attachment points will be concerned. This command is the counterpart to @remoutfit, for attachments.

* '''''Allow/deny the "Wear" contextual menu''''' : "@defaultwear=<y/n>
''Implemented in v1.21''
When allowed, the user is always able to choose the "Wear"command on the contextual menu of the inventory, even when an object is locked on their avatar. This holds the risk of kicking that locked object, but it will be reattached automatically within 5 seconds (and successive locked objects every second until there is nothing left to reattach). However some objects may be scripted in a way that they drop their restrictions when detached, or simply not take into account the fact that even a locked object can be detached when using the RLV.

Therefore, using this command with the "n" option will suppress this comman, but it will still be available for objects that contain the target attachment point in their name or in the name of their parent folder, exactly like pre-1.21 RLV. This is a little less user-friendly but more secure when it comes to make sure no locked object may be detached accidentally.

* '''''Start/stop notifications on a private channel''''' : "@notify:<channel_number>[;word]=<rem/add>"
''Implemented in v1.20''
Makes the viewer automatically repeat any restriction it adds or removes on the specified channel, or only the restrictions which name contains the word specified after the semicolon (";") character. The response on the private channel <channel_number> is preceded with a slash ("/") to avoid making the avatar send commands to other scripts without knowing it, and followed by an equal sign ("=") and "n" or "y" according to whether the restriction is applied or lifted respectively. The "@clear" command will not add an equal sign. There is no way to know what object issued the restriction or lifted it, to avoid disclosing too much information about foreign scripts. It does not repeat one-shot commands either (force commands). For example, "@notify:2222;detach=add" will send "/detach=n" whenever an object is locked, and "/detach=y" whenever an object is unlocked, on channel 2222 to which the script will listen to.

* '''''Allow/prevent sending chat messages''''' : "@sendchat=<y/n>"
''Implemented in v1.0b''
When prevented, everything typed on [[channel]] 0 will be discarded. However, emotes and messages beginning with a slash ('/') will go through, truncated to strings of 30 and 15 characters long respectively (likely to change later). Messages with special signs like ()"-*=_^ are prohibited, and will be discarded. When a period ('.') is present, the rest of the message is discarded.

* '''''Remove/add an exception to the emote truncation above''''' : "@emote=<rem/add>"
''Implemented in v1.01''
When adding this exception, the emotes are not truncated anymore (however, special signs will still discard the message).

* '''''Allow/prevent shouting''''' : "@chatshout=<y/n>"
''Implemented in v1.15''
When prevented, the avatar will chat normally even when the user tries to shout. This does not change the message in any way, only its range.

* '''''Allow/prevent chatting at normal volume''''' : "@chatnormal=<y/n>"
''Implemented in v1.15''
When prevented, the avatar will whisper even when the user tries to shout or chat normally. This does not change the message in any way, only its range.

* '''''Allow/prevent whispering''''' : "@chatwhisper=<y/n>"
''Implemented in v1.15''
When prevented, the avatar will chat normally even when the user tries to whisper. This does not change the message in any way, only its range.

* '''''Redirect public chat to private channels''''' : "@redirchat:<channel_number>=<rem/add>"
''Implemented in v1.16''
When active, this restriction redirects whatever the user says on the public channel ("/0") to the private channel provided in the option field. If several redirections are issued, the chat message will be redirected to each channel. It does not apply to emotes, and will not trigger any animation (typing start, typing stop, nodding) when talking. This restriction does not supercede @sendchannel.
'''NOTE:''' As of RLV v1.22.1 / RLVa 1.1.0 @redirchat also truncates emotes on channel 0. It's not clear if this is a bug or a missing note in the API. An additional @emote=add works around this side-effect. '''Addendum by {{User|Henri Beauchamp}}''': as someone who worked together with Marine on the reference implementation, this is '''clearly''' a bug and plain unintended. It appeared during some code refactoring, but as always specified before in the API, @redirchat should *not* affect emotes at all. If you want to affect emotes as well, please use @rediremote. This bug was fixed in the [http://sldev.free.fr/ Cool VL Viewer].

* '''''Redirect public emotes to private channels''''' : "@rediremote:<channel_number>=<rem/add>"
''Implemented in v1.19''
When active, this restriction redirects whatever emote the user says on the public channel ("/0") to the private channel provided in the option field. If several redirections are issued, the emote will be redirected to each channel.

* '''''Allow/prevent sending instant messages''''' : "@sendim=<y/n>"
''Implemented in v1.0b''
When prevented, everything typed in IM will be discarded and a bogus message will be sent to the receiver instead.

* '''''Allow/prevent sending instant messages, secure way''''' : "@sendim_sec=<y/n>"
''Implemented in v1.21''
When prevented, everything typed in IM will be discarded and a bogus message will be sent to the receiver instead. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the instant message sending prevention''''' : "@sendim:<UUID>=<rem/add>"
''Implemented in v1.01''
When adding an exception, the user can send IMs to the receiver whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving chat messages''''' : "@recvchat=<y/n>"
''Implemented in v1.0b''
When prevented, everything heard in public chat will be discarded except emotes.

* '''''Allow/prevent receiving chat messages, secure way''''' : "@recvchat_sec=<y/n>"
''Implemented in v1.21''
When prevented, everything heard in public chat will be discarded except emotes. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the chat message receiving prevention''''' : "@recvchat:<UUID>=<rem/add>"
''Implemented in v1.01''
When adding an exception, the user can hear chat messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent seeing emotes''''' : "@recvemote=<y/n>"
''Implemented in v1.19''
When prevented, every emote seen in public chat will be discarded.

* '''''Allow/prevent seeing emotes, secure way''''' : "@recvemote_sec=<y/n>"
''Implemented in v1.21''
When prevented, every emote seen in public chat will be discarded. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the emote seeing prevention''''' : "@recvemote:<UUID>=<rem/add>"
''Implemented in v1.19''
When adding an exception, the user can see emotes from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving instant messages''''' : "@recvim=<y/n>"
''Implemented in v1.0b''
When prevented, every incoming IM will be discarded and the sender will be notified that the user cannot read them.

* '''''Allow/prevent receiving instant messages, secure way''''' : "@recvim_sec=<y/n>"
''Implemented in v1.21''
When prevented, every incoming IM will be discarded and the sender will be notified that the user cannot read them. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the instant message receiving prevention''''' : "@recvim:<UUID>=<rem/add>"
''Implemented in v1.01''
When adding an exception, the user can read instant messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent teleporting to a landmark''''' : "@tplm=<y/n>"
''Implemented in v1.0''
When prevented, the user cannot use a [[landmark]], pick or any other preset location to [[teleport]] there.

* '''''Allow/prevent teleporting to a location''''' : "@tploc=<y/n>"
''Implemented in v1.0''
When prevented, the user cannot use [[teleport]] to a coordinate by using the [[map]] and such.

* '''''Allow/prevent teleporting by a friend''''' : "@tplure=<y/n>"
''Implemented in v1.0''
When prevented, the user automatically discards any [[teleport]] offer, and the avatar who initiated the offer is notified.

* '''''Allow/prevent teleporting by a friend, secure way''''' : "@tplure_sec=<y/n>"
''Implemented in v1.21''
When prevented, the user automatically discards any [[teleport]] offer, and the avatar who initiated the offer is notified. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the friend teleport prevention''''' : "@tplure:<UUID>=<rem/add>"
''Implemented in v1.0''
When adding an exception, the user can be teleported by the avatar whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Unlimit/limit sit-tp''''' : "@sittp=<y/n>"
''Implemented in v1.0''
When limited, the avatar cannot sit on a [[prim]] unless it is closer than 1.5 m. This allows cages to be secure, preventing the avatar from warping its position through the walls (unless the prim is too close).

* '''''Allow/deny permissive exceptions''''' : "@permissive=<y/n>"
''Implemented in v1.21''
When denied, all restrictions turn into their "secure" counterparts (if any). This means an exception to a restriction will be ignored if it is not issued by the same object that issued the restriction. Using non-secure restrictions (the original ones, like @sendim, @recvim etc) and not using @permissive allow the avatar to benefit from exceptions issued by different objects.

'''Warning''' : Using this command (or any secure version of the original commands) may silently discard exceptions issued by different objects (it is even its primary purpose), hence some products may appear to cease working while this restriction is in effect. For example, a product that allows the avatar to always be able to send IMs a particular friend will not be able to overcome a @sendim_sec or a @permissive command sent by another object, and will look like it is broken. Therefore, use with caution and make the user aware of how secure your own product is !

* '''''Clear all the rules tied to an object''''' : "@clear"
''Implemented in v1.0a, but working only since v1.04a''
This command clears all the restrictions and exceptions tied to a particular [[UUID]].

'''Warning''' : when triggered on detach by default, this might prevent the automatic reattach when @defaultwear is active, as @clear will also lift @detach=n, thus the viewer thinks the item that gets detached by accident by a default-wear-action is unlocked and will not reattach it.

Possible workarounds:
::* only lift the exact restrictions you added with @clear=<pattern>
::* only trigger @clear on detach when you are sure the attachment is not locked
::* don't trigger @clear on detach at all and wait for the viewer to lift the set restrictions

* '''''Clear a subset of the rules tied to an object''''' : "@clear=<string>"
''Implemented in v1.0a, but working only since v1.04a''
This command clears all the restrictions and exceptions tied to a particular [[UUID]] which name contains <string>. A good example would be "@clear=tp" which clears all the [[teleport]] restrictions and exceptions tied to that object, whereas "@clear=tplure:" would only clear the exceptions to the "teleport-by-friend" restriction

* '''''Allow/prevent editing objects''''' : "@edit=<y/n>"
''Implemented in v1.03''
When prevented from editing and opening objects, the Build & Edit window will refuse to open.

* '''''Allow/prevent rezzing inventory''''' : "@rez=<y/n>"
''Implemented in v1.03''
When prevented from [[rez]]zing stuff, creating and deleting objects, drag-dropping from inventory and dropping attachments will fail.

* '''''Allow/prevent wearing clothes''''' : @addoutfit[:<part>]=<y/n>
''Implemented in v1.10, added skin hair and eyes in v1.10.1''
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin|eyes|hair|shape|alpha|tattoo
If part is not specified, prevents from wearing anything beyond what the avatar is already wearing.

'''Note:''' Since the release of Viewer 2.0 there are two new avatar skin layers: Tattoo and Avatar Transparency Mask. The alpha and tattoo layers will only be supported by RLV compliant viewers that implement the new Viewer 2.0 features.

* '''''Allow/prevent removing clothes''''' : @remoutfit[:<part>]=<y/n> (underpants and undershirt are kept for teens)
''Implemented in v1.10, added skin hair and eyes in v1.10.1''
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin|eyes|hair|shape|alpha|tattoo
If part is not specified, prevents from removing anything in what the avatar is wearing.

'''Note:''' Since the release of Viewer 2.0 there are two new avatar skin layers: Tattoo and Avatar Transparency Mask. The alpha and tattoo layers will only be supported by RLV compliant viewers that implement the new Viewer 2.0 features.

* '''''Force removing clothes''''' : @remoutfit[:<part>]=force (*) (teens can't be forced to remove underpants and undershirt)
''Implemented in v1.10''
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|alpha|tattoo
If part is not specified, removes everything.

'''Note:''' Since the release of Viewer 2.0 there are two new avatar skin layers: Tattoo and Avatar Transparency Mask. The alpha and tattoo layers will only be supported by RLV compliant viewers that implement the new Viewer 2.0 features.

'''Note:''' skin, shape, eyes and hair cannot be removed since they are body parts (and removing any would result in an unrezzed avatar).

* '''''Force removing attachments''''' : @detach[:attachpt]=force (*)
''Implemented in v1.10''
Where part is :
chest|skull|left shoulder|right shoulder|left hand|right hand|left foot|right foot|spine|
pelvis|mouth|chin|left ear|right ear|left eyeball|right eyeball|nose|r upper arm|r forearm|
l upper arm|l forearm|right hip|r upper leg|r lower leg|left hip|l upper leg|l lower leg|stomach|left pec|
right pec|center 2|top right|top|top left|center|bottom left|bottom|bottom right
If part is not specified, removes everything.

* '''''Force removing attachments (alias)''''' : @remattach[:attachpt]=force (*)
''Implemented in v1.22''
This command is an alias to @detach[:attachpt]=force (to keep things consistent).

* '''''Get the list of worn clothes''''' : @getoutfit[:part]=<channel_number>
''Implemented in v1.10, added skin hair and eyes in v1.10.1''
Makes the viewer automatically answer the current occupation of clothes layers as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
gloves,jacket,pants,shirt,shoes,skirt,socks,underpants,undershirt,skin,eyes,hair,shape
in that order.

If a part is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the part.
Ex 1 : @getoutfit=2222 => "0011000111" => avatar is wearing pants, shirt, underpants and undershirt, and of course a skin.
Ex 2 : @getoutfit:socks=2222 => "0" => the avatar is not wearing socks.

'''Note:''' For viewers that implement the new Viewer 2.0 features, the list is:

gloves,jacket,pants,shirt,shoes,skirt,socks,underpants,undershirt,skin,eyes,hair,shape,alpha,tattoo

* '''''Get the list of worn attachments''''' : @getattach[:attachpt]=<channel_number>
''Implemented in v1.10''
Makes the viewer automatically answer the current occupation of attachment points as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
none,chest,skull,left shoulder,right shoulder,left hand,right hand,left foot,right foot,spine,
pelvis,mouth,chin,left ear,right ear,left eyeball,right eyeball,nose,r upper arm,r forearm,
l upper arm,l forearm,right hip,r upper leg,r lower leg,left hip,l upper leg,l lower leg,stomach,left pec,
right pec,center 2,top right,top,top left,center,bottom left,bottom,bottom right
in that order.

If an attachment point is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the point.
Ex 1 : @getattach=2222 => "011000011010000000000000100100000000101" => avatar is wearing attachments on
chest, skull, left and right foot, pelvis, l and r lower leg, HUD bottom left and HUD bottom right.
Ex 2 : @getattach:chest=2222 => "1" => avatar is wearing something on the chest.

''Note'' : The first character ("none") is always '0', so the index of each attach point in the string is '''exactly equal''' to the corresponding ATTACH_* macro in LSL. For instance, the index 9 in the string is ATTACH_BACK (which means "spine"). Remember the indices start at zero.

* '''''Force the viewer to automatically accept attach and take control permission requests''''' : @acceptpermission=<rem/add>
''Implemented in v1.16''
Forces the avatar to automatically accept attach and take control permission requests. The dialog box doesn't even show up. This command does not supercede @denypermission, of course.

* '''''Allow/prevent accepting attach and take control permissions''''' : @denypermission=<rem/add>
''Implemented in v1.16, DEPRECATED in v1.16.2''
When prevented, all attach and take control permission requests are automatically declined, without even showing the dialog box. Due to the extreme annoyance it was making, and because locked objects automatically reattach themselves since v1.16.1, this command is NOW DEPRECATED, DON'T USE IT !

* '''''Allow/prevent using inventory''''' : @showinv=<y/n>
''Implemented in v1.10''
Forces the [[inventory]] windows to close and stay closed.

* '''''Allow/prevent reading notecards''''' : @viewnote=<y/n>
''Implemented in v1.10''
Prevents from opening [[notecards]] but does not close the ones already open.

* '''''Allow/prevent opening scripts''''' : @viewscript=<y/n>
''Implemented in v1.22''
Prevents from opening [[scripts]] but does not close the ones already open.

* '''''Allow/prevent opening textures''''' : @viewtexture=<y/n>
''Implemented in v1.22''
Prevents from opening [[textures]] (and snapshots) but does not close the ones already open.

* '''''Allow/prevent standing up''''' : @unsit=<y/n>
''Implemented in v1.10, modified in v1.15 to prevent teleporting as well''
Hides the Stand up button. From v1.15 it also prevents teleporting, which was a way to stand up.

* '''''Force sit on an object''''' : @sit:<UUID>=force (*)
''Implemented in v1.10''
Does not work if the user is prevented from sit-tping and further than 1.5 meters away, or when prevented from unsitting.

* '''''Force unsit''''' : @unsit=force (*)
''Implemented in v1.10''
Self-explanatory but for some reason it randomly fails, so don't rely on it for now. Further testing is needed.

* '''''Allow/prevent sitting down''''' : @sit=<y/n>
''Implemented in v1.16.2''
Prevents the user from sitting on anything, including with @sit:UUID=force.

* '''''Allow/prevent using any chat channel but certain channels''''' : @sendchannel[:<channel>]=<y/n>
''Implemented in v1.10''
Complimentary of @sendchat, this command prevents the user from sending messages on non-public [[channel]]s. If channel is specified, it becomes an exception to the aforementioned restriction. It does not prevent the viewer automatic replies like @version=nnnn, @getstatus=nnnn etc.

* '''''Allow/prevent using any chat channel but certain channels, secure way''''' : @sendchannel_sec[:<channel>]=<y/n>
''Implemented in v1.10''
Complimentary of @sendchat, this command prevents the user from sending messages on non-public [[channel]]s. If channel is specified, it becomes an exception to the aforementioned restriction. It does not prevent the viewer automatic replies like @version=nnnn, @getstatus=nnnn etc. This particular command only accepts exceptions issued from the same object, opposed to its non-secure version which accepts exceptions from any other object.

* '''''Get the list of restrictions the avatar is currently submitted to''''' : @getstatus[:<part_of_rule>]=<channel>
''Implemented in v1.10, slightly tweaked in v1.16''
Makes the viewer automatically answer the list of rules the avatar is currently under, only for the object containing the script issuing that command, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is a list of rules, separated by slashes ('/'). Attention : since v1.16 a slash is prepended at the beginning of the string. This does not confuse llParseString2List() calls, but does confuse llParseStringKeepNulls() calls !

This command is useful for people who write scripts that may conflict with other scripts in the same object (for instance : third-party plugins). Conflicts do not occur in different objects, that's why this command only applies to the object calling it.

<part_of_rule> is the name of a rule, or a part of it, useful if the script only needs to know about a certain restriction.

Example : If the avatar is under tploc, tplure, tplm and sittp, here is what the script would get :
@getstatus=2222 => /tploc/tplure/tplm/sittp
@getstatus:sittp=2222 => /sittp
@getstatus:tpl=2222 => /tploc/tplure/tplm (because "tpl" is part of "tploc", "tplure" and "tplm" but not "sittp")

* '''''Get the list of all the restrictions the avatar is currently submitted to''''' : @getstatusall[:<part_of_rule>]=<channel>
''Implemented in v1.15, slightly tweaked in v1.16''
Makes the viewer automatically answer the list of rules the avatar is currently under, for all the objects regardless of their UUID, contrary to @getstatus, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is a list of rules, separated by slashes ('/'). Attention : since v1.16 a slash is prepended at the beginning of the string. This does not confuse llParseString2List() calls, but does confuse llParseStringKeepNulls() calls !

* '''''Get the list of shared folders in the avatar's inventory''''' : @getinv[:folder1/.../folderN]=<channel_number>
''Implemented in v1.11, added sub-folders in v1.13''
Makes the viewer automatically answer the list of folders contained into the folder named "#RLV" (if it exists), immediately on the chat channel number <channel_number> that the script can listen to. If folders are specified, it will give the list of sub-folders contained into the folder located at that path instead of the shared root (example : "@getinv:Restraints/Leather cuffs/Arms=2222"). Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The answer is a list of names, separated by commas (","). Folders which names begin with a dot (".") will be ignored.

* '''''Get the list of shared folders in the avatar's inventory, with information about worn items''''' : @getinvworn[:folder1/.../folderN]=<channel_number>
''Implemented in v1.15''
Makes the viewer automatically answer the list of folders contained into the folder named "#RLV" (if it exists), immediately on the chat channel number <channel_number> that the script can listen to. If folders are specified, it will give the list of sub-folders contained into the folder located at that path instead of the shared root (example : "@getinvworn:Restraints/Leather cuffs/Arms=2222"). Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The answer is a comma-separated list of names, each one followed with a pipe ("|") and two digits. The current folder is put in first position (as opposed to @getinv which does not show the current folder, obviously), but without a name, only the pipe and the two digits.

Object : "@getinvworn:Restraints/Leather cuffs=2222"
Viewer : "|02,Arms|30,Legs|10"

Folders which names begin with a dot (".") will be ignored. The two digits are calculated as follows :

First digit : Proportion of items worn in the corresponding folder (including no-mod items). In this example, the "3" of "30" means "all the items in the "Arms" folder are currently worn, while the "1" of "10" means "no item in the Legs folder is currently worn, but there are items to wear".

Second digit : Proportion of items globally worn in all the folders contained inside the corresponding folder. In this example, the "2" of "02" means "some items are worn in some of the folders contained into "Leather cuffs".

The digits, comprised between 0 and 3 included, have the following meaning :

* 0 : No item is present in that folder
* 1 : Some items are present in that folder, but none of them is worn
* 2 : Some items are present in that folder, and some of them are worn
* 3 : Some items are present in that folder, and all of them are worn

* '''''Get the path to a shared folder by giving a search criterion''''' : @findfolder:part1[&&...&&partN]=<channel_number>
''Implemented in v1.13.1''
Makes the viewer automatically answer the path to the first shared folder which name contains <part1> and <part2> and ... and <partN>, immediately on the chat channel number <channel_number> that the script can listen to. The search is in depth first, notice the separator which is "&&" like "and". Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. It does not take disabled folders into account (folders which name begins with a dot "."), nor folders which name begins with a tilde ("~"). The answer is a list of folders, separated by slashes ('/').

* '''''Force attach items contained inside a shared folder''''' : @attach:<folder1/.../folderN>=force (*)
''Implemented in v1.11, added no-mod items in v1.12, added sub-folders in v1.13''
Forces the viewer to attach every object and wear every piece of clothing contained inside the folder located at the specified path (which must be under "#RLV"). Objects names '''must''' contain the name of their target attachment point or they won't be attached. Each no-modify object '''must''' be contained inside a folder (one object per folder), which name contains the name of its target attachment point since it can't be renamed. Names cannot begin with a dot (".") since such folders are invisible to the scripts.

Attachment point names are the same as the ones contained into the "Attach To" submenu : "skull", "chest", "l forearm"...

Note : Folder names '''can''' contain slashes, and will be chosen in priority when able (for instance, if "@attach:Restraints/cuffs=force" is issued, the "Restraints/cuffs" folder will be chosen before a "cuffs" folder contained inside a "Restraints" parent folder.

* '''''Force attach items contained inside a shared folder, and its children recursively''''' : @attachall:<folder1/.../folderN>=force (*)
''Implemented in v1.15''
This command works exactly like @attach described hereabove, but also attaches whatever is contained into children folders.

* '''''Force detach items contained inside a shared folder''''' : @detach:<folder_name>=force (*)
''Implemented in v1.11''
Forces the viewer to detach every object and unwear every piece of clothing contained inside <folder_name>(which must be directly under "#RLV"). If "@detach" is used with an attachment point name (skull, pelvis... see above), it takes priority over this way of detaching since it is the same command.

* '''''Force detach items contained inside a shared folder, and its children recursively''''' : @detachall:<folder1/.../folderN>=force (*)
''Implemented in v1.15''
This command works exactly like @detach described hereabove, but also detaches whatever is contained into children folders.

* '''''Get the path to the shared folder containing a particular object/clothing''''' : @getpath[:<attachpt> or <clothing_layer>]=<channel_number>
''Implemented in v1.16''
Makes the viewer automatically answer the path to the shared folder containing the item that :
** issues this command if no option is set
** is attached on the attach point provided in the option field, ex : @getpath:spine=2222 => "Restraints/Collar"
** is worn on the clothing layer provided in the option field, ex : @getpath:pants=2222 => "Casual/Jeans/Tight"
Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. It does not take disabled folders into account (folders which name begins with a dot "."). The answer is a list of folders, separated by slashes ('/').

* '''''Force attach items contained into a shared folder that contains a particular object/clothing''''' : @attachthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with an @attach command (this saves a listener and a timeout).

* '''''Force attach items contained into a shared folder that contains a particular object/clothing, and its children folders''''' : @attachallthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with an @attachall command (this saves a listener and a timeout).

* '''''Force detach items contained into a shared folder that contains a particular object/clothing''''' : @detachthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with a @detach command (this saves a listener and a timeout).

* '''''Force detach items contained into a shared folder that contains a particular object/clothing, and its children folders''''' : @detachallthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with a @detachall command (this saves a listener and a timeout).

* '''''Force detach an item''''' : @detachme=force (*)
''Implemented in v1.16.2''
This command forces the object that issues it to detach itself from the avatar. It is there as a convenience to avoid a race condition when calling @clear then llDetachFromAvatar(), sometimes the object could detach itself before clearing its restrictions, making it reattach automatically after a while. With this command one can issue a @clear,detachme=force to be sure @clear is executed first.

* '''''Allow/prevent touching objects located further than 1.5 meters away from the avatar''''' : @fartouch=<y/n>
''Implemented in v1.11''
When prevented, the avatar is unable to touch/grab objects from more than 1.5 m away, this command makes restraints more realistic since the avatar litterally has to press against the object in order to click on it.

* '''''Allow/prevent viewing the world map''''' : @showworldmap=<y/n>
''Implemented in v1.11''
When prevented, the avatar is unable to view the world map, and it closes if it is open when the restriction becomes active.

* '''''Allow/prevent viewing the mini map''''' : @showminimap=<y/n>
''Implemented in v1.11''
When prevented, the avatar is unable to view the mini map, and it closes if it is open when the restriction becomes active.

* '''''Allow/prevent knowing the current location''''' : @showloc=<y/n>
''Implemented in v1.12''
When prevented, the user is unable to know where they are : the world map is hidden, the parcel and region name on the top menubar are hidden, they can't create landmarks, nor buy the land, nor see what land they have just left after a teleport, nor see the location in the About box, and even system and object messages are obfuscated if they contain the name of the region and/or the name of the parcel. However, [[llOwnerSay]] calls are ''not'' obfuscated so radars ''will'' still work (and RL commands as well).

* '''''Force-Teleport the user''''' : @tpto:<X>/<Y>/<Z>=force (*)
''Implemented in v1.12''
This command forces the avatar to teleport to the indicated coordinates. Note that these coordinates are always '''global''', hence the script that calls this command will not be trivial. Moreso, if the destination contains a telehub or a landing point, the user will land there instead of the desired point. This is a SL limitation. Also keep in mind that @tpto is inhibited by @tploc=n, and from v1.15 and above, by @unsit too.

Here is a sample code to call that command properly :

<lsl>

// FORCE TELEPORT EXAMPLE
// Listens on channel 4 for local coordinates and a sim name
// and tells your viewer to teleport you there.
//
// By Marine Kelley 2008-08-26
// RLV version required : 1.12 and above
//
// HOW TO USE :
// * Create a script inside a box
// * Overwrite the contents of the script with this one
// * Wear the box
// * Say the destination coords Region/X/Y/Z on channel 4 :
// Example : /4 Help Island Public/128/128/50

key kRequestHandle; // UUID of the dataserver request
vector vLocalPos; // local position extracted from the

Init () {
kRequestHandle = NULL_KEY;
llListen (4, "", llGetOwner (), "");
}

default
{
state_entry () {
Init ();
}

on_rez(integer start_param) {
Init ();
}

listen(integer channel, string name, key id, string message) {
list tokens = llParseString2List (message, ["/"], []);
integer L = llGetListLength (tokens);

if (L==4) {
// Extract local X, Y and Z
vLocalPos.x = llList2Float (tokens, 1);
vLocalPos.y = llList2Float (tokens, 2);
vLocalPos.z = llList2Float (tokens, 3);

// Request info about the sim
kRequestHandle=llRequestSimulatorData (llList2String (tokens, 0), DATA_SIM_POS);
}
}

dataserver(key queryid, string data) {
if (queryid == kRequestHandle) {
// Parse the dataserver response (it is a vector cast to a string)
list tokens = llParseString2List (data, ["<", ",", ">"], []);
string pos_str = "";
vector global_pos;

// The coordinates given by the dataserver are the ones of the
// South-West corner of this sim
// => offset with the specified local coordinates
global_pos.x = llList2Float (tokens, 0);
global_pos.y = llList2Float (tokens, 1);
global_pos.z = llList2Float (tokens, 2);
global_pos += vLocalPos;

// Build the command
pos_str = (string)((integer)global_pos.x)
+"/"+(string)((integer)global_pos.y)
+"/"+(string)((integer)global_pos.z);
llOwnerSay ("Global position : "+(string)pos_str); // Debug purposes

// Fire !
llOwnerSay ("@tpto:"+pos_str+"=force");
}
}

}

</lsl>

* '''''Remove/add auto-accept teleport offers from a particular avatar''''' : "@accepttp[:<UUID>]=<rem/add>"
''Implemented in v1.15, slightly improved in v1.16''
Adding this rule will make the user automatically accept any teleport offer from the avatar which key is <UUID>, exactly like if that avatar was a Linden (no confirmation box, no message, no Cancel button). This rule does not supercede nor deprecate @tpto because the former teleports to someone, while the latter teleports to an arbitrary location. Attention : in v1.16 the UUID becomes optional, which means that @accepttp=add will force the user to accept teleport offers from anyone ! Use with caution !

* '''''Allow/prevent seeing the names of the people around''''' : @shownames=<y/n>
''Implemented in v1.12.2, added more dummy names in v1.16''
When prevented, the user is unable to know who is around. The names don't show on the screen, the names on the chat are replaced by "dummy" names such as "Someone", "A resident", the tooltips are hidden, the pie menu is almost useless so the user can't get the profile directly etc.

* '''''Allow/prevent seeing all the hovertexts''''' : @showhovertextall=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read any hovertext (2D text floating above some prims).

* '''''Allow/prevent seeing one hovertext in particular''''' : @showhovertext:<UUID>=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read the hovertext floating above the prim which id is UUID. This is made that way so that the restriction can be issued on an object, by another one (unlike @detach which can only set this restriction on itself).

* '''''Allow/prevent seeing the hovertexts on the HUD of the user''''' : @showhovertexthud=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read any hovertext showing over their HUD objects, but will be able to see the ones in-world.

* '''''Allow/prevent seeing the hovertexts in-world''''' : @showhovertextworld=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read any hovertext showing over their in-world objects, but will be able to see the ones over their HUD.

* '''''Allow/prevent flying''''' : @fly=<y/n>
''Implemented in v1.12.2''
When prevented, the user is unable to fly.

* '''''Get the UUID of the object the avatar is sitting on''''' : @getsitid=<channel_number>
''Implemented in v1.12.4''
Makes the viewer automatically answer the UUID of the object the avatar is currently sitting on, or NULL_KEY if they are not sitting.

* '''''Force rotate the avatar to a set direction''''' : @setrot:<angle_in_radians>=force
''Implemented in v1.17''
Forces the avatar to rotate towards a direction set by an angle in radians from the north. Note that this command is not very precise, nor will do anything if the action attempts to rotate the avatar by less than 10° (experimental value, it has been mentioned somewhere that 6° was the minimum). In other words, it is best to either check with a llGetRot() first, or to make the avatar turn twice, first 180° plus the desired angle, then by the angle we need. It isn't very elegant but it works.

* '''''Allow/prevent changing some debug settings''''' : @setdebug=<y/n>
''Implemented in v1.16''
When prevented, the user is unable to change some viewer debug settings (Advanced > Debug Settings). As most debug settings are either useless or critical to the user's experience, a whitelist approach is taken : only a few debug settings are locked, the others are always available and untouched. At the time of this writing, the allowed debug settings are :
** AvatarSex (0 : Female, 1 : Male) : gender of the avatar at creation.
** RenderResolutionDivisor (1 -> ...) : "blurriness" of the screen. Combined to clever @setenv commands, can simulate nice effects. Note: renderresolutiondivisor is a Windlight only option (Basic Shaders must be enabled in graphics preferences) and as such, is not available in v1.19.0.5 or older viewers.

* '''''Force change a debug setting''''' : @setdebug_<setting>:<value>=force (*)
''Implemented in v1.16''
Forces the viewer to change a particular debug setting and set it to <value>. This command is actually a package of many sub-commands, that are regrouped under "@setdebug_...", for instance "@setdebug_avatarsex:0=force", "@setdebug_renderresolutiondivisor:64=force" etc.

See the list of allowed debug settings in the @setdebug command hereabove.

* '''''Get the value of a debug setting''''' : @getdebug_<setting>=<channel_number>
''Implemented in v1.16''
Makes the viewer automatically answer the value of a debug setting, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is the value that has been set with the <setting> part of the matching @setdebug command, or by hand.

See the list of allowed debug settings in the @setdebug command hereabove.

* '''''Allow/prevent changing the environment settings''''' : @setenv=<y/n>
''Implemented in v1.14''
When prevented, the user is unable to change the viewer environment settings (World > Environment Settings > Sunrise/Midday/Sunset/Midnight/Revert to region default/Environment editor are all locked out).

* '''''Force change an environment setting''''' : @setenv_<setting>:<value>=force (*)
''Implemented in v1.14''
Forces the viewer to change a particular environment setting (time of day or Windlight) and set it to <value>. This command is actually a package of many sub-commands, that are regrouped under "@setenv_...", for instance "@setenv_daytime:0.5=force", "@setenv_bluehorizonr:0.21=force" etc.

This command (like any other "force" command) is silently discarded if the corresponding restriction has been set, here "@setenv", but in this case the restriction is ignored if the change is issued from the object that has created it. In other words, a collar can restrict environment changes, yet force a change by itself, while another object could not do it until the collar lifts the restriction.

Although a range is specified for every value, no check is made in the viewer so a script can do what the UI can't do, for interesting effects. Use at your own risk, though. The ranges indicated here are merely the ones available on the sliders on the Environment Editor, for reference.

Each particular sub-command works as follows (the names are chosen to be as close to the Windlight panels of the viewer as possible) :

{| border="1" cellpadding="5"
| '''@setenv_XXX:<value>=force where XXX is...''' || '''<value> range''' || '''Sets...'''
|-
| daytime || 0.0-1.0 and <0 || Time of day (sunrise:0.25, midday:0.567, sunset:0.75, midnight:0.0, set back to region default:<0). '''Attention, resets all other Windlight parameters'''
|-
| preset || String || A Preset environment, e.g. Gelatto, Foggy. '''Attention, loading a Preset is heavy on the viewer and can slow it down for a short while, don't do it every second'''
|-
| ambientr || 0.0-1.0 || Ambient light, Red channel
|-
| ambientg || 0.0-1.0 || Ambient light, Green channel
|-
| ambientb || 0.0-1.0 || Ambient light, Blue channel
|-
| ambienti || 0.0-1.0 || Ambient light, Intensity
|-
| bluedensityr || 0.0-1.0 || Blue Density, Red channel
|-
| bluedensityg || 0.0-1.0 || Blue Density, Green channel
|-
| bluedensityb || 0.0-1.0 || Blue Density, Blue channel
|-
| bluedensityi || 0.0-1.0 || Blue Density, Intensity
|-
| bluehorizonr || 0.0-1.0 || Blue Horizon, Red channel
|-
| bluehorizong || 0.0-1.0 || Blue Horizon, Green channel
|-
| bluehorizonb || 0.0-1.0 || Blue Horizon, Blue channel
|-
| bluehorizoni || 0.0-1.0 || Blue Horizon, Intensity
|-
| cloudcolorr || 0.0-1.0 || Cloud color, Red channel
|-
| cloudcolorg || 0.0-1.0 || Cloud color, Green channel
|-
| cloudcolorb || 0.0-1.0 || Cloud color, Blue channel
|-
| cloudcolori || 0.0-1.0 || Cloud color, Intensity
|-
| cloudcoverage || 0.0-1.0 || Cloud coverage
|-
| cloudx || 0.0-1.0 || Cloud offset X
|-
| cloudy || 0.0-1.0 || Cloud offset Y
|-
| cloudd || 0.0-1.0 || Cloud density
|-
| clouddetailx || 0.0-1.0 || Cloud detail X
|-
| clouddetaily || 0.0-1.0 || Cloud detail Y
|-
| clouddetaild || 0.0-1.0 || Cloud detail density
|-
| cloudscale || 0.0-1.0 || Cloud scale
|-
| cloudscrollx || 0.0-1.0 || Cloud scroll X
|-
| cloudscrolly || 0.0-1.0 || Cloud scroll Y
|-
| densitymultiplier || 0.0-0.9 || Density multiplier of the fog
|-
| distancemultiplier || 0.0-100.0 || Distance multiplier of the fog
|-
| eastangle || 0.0-1.0 || Position of the east, 0.0 is normal
|-
| hazedensity || 0.0-1.0 || Density of the haze
|-
| hazehorizon || 0.0-1.0 || Haze at the horizon
|-
| maxaltitude || 0.0-4000.0 || Maximum altitude of the fog
|-
| scenegamma || 0.0-10.0 || Overall gamma, 1.0 is normal
|-
| starbrightness|| 0.0-2.0 || Brightness of the stars
|-
| sunglowfocus || 0.0-0.5 || Focus of the glow of the sun
|-
| sunglowsize || 1.0-2.0 || Size of the glow of the sun
|-
| sunmooncolorr || 0.0-1.0 || Sun and moon, Red channel
|-
| sunmooncolorg || 0.0-1.0 || Sun and moon, Green channel
|-
| sunmooncolorb || 0.0-1.0 || Sun and moon, Blue channel
|-
| sunmooncolori || 0.0-1.0 || Sun and moon, Intensity
|-
| sunmoonposition || 0.0-1.0 || Position of the sun/moon, different from "daytime", '''use this to set the apparent sunlight after loading a Preset'''
|}

Note: from the above settings, only the "daytime" one is supported by v1.19.0 (or older) viewers implementing RestrainedLove v1.14 and later. The other settings are ignored. This is because these viewers do not implement the Windlight renderer.

(*) Silently discarded if the user is prevented from doing so by the corresponding restriction. This is on purpose.
Ex : Force detach won't work if the object is undetachable. Force undress won't work if the user is prevented from undressing.

* '''''Get the value of an environment setting''''' : @getenv_<setting>=<channel_number>
''Implemented in v1.15''
Makes the viewer automatically answer the value of an environment setting, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is the value that has been set with the <setting> part of the matching @setenv command, or by hand. See the table hereabove for a list of settings. 
Note: only @getenv_daytime is supported by v1.19.0 (or older, i.e. non Windlight) viewers implementing RestrainedLove v1.15 and later.

==Important note about the global behaviours such as sendchat==
Such behaviours are global, which means they don't depend on a particular object. However, they are triggered by objects with a set [[UUID]] which can change, and several objects can add the same behaviour, which will be stored several times as the [[UUID]]s are different.

This has a nice side effect : when wearing 2 locked devices that prevent chat, it is necessary to unlock them both to be able to chat again. But it has a nasty side effect, too : if the item changes [[UUID]] (for instance it was derezzed and rezzed again), and it doesn't allow chat beforehand, then the user will have to wait a short moment because the rule stays "orphaned" (its [[UUID]] is defunct) until the '''garbage collector''' kicks in.

Please note : Since 1.16.1 any locked object that is kicked off by any mean (llAttachToAvatar for example) will be reattached automatically by the viewer after 5 seconds. This means that calling @clear on detaching will actually unlock the object, which will have to be relocked after being reattached. It is therefore not recommended anymore to call @clear on detach, as opposed to pre-1.16.1 versions.

==Shared Folders==

Since v1.11, the viewer can "share" some of your items with scripts in world in order to let them force you to attach, detach and list what you have shared.

"Share" does NOT mean they will be taken by other people if they want to (some of the items may be no-transfer anyway), but only that they can force YOU to wear/unwear them at will through the use of a script YOUR restraints contain. They will remain in your inventory.

To do this :
* Create a folder named "#RLV" (without the quotes) directly under "My Inventory" (right-click on "My Inventory", select "New Folder"). We'll call this folder the "shared root".
* Move a folder containing restraints or other attachments directly into this new folder.
* Wear the contents of that folder, that's it !

So it would look like this :

My Inventory
|- #RLV
| |- cuffs
| | |- left cuff (l forearm) (no copy)
| | \- right cuff (r forearm) (no copy)
| \- gag
| \- gag (mouth) (no copy)
|- Animations
|- Body Parts
.
.
.

For example : If you're owning a set of RR Straps and want to share them, just move the folder "Straps BOXED" under the shared root.

Either wear all the items of the folders you have just moved (one folder at a time !) or rename your items yourself, so that each item name contains the name of the target attachment point. For example : "left cuff (l forearm)", "right ankle cuff (r lower leg)". Please note that no-modify items are a bit more complex to share, because they cannot be renamed either by you or by the viewer. More on that below.

The attachment point name is the same as the one you find in the "Attach To" menu of your inventory, and is case insensitive (for example : "chest", "skull", "stomach", "left ear", "r upper arm"...). If you wear the item without renaming it first it will be renamed automatically, but only if it is in a shared folder, and does not contain any attachment point name already, and is mod. If you want to wear it on another attachment point, you'll need to rename it by hand first.

Pieces of clothing are treated exactly the same way (in fact they can even be put in the folder of a set of restraints and be worn with the same command). Shoes, for instance, are a good example of mixed outfits : some attachments and the Shoes layer. Clothes are NOT renamed automatically when worn, since their very type decides where they are to be worn (skirt, jacket, undershirt...).

HOW TO SHARE NO-MODIFY ITEMS :
As you already know, no-mod items cannot be renamed so the technique is a bit more complex. Create a sub-folder inside the outfit folder (such as "cuffs" in the example above), put ONE no-modify item in it. When wearing the object, you'll see the folder itself be renamed (that's why you must not put more than one object inside it). So if your outfit contains several no-mod objects, you'll need to create as many folders and put the no-mod objects in them, one in each folder.

Example with no-modify shoes :

My Inventory
|- #RLV
| \- shoes
| |- left shoe (left foot)
| | \- left shoe (no modify) (no transfer) <-- no-mod object
| |- right shoe (right foot)
| | \- right shoe (no modify) (no transfer) <-- no-mod object
| \- shoe base (no modify) (no transfer) <-- this is not an object
|- Animations
|- Body Parts
.
.
.

GOTCHAS :
* Do NOT put a comma (',') in the name of the folders under the shared root or it would screw the list up.
* Don't forget to rename the items in the shared folders (or to wear these items at least once to have them be renamed automatically) or the force attach command will appear to do nothing at all.
* Avoid cluttering the shared root with many folders, since some scripts may rely on the list they got with the @getinv command and chat messages are limited to 1023 characters. Choose wisely, and use short names. But with 9 characters per folder name average, you can expect to have about 100 folders available.
* Remember to put no-modify items in sub-folders, one each, so their names can be used by the viewer do find out where to attach them. They can't be shared like modify items since they can't be renamed, and the outfit folder itself will not be renamed (since it contains several items).

'''''Accept sub-folders given via llGiveInventoryList() into the shared folder''''' :

Starting with RestrainedLove v1.16.2, you may give a list of items to a victim and have them stored as a sub-folder inside the #RLV folder (thus allowing you to @attach the given items later).

Issuing a llGiveInventoryList(victim_id, "#RLV/~subfolder_name", list_of_stuff) command in a script makes a standard Keep/Discard/Mute dialog appear in the viewer of the victim (the avatar which key is victim_id).

Should the victim accept the offer, the list_of_stuff items are put into a new sub-folder of the #RLV folder. The name of this sub-folder is "~subfolder_name" (it is the scripter's responsibility to use unique sub-folder names: if the name is the same as an existing sub-folder, two sub-folders with the same name will appear in the #RLV folder).

Note that the tilde character *must* be used as the first character for the name of the sub-folder (this is so that the victim can easily spot any sub-folder given to them in this way, and so that such sub-folder names appear last in the #RLV folder).

Note also that this feature may be disabled by the user, (by setting the RestrainedLoveForbidGiveToRLV debug setting to TRUE): in this case the given items are put into a folder named "#RLV/~subfolder_name" at the root of the inventory instead of inside the #RLV folder.

Since the user may either refuse the offer or have the feature disabled in their viewer, and since SL may take quite some time to perform the actual transfer of the objects on laggy days, you must check that the given folder is present (with @getinv), before attempting to @attach the given objects.

==For your information==
Here is how it works internally, for a better understanding of the gotchas you may encounter :
* Each command is parsed into a '''Behaviour''' (ex: "remoutfit"), an '''Option''' (ex: "shirt") and a '''Param''' (ex: "force") and comes from an [[UUID]] (the unique identifier of the emitting object).

* There are two types of commands : '''one-shot''' commands (those which Param is "force" and those which Param is a number such as the channel number of a "version" call) and '''rules''' (those which Param is "y", "n", "add" or "rem"). "clear" is special but can be seen as a one-shot command.

* Parameters "n" and "add" are '''exactly equal''' and are treated '''exactly the same way''', they are just '''synonyms'''. Same goes for "y" and "rem". The only purpose is to distinguish rules ("sendchannel=n") from exceptions ("sendchannel:8=add") in a script for clarity.

* Rules are stored inside a table linking the [[UUID]] of the emitter to the rule itself. They are '''added''' when receiving a "n"/"add" Param, and '''removed''' when receiving a "y"/"rem" Param.
If '''''UUID1''''' is a collar and '''''UUID2''''' is a gag :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

Those two rules mean that the user cannot send IMs except to their keyholder, and cannot TP at all. Those two items are not detachable. Now if the collar sends "@sendim=n", the table becomes :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp, sendim

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

If it sends "@sendim=n" a second time nothing changes, as there is a check for its existence prior to adding it. If the gag is unlocked and detached, either it sends a "@clear" or the garbage collector kicks in so the rules linked to '''''UUID2''''' disappear. However, the avatar is still unable to send IMs even to their keyholder, as the exception has disappeared as well. This is because rules linked to one object don't conflict with rules linked to another one.

* One-shot commands, on the other hand, are executed on-the-fly and are not stored.

* When logging on, the avatar stays non-operational (cannot chat, cannot move) for some time, while the user sees the progress bar. However, worn scripted objects [[rez]] in the meantime and start sending rules and commands before the viewer can execute them. Therefore it stores them in a buffer and executes them only when the user is given controls (when the progress bar disappears).

* The viewer periodically (every N seconds) checks all its rules and removes the ones linked to an [[UUID]] that does not exist around anymore ("garbage collector"). This means that rules issued by an '''unworn''' owned object will be discarded as soon as the avatar [[teleports]] elsewhere.

[[Category:Third Party Client]]
[[Category:RestrainedLove]]

User:Batche Manen

2010-07-12T11:53:12Z

Batche Manen: :3

Om nom nom. :3

LSL Protocol/RestrainedLoveAPI

2010-07-12T11:52:13Z

Batche Manen: Corrected the @recvim exception header claiming it added exceptions to the "chat message receiving prevention"

{{LSL Header|ml=*}}
=Restrained Love viewer v1.23 Specification=

By [[User:Marine Kelley|Marine Kelley]]

==Audience==

This document is for people who wish to modify or create their own [[LSL]] scripts to use the features of the [http://realrestraint.blogspot.com RestrainedLove viewer]. It does not explain [[LSL]] concepts such as messages and events, nor universal concepts such as [[UUID]]s.

This document contains the specification for RestrainedLove viewer itself. If you need information about the RestrainedLove viewer relay(RLV relay), please see the [[LSL_Protocol/Restrained_Love_Relay/Specification|RLV relay specification]]

==Introduction==

The [http://realrestraint.blogspot.com RestrainedLove viewer] executes certain behaviours when receiving special messages from scripts in-world. These messages are mostly calls to the [[llOwnerSay]]() [[LSL]] function.

==Architecture==

The [http://realrestraint.blogspot.com RestrainedLove viewer] intercepts every [[llOwnerSay]] message sent to the viewer. Lines that begin with an at-sign (''''@'''') are parsed as RLV commands. Other lines are forwarded to the user in the Local Chat window, as usual. For instance, a call to [[llOwnerSay]] ("@detach=n") sends the ''detach'' command with parameter ''n'' to the viewer on behalf of the object running the script.

The syntax of a message is:

: <code>@<command1>[:option1]=<param1>,<command2>[:option2]=<param2>,...,<commandN>[:optionN]=<paramN></code>

Note that there is only one '@' sign, placed at the beginning of the message. The viewer interprets this as "this entire [[llOwnerSay]]() message contains one or more commands to execute". For documentation purposes, commands are always presented with the leading ''''@''''. However, it is an error to put the ''''@'''' in front of each command within a multi-command message, and the the subsequent commands will fail.

: Historical Note: Prior to Version '''1.10''', RLV only allowed one command per message. Version '''1.10''' added the ability to include multiple commands in one message, to avoid spamming users who are not using this viewer.

If at least one command fails (e.g. a typo), the viewer says "... fails command : ... " and prints the entire message. However, correct commands are still parsed and executed, only the incorrect ones are ignored.

Many of these commands determine the subsequent ''behaviour'' of the object or avatar. For example, the '''@detach=n''' command locks the given object, making it undetachable. Some commands set ''global behaviours'', which aren't limited to the object sending the command. For example, the '''@sendchat=n''' command will prevent the user from talking in local chat.

'''NOTE''' about commands with exceptions, such as @sendim or @sendchannel... @(rule):(exception)=n actually (and counter-intuitively) '''adds an exception''' for the given rule. @sendchannel:1=n, for example, '''allows''' chat on channel 1. This has been the source of at least two scripters' confusion. =add (which means the same as =n) and =rem (which means =y) exist for the purpose of adding and removing exceptions, respectively. Use them.

{{hint|mode=warning|desc=These behaviours are '''not''' persistent between sessions. Since an object changes its [[UUID]] every time it [[rez]]zes, the object ''must'' resend its status (undetachable, preventing IMs...) in the [[on_rez]]() event as well as whenever it changes its status.}}

==List of commands==

'''Note:''' These commands are not case-sensitive but are spacing-sensitive. In other words, "@detach = n" will '''not''' work.

'''Notation convention:''' Parameters in [square brackets] are optional parameters that can be omitted. The pipe | and slash / signs separate options from which one must be used. <angle brackets> enclose parameters that are mandatory.

* '''''Automated version checking''''' : "@version=<channel_number>"
''Implemented in v1.0b''
Makes the viewer automatically say its version immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

'''Warning''' : when logging in, the [[on_rez]] event of all the attachments occurs way before the avatar can actually send chat messages (about half the way through the login progress bar). This means the timeout should be long enough, like 30 seconds to one minute in order to receive the automatic reply from the viewer.

'''Warning 2''' : On 02/22/2010, Linden Lab has released their Third Party Viewer policy which forbids using the term "Life" in the name of Third Party Viewers. Therefore "Restrained Life" had to be renamed to "Restrained Love". However, for compatibility purposes, this @version command still works and will keep working, however you are encouraged to '''not''' use it in new scripts, and to '''not''' show the terms "Restrained Life" to the user anywhere. For new scripts, please use @versionnew below instead.

* '''''Automated version checking''''' : "@versionnew=<channel_number>"
''Implemented in v1.23''
Makes the viewer automatically say its version immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

This command is the successor of @version and replaces it, although @version is kept for ascending compatibility purposes. It returns "RestrainedLove viewer v... (SL ...)" ("RestrainedLove" is in one word).

'''Warning''' : when logging in, the [[on_rez]] event of all the attachments occurs way before the avatar can actually send chat messages (about half the way through the login progress bar). This means the timeout should be long enough, like 30 seconds to one minute in order to receive the automatic reply from the viewer.

* '''''Automated version number checking''''' : "@versionnum=<channel_number>"
''Implemented in v1.21''
Makes the viewer automatically say its version number immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. This command is less cumbersome than @version, since the script does not have to parse the response, it gets the version number immediately.

The version number is a mere integer that represents the version of the viewer. If the version is X.Y.Z.P, then the number will be X.10^6 + Y.10^4 + Z.10^2 + P. For example, 1.21.1 would be 1210100.

* '''''Automated version checking, second way''''' : llGetAgentLanguage (key id) '''''DEPRECATED: DO NOT USE !'''''
''Implemented in v1.16''
When calling this LSL function, the result is obtained immediately (no need to use a listener and a timer), is exactly equal to the one given by "@version" and cannot be hidden by the user. This string takes the place of the language returned by the regular SL viewer, which could answer values like "en-us", "fr", "ko" etc. Or nothing at all, if the user chose to hide their language setting. Being optional in the regular viewer, it cannot be trusted by a script, so "hijacking" this feature for the much more useful synchronous version checking in the RLV makes sense. IMPORTANT NOTE: this feature cannot be implemented in viewers prior to v1.21, even when they do implement RestrainedLove v1.16, so make sure you do fall back to the @version method whenever llGetAgentLanguage() returns an empty string. ALSO NOTE: In RestrainedLove 1.16, llGetAgentLanguage() will return an empty string when called by on_rez during login unless the call is delayed by several seconds (how many seconds may vary). FINAL NOTE: This feature was removed from v1.16.1 (and v1.16b, for the Cool SL Viewer).

* '''''Manual version checking''''' : "@version"
''Implemented in v1.0a''
This command must be sent in IM from an avatar to the user (will not work from objects). The viewer automatically answers its version to the sender in IM, but neither the message nor the answer appears in the user's IM window, so it's totally stealthy.

* '''''Render an object detachable/nondetachable''''' : "@detach=<y/n>"
''Implemented in v1.0a''
When called with the "n" option, the object sending this message (which must be an attachment) will be made nondetachable. It can be detached again when the "y" option is called.

* '''''Unlock/Lock an attachment point''''' : "@detach:<attach_point_name>=<y/n>"
''Implemented in v1.20''
When called with the "n" option, the attachment point of name <attach_point_name> will be locked either full (if it is occupied by an object at that time) or empty (if not). Any object that is occupying this point when the restriction is issued will be considered as undetachable, exactly like if it had issued a "@detach=n" command itself. If the point is empty it will stay that way, no item will be able to be attached there, and llAttachToAvatar() calls will fail (the object will be attached, then detached right away).

* '''''Unlock/Lock an attachment point empty''''' : "@addattach[:<attach_point_name>]=<y/n>"
''Implemented in v1.22''
When called with the "n" option, the attachment point of name <attach_point_name> will be locked empty. Any object that is occupying this point when the restriction is issued can be detached, but nothing can be attached there. If the point is empty it will stay that way, no item will be able to be attached there, and llAttachToAvatar() calls will fail (the object will be attached, then detached right away). If <attach_point_name> is not specified, then all the attachment points will be concerned. This command is the counterpart to @addoutfit, for attachments.

* '''''Unlock/Lock an attachment point full''''' : "@remattach[:<attach_point_name>]=<y/n>"
''Implemented in v1.22''
When called with the "n" option, the attachment point of name <attach_point_name> will be locked full. Any object that is occupying this point when the restriction is issued will be rendered undetachable. If the point is empty it will allow the user to wear something, but then that object will become undetachable too, no item will be able to replace it, and llAttachToAvatar() calls will fail (the object will be attached, then detached right away). If <attach_point_name> is not specified, then all the attachment points will be concerned. This command is the counterpart to @remoutfit, for attachments.

* '''''Allow/deny the "Wear" contextual menu''''' : "@defaultwear=<y/n>
''Implemented in v1.21''
When allowed, the user is always able to choose the "Wear"command on the contextual menu of the inventory, even when an object is locked on their avatar. This holds the risk of kicking that locked object, but it will be reattached automatically within 5 seconds (and successive locked objects every second until there is nothing left to reattach). However some objects may be scripted in a way that they drop their restrictions when detached, or simply not take into account the fact that even a locked object can be detached when using the RLV.

Therefore, using this command with the "n" option will suppress this comman, but it will still be available for objects that contain the target attachment point in their name or in the name of their parent folder, exactly like pre-1.21 RLV. This is a little less user-friendly but more secure when it comes to make sure no locked object may be detached accidentally.

* '''''Start/stop notifications on a private channel''''' : "@notify:<channel_number>[;word]=<rem/add>"
''Implemented in v1.20''
Makes the viewer automatically repeat any restriction it adds or removes on the specified channel, or only the restrictions which name contains the word specified after the semicolon (";") character. The response on the private channel <channel_number> is preceded with a slash ("/") to avoid making the avatar send commands to other scripts without knowing it, and followed by an equal sign ("=") and "n" or "y" according to whether the restriction is applied or lifted respectively. The "@clear" command will not add an equal sign. There is no way to know what object issued the restriction or lifted it, to avoid disclosing too much information about foreign scripts. It does not repeat one-shot commands either (force commands). For example, "@notify:2222;detach=add" will send "/detach=n" whenever an object is locked, and "/detach=y" whenever an object is unlocked, on channel 2222 to which the script will listen to.

* '''''Allow/prevent sending chat messages''''' : "@sendchat=<y/n>"
''Implemented in v1.0b''
When prevented, everything typed on [[channel]] 0 will be discarded. However, emotes and messages beginning with a slash ('/') will go through, truncated to strings of 30 and 15 characters long respectively (likely to change later). Messages with special signs like ()"-*=_^ are prohibited, and will be discarded. When a period ('.') is present, the rest of the message is discarded.

* '''''Remove/add an exception to the emote truncation above''''' : "@emote=<rem/add>"
''Implemented in v1.01''
When adding this exception, the emotes are not truncated anymore (however, special signs will still discard the message).

* '''''Allow/prevent shouting''''' : "@chatshout=<y/n>"
''Implemented in v1.15''
When prevented, the avatar will chat normally even when the user tries to shout. This does not change the message in any way, only its range.

* '''''Allow/prevent chatting at normal volume''''' : "@chatnormal=<y/n>"
''Implemented in v1.15''
When prevented, the avatar will whisper even when the user tries to shout or chat normally. This does not change the message in any way, only its range.

* '''''Allow/prevent whispering''''' : "@chatwhisper=<y/n>"
''Implemented in v1.15''
When prevented, the avatar will chat normally even when the user tries to whisper. This does not change the message in any way, only its range.

* '''''Redirect public chat to private channels''''' : "@redirchat:<channel_number>=<rem/add>"
''Implemented in v1.16''
When active, this restriction redirects whatever the user says on the public channel ("/0") to the private channel provided in the option field. If several redirections are issued, the chat message will be redirected to each channel. It does not apply to emotes, and will not trigger any animation (typing start, typing stop, nodding) when talking. This restriction does not supercede @sendchannel.
'''NOTE:''' As of RLV v1.22.1 / RLVa 1.1.0 @redirchat also truncates emotes on channel 0. It's not clear if this is a bug or a missing note in the API. An additional @emote=add works around this side-effect. '''Addendum by {{User|Henri Beauchamp}}''': as someone who worked together with Marine on the reference implementation, this is '''clearly''' a bug and plain unintended. It appeared during some code refactoring, but as always specified before in the API, @redirchat should *not* affect emotes at all. If you want to affect emotes as well, please use @rediremote. This bug was fixed in the [http://sldev.free.fr/ Cool VL Viewer].

* '''''Redirect public emotes to private channels''''' : "@rediremote:<channel_number>=<rem/add>"
''Implemented in v1.19''
When active, this restriction redirects whatever emote the user says on the public channel ("/0") to the private channel provided in the option field. If several redirections are issued, the emote will be redirected to each channel.

* '''''Allow/prevent sending instant messages''''' : "@sendim=<y/n>"
''Implemented in v1.0b''
When prevented, everything typed in IM will be discarded and a bogus message will be sent to the receiver instead.

* '''''Allow/prevent sending instant messages, secure way''''' : "@sendim_sec=<y/n>"
''Implemented in v1.21''
When prevented, everything typed in IM will be discarded and a bogus message will be sent to the receiver instead. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the instant message sending prevention''''' : "@sendim:<UUID>=<rem/add>"
''Implemented in v1.01''
When adding an exception, the user can send IMs to the receiver whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving chat messages''''' : "@recvchat=<y/n>"
''Implemented in v1.0b''
When prevented, everything heard in public chat will be discarded except emotes.

* '''''Allow/prevent receiving chat messages, secure way''''' : "@recvchat_sec=<y/n>"
''Implemented in v1.21''
When prevented, everything heard in public chat will be discarded except emotes. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the chat message receiving prevention''''' : "@recvchat:<UUID>=<rem/add>"
''Implemented in v1.01''
When adding an exception, the user can hear chat messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent seeing emotes''''' : "@recvemote=<y/n>"
''Implemented in v1.19''
When prevented, every emote seen in public chat will be discarded.

* '''''Allow/prevent seeing emotes, secure way''''' : "@recvemote_sec=<y/n>"
''Implemented in v1.21''
When prevented, every emote seen in public chat will be discarded. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the emote seeing prevention''''' : "@recvemote:<UUID>=<rem/add>"
''Implemented in v1.19''
When adding an exception, the user can see emotes from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving instant messages''''' : "@recvim=<y/n>"
''Implemented in v1.0b''
When prevented, every incoming IM will be discarded and the sender will be notified that the user cannot read them.

* '''''Allow/prevent receiving instant messages, secure way''''' : "@recvim_sec=<y/n>"
''Implemented in v1.21''
When prevented, every incoming IM will be discarded and the sender will be notified that the user cannot read them. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the instant message receiving prevention''''' : "@recvim:<UUID>=<rem/add>"
''Implemented in v1.01''
When adding an exception, the user can read instant messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent teleporting to a landmark''''' : "@tplm=<y/n>"
''Implemented in v1.0''
When prevented, the user cannot use a [[landmark]], pick or any other preset location to [[teleport]] there.

* '''''Allow/prevent teleporting to a location''''' : "@tploc=<y/n>"
''Implemented in v1.0''
When prevented, the user cannot use [[teleport]] to a coordinate by using the [[map]] and such.

* '''''Allow/prevent teleporting by a friend''''' : "@tplure=<y/n>"
''Implemented in v1.0''
When prevented, the user automatically discards any [[teleport]] offer, and the avatar who initiated the offer is notified.

* '''''Allow/prevent teleporting by a friend, secure way''''' : "@tplure_sec=<y/n>"
''Implemented in v1.21''
When prevented, the user automatically discards any [[teleport]] offer, and the avatar who initiated the offer is notified. This particular command accepts exceptions issued from the same object only, opposed to the non-secure way that accepts exceptions from any object.

* '''''Remove/add exceptions to the friend teleport prevention''''' : "@tplure:<UUID>=<rem/add>"
''Implemented in v1.0''
When adding an exception, the user can be teleported by the avatar whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Unlimit/limit sit-tp''''' : "@sittp=<y/n>"
''Implemented in v1.0''
When limited, the avatar cannot sit on a [[prim]] unless it is closer than 1.5 m. This allows cages to be secure, preventing the avatar from warping its position through the walls (unless the prim is too close).

* '''''Allow/deny permissive exceptions''''' : "@permissive=<y/n>"
''Implemented in v1.21''
When denied, all restrictions turn into their "secure" counterparts (if any). This means an exception to a restriction will be ignored if it is not issued by the same object that issued the restriction. Using non-secure restrictions (the original ones, like @sendim, @recvim etc) and not using @permissive allow the avatar to benefit from exceptions issued by different objects.

'''Warning''' : Using this command (or any secure version of the original commands) may silently discard exceptions issued by different objects (it is even its primary purpose), hence some products may appear to cease working while this restriction is in effect. For example, a product that allows the avatar to always be able to send IMs a particular friend will not be able to overcome a @sendim_sec or a @permissive command sent by another object, and will look like it is broken. Therefore, use with caution and make the user aware of how secure your own product is !

* '''''Clear all the rules tied to an object''''' : "@clear"
''Implemented in v1.0a, but working only since v1.04a''
This command clears all the restrictions and exceptions tied to a particular [[UUID]].

'''Warning''' : when triggered on detach by default, this might prevent the automatic reattach when @defaultwear is active, as @clear will also lift @detach=n, thus the viewer thinks the item that gets detached by accident by a default-wear-action is unlocked and will not reattach it.

Possible workarounds:
::* only lift the exact restrictions you added with @clear=<pattern>
::* only trigger @clear on detach when you are sure the attachment is not locked
::* don't trigger @clear on detach at all and wait for the viewer to lift the set restrictions

* '''''Clear a subset of the rules tied to an object''''' : "@clear=<string>"
''Implemented in v1.0a, but working only since v1.04a''
This command clears all the restrictions and exceptions tied to a particular [[UUID]] which name contains <string>. A good example would be "@clear=tp" which clears all the [[teleport]] restrictions and exceptions tied to that object, whereas "@clear=tplure:" would only clear the exceptions to the "teleport-by-friend" restriction

* '''''Allow/prevent editing objects''''' : "@edit=<y/n>"
''Implemented in v1.03''
When prevented from editing and opening objects, the Build & Edit window will refuse to open.

* '''''Allow/prevent rezzing inventory''''' : "@rez=<y/n>"
''Implemented in v1.03''
When prevented from [[rez]]zing stuff, creating and deleting objects, drag-dropping from inventory and dropping attachments will fail.

* '''''Allow/prevent wearing clothes''''' : @addoutfit[:<part>]=<y/n>
''Implemented in v1.10, added skin hair and eyes in v1.10.1''
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin|eyes|hair|shape|alpha|tattoo
If part is not specified, prevents from wearing anything beyond what the avatar is already wearing.

'''Note:''' Since the release of Viewer 2.0 there are two new avatar skin layers: Tattoo and Avatar Transparency Mask. The alpha and tattoo layers will only be supported by RLV compliant viewers that implement the new Viewer 2.0 features.

* '''''Allow/prevent removing clothes''''' : @remoutfit[:<part>]=<y/n> (underpants and undershirt are kept for teens)
''Implemented in v1.10, added skin hair and eyes in v1.10.1''
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin|eyes|hair|shape|alpha|tattoo
If part is not specified, prevents from removing anything in what the avatar is wearing.

'''Note:''' Since the release of Viewer 2.0 there are two new avatar skin layers: Tattoo and Avatar Transparency Mask. The alpha and tattoo layers will only be supported by RLV compliant viewers that implement the new Viewer 2.0 features.

* '''''Force removing clothes''''' : @remoutfit[:<part>]=force (*) (teens can't be forced to remove underpants and undershirt)
''Implemented in v1.10''
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|alpha|tattoo
If part is not specified, removes everything.

'''Note:''' Since the release of Viewer 2.0 there are two new avatar skin layers: Tattoo and Avatar Transparency Mask. The alpha and tattoo layers will only be supported by RLV compliant viewers that implement the new Viewer 2.0 features.

'''Note:''' skin, shape, eyes and hair cannot be removed since they are body parts (and removing any would result in an unrezzed avatar).

* '''''Force removing attachments''''' : @detach[:attachpt]=force (*)
''Implemented in v1.10''
Where part is :
chest|skull|left shoulder|right shoulder|left hand|right hand|left foot|right foot|spine|
pelvis|mouth|chin|left ear|right ear|left eyeball|right eyeball|nose|r upper arm|r forearm|
l upper arm|l forearm|right hip|r upper leg|r lower leg|left hip|l upper leg|l lower leg|stomach|left pec|
right pec|center 2|top right|top|top left|center|bottom left|bottom|bottom right
If part is not specified, removes everything.

* '''''Force removing attachments (alias)''''' : @remattach[:attachpt]=force (*)
''Implemented in v1.22''
This command is an alias to @detach[:attachpt]=force (to keep things consistent).

* '''''Get the list of worn clothes''''' : @getoutfit[:part]=<channel_number>
''Implemented in v1.10, added skin hair and eyes in v1.10.1''
Makes the viewer automatically answer the current occupation of clothes layers as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
gloves,jacket,pants,shirt,shoes,skirt,socks,underpants,undershirt,skin,eyes,hair,shape
in that order.

If a part is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the part.
Ex 1 : @getoutfit=2222 => "0011000111" => avatar is wearing pants, shirt, underpants and undershirt, and of course a skin.
Ex 2 : @getoutfit:socks=2222 => "0" => the avatar is not wearing socks.

'''Note:''' For viewers that implement the new Viewer 2.0 features, the list is:

gloves,jacket,pants,shirt,shoes,skirt,socks,underpants,undershirt,skin,eyes,hair,shape,alpha,tattoo

* '''''Get the list of worn attachments''''' : @getattach[:attachpt]=<channel_number>
''Implemented in v1.10''
Makes the viewer automatically answer the current occupation of attachment points as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
none,chest,skull,left shoulder,right shoulder,left hand,right hand,left foot,right foot,spine,
pelvis,mouth,chin,left ear,right ear,left eyeball,right eyeball,nose,r upper arm,r forearm,
l upper arm,l forearm,right hip,r upper leg,r lower leg,left hip,l upper leg,l lower leg,stomach,left pec,
right pec,center 2,top right,top,top left,center,bottom left,bottom,bottom right
in that order.

If an attachment point is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the point.
Ex 1 : @getattach=2222 => "011000011010000000000000100100000000101" => avatar is wearing attachments on
chest, skull, left and right foot, pelvis, l and r lower leg, HUD bottom left and HUD bottom right.
Ex 2 : @getattach:chest=2222 => "1" => avatar is wearing something on the chest.

''Note'' : The first character ("none") is always '0', so the index of each attach point in the string is '''exactly equal''' to the corresponding ATTACH_* macro in LSL. For instance, the index 9 in the string is ATTACH_BACK (which means "spine"). Remember the indices start at zero.

* '''''Force the viewer to automatically accept attach and take control permission requests''''' : @acceptpermission=<rem/add>
''Implemented in v1.16''
Forces the avatar to automatically accept attach and take control permission requests. The dialog box doesn't even show up. This command does not supercede @denypermission, of course.

* '''''Allow/prevent accepting attach and take control permissions''''' : @denypermission=<rem/add>
''Implemented in v1.16, DEPRECATED in v1.16.2''
When prevented, all attach and take control permission requests are automatically declined, without even showing the dialog box. Due to the extreme annoyance it was making, and because locked objects automatically reattach themselves since v1.16.1, this command is NOW DEPRECATED, DON'T USE IT !

* '''''Allow/prevent using inventory''''' : @showinv=<y/n>
''Implemented in v1.10''
Forces the [[inventory]] windows to close and stay closed.

* '''''Allow/prevent reading notecards''''' : @viewnote=<y/n>
''Implemented in v1.10''
Prevents from opening [[notecards]] but does not close the ones already open.

* '''''Allow/prevent opening scripts''''' : @viewscript=<y/n>
''Implemented in v1.22''
Prevents from opening [[scripts]] but does not close the ones already open.

* '''''Allow/prevent opening textures''''' : @viewtexture=<y/n>
''Implemented in v1.22''
Prevents from opening [[textures]] (and snapshots) but does not close the ones already open.

* '''''Allow/prevent standing up''''' : @unsit=<y/n>
''Implemented in v1.10, modified in v1.15 to prevent teleporting as well''
Hides the Stand up button. From v1.15 it also prevents teleporting, which was a way to stand up.

* '''''Force sit on an object''''' : @sit:<UUID>=force (*)
''Implemented in v1.10''
Does not work if the user is prevented from sit-tping and further than 1.5 meters away, or when prevented from unsitting.

* '''''Force unsit''''' : @unsit=force (*)
''Implemented in v1.10''
Self-explanatory but for some reason it randomly fails, so don't rely on it for now. Further testing is needed.

* '''''Allow/prevent sitting down''''' : @sit=<y/n>
''Implemented in v1.16.2''
Prevents the user from sitting on anything, including with @sit:UUID=force.

* '''''Allow/prevent using any chat channel but certain channels''''' : @sendchannel[:<channel>]=<y/n>
''Implemented in v1.10''
Complimentary of @sendchat, this command prevents the user from sending messages on non-public [[channel]]s. If channel is specified, it becomes an exception to the aforementioned restriction. It does not prevent the viewer automatic replies like @version=nnnn, @getstatus=nnnn etc.

* '''''Allow/prevent using any chat channel but certain channels, secure way''''' : @sendchannel_sec[:<channel>]=<y/n>
''Implemented in v1.10''
Complimentary of @sendchat, this command prevents the user from sending messages on non-public [[channel]]s. If channel is specified, it becomes an exception to the aforementioned restriction. It does not prevent the viewer automatic replies like @version=nnnn, @getstatus=nnnn etc. This particular command only accepts exceptions issued from the same object, opposed to its non-secure version which accepts exceptions from any other object.

* '''''Get the list of restrictions the avatar is currently submitted to''''' : @getstatus[:<part_of_rule>]=<channel>
''Implemented in v1.10, slightly tweaked in v1.16''
Makes the viewer automatically answer the list of rules the avatar is currently under, only for the object containing the script issuing that command, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is a list of rules, separated by slashes ('/'). Attention : since v1.16 a slash is prepended at the beginning of the string. This does not confuse llParseString2List() calls, but does confuse llParseStringKeepNulls() calls !

This command is useful for people who write scripts that may conflict with other scripts in the same object (for instance : third-party plugins). Conflicts do not occur in different objects, that's why this command only applies to the object calling it.

<part_of_rule> is the name of a rule, or a part of it, useful if the script only needs to know about a certain restriction.

Example : If the avatar is under tploc, tplure, tplm and sittp, here is what the script would get :
@getstatus=2222 => tploc/tplure/tplm/sittp
@getstatus:sittp=2222 => sittp
@getstatus:tpl=2222 => tploc/tplure/tplm (because "tpl" is part of "tploc", "tplure" and "tplm" but not "sittp")

* '''''Get the list of all the restrictions the avatar is currently submitted to''''' : @getstatusall[:<part_of_rule>]=<channel>
''Implemented in v1.15, slightly tweaked in v1.16''
Makes the viewer automatically answer the list of rules the avatar is currently under, for all the objects regardless of their UUID, contrary to @getstatus, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is a list of rules, separated by slashes ('/'). Attention : since v1.16 a slash is prepended at the beginning of the string. This does not confuse llParseString2List() calls, but does confuse llParseStringKeepNulls() calls !

* '''''Get the list of shared folders in the avatar's inventory''''' : @getinv[:folder1/.../folderN]=<channel_number>
''Implemented in v1.11, added sub-folders in v1.13''
Makes the viewer automatically answer the list of folders contained into the folder named "#RLV" (if it exists), immediately on the chat channel number <channel_number> that the script can listen to. If folders are specified, it will give the list of sub-folders contained into the folder located at that path instead of the shared root (example : "@getinv:Restraints/Leather cuffs/Arms=2222"). Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The answer is a list of names, separated by commas (","). Folders which names begin with a dot (".") will be ignored.

* '''''Get the list of shared folders in the avatar's inventory, with information about worn items''''' : @getinvworn[:folder1/.../folderN]=<channel_number>
''Implemented in v1.15''
Makes the viewer automatically answer the list of folders contained into the folder named "#RLV" (if it exists), immediately on the chat channel number <channel_number> that the script can listen to. If folders are specified, it will give the list of sub-folders contained into the folder located at that path instead of the shared root (example : "@getinvworn:Restraints/Leather cuffs/Arms=2222"). Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The answer is a comma-separated list of names, each one followed with a pipe ("|") and two digits. The current folder is put in first position (as opposed to @getinv which does not show the current folder, obviously), but without a name, only the pipe and the two digits.

Object : "@getinvworn:Restraints/Leather cuffs=2222"
Viewer : "|02,Arms|30,Legs|10"

Folders which names begin with a dot (".") will be ignored. The two digits are calculated as follows :

First digit : Proportion of items worn in the corresponding folder (including no-mod items). In this example, the "3" of "30" means "all the items in the "Arms" folder are currently worn, while the "1" of "10" means "no item in the Legs folder is currently worn, but there are items to wear".

Second digit : Proportion of items globally worn in all the folders contained inside the corresponding folder. In this example, the "2" of "02" means "some items are worn in some of the folders contained into "Leather cuffs".

The digits, comprised between 0 and 3 included, have the following meaning :

* 0 : No item is present in that folder
* 1 : Some items are present in that folder, but none of them is worn
* 2 : Some items are present in that folder, and some of them are worn
* 3 : Some items are present in that folder, and all of them are worn

* '''''Get the path to a shared folder by giving a search criterion''''' : @findfolder:part1[&&...&&partN]=<channel_number>
''Implemented in v1.13.1''
Makes the viewer automatically answer the path to the first shared folder which name contains <part1> and <part2> and ... and <partN>, immediately on the chat channel number <channel_number> that the script can listen to. The search is in depth first, notice the separator which is "&&" like "and". Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. It does not take disabled folders into account (folders which name begins with a dot "."), nor folders which name begins with a tilde ("~"). The answer is a list of folders, separated by slashes ('/').

* '''''Force attach items contained inside a shared folder''''' : @attach:<folder1/.../folderN>=force (*)
''Implemented in v1.11, added no-mod items in v1.12, added sub-folders in v1.13''
Forces the viewer to attach every object and wear every piece of clothing contained inside the folder located at the specified path (which must be under "#RLV"). Objects names '''must''' contain the name of their target attachment point or they won't be attached. Each no-modify object '''must''' be contained inside a folder (one object per folder), which name contains the name of its target attachment point since it can't be renamed. Names cannot begin with a dot (".") since such folders are invisible to the scripts.

Attachment point names are the same as the ones contained into the "Attach To" submenu : "skull", "chest", "l forearm"...

Note : Folder names '''can''' contain slashes, and will be chosen in priority when able (for instance, if "@attach:Restraints/cuffs=force" is issued, the "Restraints/cuffs" folder will be chosen before a "cuffs" folder contained inside a "Restraints" parent folder.

* '''''Force attach items contained inside a shared folder, and its children recursively''''' : @attachall:<folder1/.../folderN>=force (*)
''Implemented in v1.15''
This command works exactly like @attach described hereabove, but also attaches whatever is contained into children folders.

* '''''Force detach items contained inside a shared folder''''' : @detach:<folder_name>=force (*)
''Implemented in v1.11''
Forces the viewer to detach every object and unwear every piece of clothing contained inside <folder_name>(which must be directly under "#RLV"). If "@detach" is used with an attachment point name (skull, pelvis... see above), it takes priority over this way of detaching since it is the same command.

* '''''Force detach items contained inside a shared folder, and its children recursively''''' : @detachall:<folder1/.../folderN>=force (*)
''Implemented in v1.15''
This command works exactly like @detach described hereabove, but also detaches whatever is contained into children folders.

* '''''Get the path to the shared folder containing a particular object/clothing''''' : @getpath[:<attachpt> or <clothing_layer>]=<channel_number>
''Implemented in v1.16''
Makes the viewer automatically answer the path to the shared folder containing the item that :
** issues this command if no option is set
** is attached on the attach point provided in the option field, ex : @getpath:spine=2222 => "Restraints/Collar"
** is worn on the clothing layer provided in the option field, ex : @getpath:pants=2222 => "Casual/Jeans/Tight"
Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. It does not take disabled folders into account (folders which name begins with a dot "."). The answer is a list of folders, separated by slashes ('/').

* '''''Force attach items contained into a shared folder that contains a particular object/clothing''''' : @attachthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with an @attach command (this saves a listener and a timeout).

* '''''Force attach items contained into a shared folder that contains a particular object/clothing, and its children folders''''' : @attachallthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with an @attachall command (this saves a listener and a timeout).

* '''''Force detach items contained into a shared folder that contains a particular object/clothing''''' : @detachthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with a @detach command (this saves a listener and a timeout).

* '''''Force detach items contained into a shared folder that contains a particular object/clothing, and its children folders''''' : @detachallthis[:<attachpt> or <clothing_layer>]=force (*)
''Implemented in v1.16''
This command is a shortcut for a @getpath followed with a @detachall command (this saves a listener and a timeout).

* '''''Force detach an item''''' : @detachme=force (*)
''Implemented in v1.16.2''
This command forces the object that issues it to detach itself from the avatar. It is there as a convenience to avoid a race condition when calling @clear then llDetachFromAvatar(), sometimes the object could detach itself before clearing its restrictions, making it reattach automatically after a while. With this command one can issue a @clear,detachme=force to be sure @clear is executed first.

* '''''Allow/prevent touching objects located further than 1.5 meters away from the avatar''''' : @fartouch=<y/n>
''Implemented in v1.11''
When prevented, the avatar is unable to touch/grab objects from more than 1.5 m away, this command makes restraints more realistic since the avatar litterally has to press against the object in order to click on it.

* '''''Allow/prevent viewing the world map''''' : @showworldmap=<y/n>
''Implemented in v1.11''
When prevented, the avatar is unable to view the world map, and it closes if it is open when the restriction becomes active.

* '''''Allow/prevent viewing the mini map''''' : @showminimap=<y/n>
''Implemented in v1.11''
When prevented, the avatar is unable to view the mini map, and it closes if it is open when the restriction becomes active.

* '''''Allow/prevent knowing the current location''''' : @showloc=<y/n>
''Implemented in v1.12''
When prevented, the user is unable to know where they are : the world map is hidden, the parcel and region name on the top menubar are hidden, they can't create landmarks, nor buy the land, nor see what land they have just left after a teleport, nor see the location in the About box, and even system and object messages are obfuscated if they contain the name of the region and/or the name of the parcel. However, [[llOwnerSay]] calls are ''not'' obfuscated so radars ''will'' still work (and RL commands as well).

* '''''Force-Teleport the user''''' : @tpto:<X>/<Y>/<Z>=force (*)
''Implemented in v1.12''
This command forces the avatar to teleport to the indicated coordinates. Note that these coordinates are always '''global''', hence the script that calls this command will not be trivial. Moreso, if the destination contains a telehub or a landing point, the user will land there instead of the desired point. This is a SL limitation. Also keep in mind that @tpto is inhibited by @tploc=n, and from v1.15 and above, by @unsit too.

Here is a sample code to call that command properly :

<lsl>

// FORCE TELEPORT EXAMPLE
// Listens on channel 4 for local coordinates and a sim name
// and tells your viewer to teleport you there.
//
// By Marine Kelley 2008-08-26
// RLV version required : 1.12 and above
//
// HOW TO USE :
// * Create a script inside a box
// * Overwrite the contents of the script with this one
// * Wear the box
// * Say the destination coords Region/X/Y/Z on channel 4 :
// Example : /4 Help Island Public/128/128/50

key kRequestHandle; // UUID of the dataserver request
vector vLocalPos; // local position extracted from the

Init () {
kRequestHandle = NULL_KEY;
llListen (4, "", llGetOwner (), "");
}

default
{
state_entry () {
Init ();
}

on_rez(integer start_param) {
Init ();
}

listen(integer channel, string name, key id, string message) {
list tokens = llParseString2List (message, ["/"], []);
integer L = llGetListLength (tokens);

if (L==4) {
// Extract local X, Y and Z
vLocalPos.x = llList2Float (tokens, 1);
vLocalPos.y = llList2Float (tokens, 2);
vLocalPos.z = llList2Float (tokens, 3);

// Request info about the sim
kRequestHandle=llRequestSimulatorData (llList2String (tokens, 0), DATA_SIM_POS);
}
}

dataserver(key queryid, string data) {
if (queryid == kRequestHandle) {
// Parse the dataserver response (it is a vector cast to a string)
list tokens = llParseString2List (data, ["<", ",", ">"], []);
string pos_str = "";
vector global_pos;

// The coordinates given by the dataserver are the ones of the
// South-West corner of this sim
// => offset with the specified local coordinates
global_pos.x = llList2Float (tokens, 0);
global_pos.y = llList2Float (tokens, 1);
global_pos.z = llList2Float (tokens, 2);
global_pos += vLocalPos;

// Build the command
pos_str = (string)((integer)global_pos.x)
+"/"+(string)((integer)global_pos.y)
+"/"+(string)((integer)global_pos.z);
llOwnerSay ("Global position : "+(string)pos_str); // Debug purposes

// Fire !
llOwnerSay ("@tpto:"+pos_str+"=force");
}
}

}

</lsl>

* '''''Remove/add auto-accept teleport offers from a particular avatar''''' : "@accepttp[:<UUID>]=<rem/add>"
''Implemented in v1.15, slightly improved in v1.16''
Adding this rule will make the user automatically accept any teleport offer from the avatar which key is <UUID>, exactly like if that avatar was a Linden (no confirmation box, no message, no Cancel button). This rule does not supercede nor deprecate @tpto because the former teleports to someone, while the latter teleports to an arbitrary location. Attention : in v1.16 the UUID becomes optional, which means that @accepttp=add will force the user to accept teleport offers from anyone ! Use with caution !

* '''''Allow/prevent seeing the names of the people around''''' : @shownames=<y/n>
''Implemented in v1.12.2, added more dummy names in v1.16''
When prevented, the user is unable to know who is around. The names don't show on the screen, the names on the chat are replaced by "dummy" names such as "Someone", "A resident", the tooltips are hidden, the pie menu is almost useless so the user can't get the profile directly etc.

* '''''Allow/prevent seeing all the hovertexts''''' : @showhovertextall=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read any hovertext (2D text floating above some prims).

* '''''Allow/prevent seeing one hovertext in particular''''' : @showhovertext:<UUID>=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read the hovertext floating above the prim which id is UUID. This is made that way so that the restriction can be issued on an object, by another one (unlike @detach which can only set this restriction on itself).

* '''''Allow/prevent seeing the hovertexts on the HUD of the user''''' : @showhovertexthud=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read any hovertext showing over their HUD objects, but will be able to see the ones in-world.

* '''''Allow/prevent seeing the hovertexts in-world''''' : @showhovertextworld=<y/n>
''Implemented in v1.19''
When prevented, the user is unable to read any hovertext showing over their in-world objects, but will be able to see the ones over their HUD.

* '''''Allow/prevent flying''''' : @fly=<y/n>
''Implemented in v1.12.2''
When prevented, the user is unable to fly.

* '''''Get the UUID of the object the avatar is sitting on''''' : @getsitid=<channel_number>
''Implemented in v1.12.4''
Makes the viewer automatically answer the UUID of the object the avatar is currently sitting on, or NULL_KEY if they are not sitting.

* '''''Force rotate the avatar to a set direction''''' : @setrot:<angle_in_radians>=force
''Implemented in v1.17''
Forces the avatar to rotate towards a direction set by an angle in radians from the north. Note that this command is not very precise, nor will do anything if the action attempts to rotate the avatar by less than 10° (experimental value, it has been mentioned somewhere that 6° was the minimum). In other words, it is best to either check with a llGetRot() first, or to make the avatar turn twice, first 180° plus the desired angle, then by the angle we need. It isn't very elegant but it works.

* '''''Allow/prevent changing some debug settings''''' : @setdebug=<y/n>
''Implemented in v1.16''
When prevented, the user is unable to change some viewer debug settings (Advanced > Debug Settings). As most debug settings are either useless or critical to the user's experience, a whitelist approach is taken : only a few debug settings are locked, the others are always available and untouched. At the time of this writing, the allowed debug settings are :
** AvatarSex (0 : Female, 1 : Male) : gender of the avatar at creation.
** RenderResolutionDivisor (1 -> ...) : "blurriness" of the screen. Combined to clever @setenv commands, can simulate nice effects. Note: renderresolutiondivisor is a Windlight only option (Basic Shaders must be enabled in graphics preferences) and as such, is not available in v1.19.0.5 or older viewers.

* '''''Force change a debug setting''''' : @setdebug_<setting>:<value>=force (*)
''Implemented in v1.16''
Forces the viewer to change a particular debug setting and set it to <value>. This command is actually a package of many sub-commands, that are regrouped under "@setdebug_...", for instance "@setdebug_avatarsex:0=force", "@setdebug_renderresolutiondivisor:64=force" etc.

See the list of allowed debug settings in the @setdebug command hereabove.

* '''''Get the value of a debug setting''''' : @getdebug_<setting>=<channel_number>
''Implemented in v1.16''
Makes the viewer automatically answer the value of a debug setting, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is the value that has been set with the <setting> part of the matching @setdebug command, or by hand.

See the list of allowed debug settings in the @setdebug command hereabove.

* '''''Allow/prevent changing the environment settings''''' : @setenv=<y/n>
''Implemented in v1.14''
When prevented, the user is unable to change the viewer environment settings (World > Environment Settings > Sunrise/Midday/Sunset/Midnight/Revert to region default/Environment editor are all locked out).

* '''''Force change an environment setting''''' : @setenv_<setting>:<value>=force (*)
''Implemented in v1.14''
Forces the viewer to change a particular environment setting (time of day or Windlight) and set it to <value>. This command is actually a package of many sub-commands, that are regrouped under "@setenv_...", for instance "@setenv_daytime:0.5=force", "@setenv_bluehorizonr:0.21=force" etc.

This command (like any other "force" command) is silently discarded if the corresponding restriction has been set, here "@setenv", but in this case the restriction is ignored if the change is issued from the object that has created it. In other words, a collar can restrict environment changes, yet force a change by itself, while another object could not do it until the collar lifts the restriction.

Although a range is specified for every value, no check is made in the viewer so a script can do what the UI can't do, for interesting effects. Use at your own risk, though. The ranges indicated here are merely the ones available on the sliders on the Environment Editor, for reference.

Each particular sub-command works as follows (the names are chosen to be as close to the Windlight panels of the viewer as possible) :

{| border="1" cellpadding="5"
| '''@setenv_XXX:<value>=force where XXX is...''' || '''<value> range''' || '''Sets...'''
|-
| daytime || 0.0-1.0 and <0 || Time of day (sunrise:0.25, midday:0.567, sunset:0.75, midnight:0.0, set back to region default:<0). '''Attention, resets all other Windlight parameters'''
|-
| preset || String || A Preset environment, e.g. Gelatto, Foggy. '''Attention, loading a Preset is heavy on the viewer and can slow it down for a short while, don't do it every second'''
|-
| ambientr || 0.0-1.0 || Ambient light, Red channel
|-
| ambientg || 0.0-1.0 || Ambient light, Green channel
|-
| ambientb || 0.0-1.0 || Ambient light, Blue channel
|-
| ambienti || 0.0-1.0 || Ambient light, Intensity
|-
| bluedensityr || 0.0-1.0 || Blue Density, Red channel
|-
| bluedensityg || 0.0-1.0 || Blue Density, Green channel
|-
| bluedensityb || 0.0-1.0 || Blue Density, Blue channel
|-
| bluedensityi || 0.0-1.0 || Blue Density, Intensity
|-
| bluehorizonr || 0.0-1.0 || Blue Horizon, Red channel
|-
| bluehorizong || 0.0-1.0 || Blue Horizon, Green channel
|-
| bluehorizonb || 0.0-1.0 || Blue Horizon, Blue channel
|-
| bluehorizoni || 0.0-1.0 || Blue Horizon, Intensity
|-
| cloudcolorr || 0.0-1.0 || Cloud color, Red channel
|-
| cloudcolorg || 0.0-1.0 || Cloud color, Green channel
|-
| cloudcolorb || 0.0-1.0 || Cloud color, Blue channel
|-
| cloudcolori || 0.0-1.0 || Cloud color, Intensity
|-
| cloudcoverage || 0.0-1.0 || Cloud coverage
|-
| cloudx || 0.0-1.0 || Cloud offset X
|-
| cloudy || 0.0-1.0 || Cloud offset Y
|-
| cloudd || 0.0-1.0 || Cloud density
|-
| clouddetailx || 0.0-1.0 || Cloud detail X
|-
| clouddetaily || 0.0-1.0 || Cloud detail Y
|-
| clouddetaild || 0.0-1.0 || Cloud detail density
|-
| cloudscale || 0.0-1.0 || Cloud scale
|-
| cloudscrollx || 0.0-1.0 || Cloud scroll X
|-
| cloudscrolly || 0.0-1.0 || Cloud scroll Y
|-
| densitymultiplier || 0.0-0.9 || Density multiplier of the fog
|-
| distancemultiplier || 0.0-100.0 || Distance multiplier of the fog
|-
| eastangle || 0.0-1.0 || Position of the east, 0.0 is normal
|-
| hazedensity || 0.0-1.0 || Density of the haze
|-
| hazehorizon || 0.0-1.0 || Haze at the horizon
|-
| maxaltitude || 0.0-4000.0 || Maximum altitude of the fog
|-
| scenegamma || 0.0-10.0 || Overall gamma, 1.0 is normal
|-
| starbrightness|| 0.0-2.0 || Brightness of the stars
|-
| sunglowfocus || 0.0-0.5 || Focus of the glow of the sun
|-
| sunglowsize || 1.0-2.0 || Size of the glow of the sun
|-
| sunmooncolorr || 0.0-1.0 || Sun and moon, Red channel
|-
| sunmooncolorg || 0.0-1.0 || Sun and moon, Green channel
|-
| sunmooncolorb || 0.0-1.0 || Sun and moon, Blue channel
|-
| sunmooncolori || 0.0-1.0 || Sun and moon, Intensity
|-
| sunmoonposition || 0.0-1.0 || Position of the sun/moon, different from "daytime", '''use this to set the apparent sunlight after loading a Preset'''
|}

Note: from the above settings, only the "daytime" one is supported by v1.19.0 (or older) viewers implementing RestrainedLove v1.14 and later. The other settings are ignored. This is because these viewers do not implement the Windlight renderer.

(*) Silently discarded if the user is prevented from doing so by the corresponding restriction. This is on purpose.
Ex : Force detach won't work if the object is undetachable. Force undress won't work if the user is prevented from undressing.

* '''''Get the value of an environment setting''''' : @getenv_<setting>=<channel_number>
''Implemented in v1.15''
Makes the viewer automatically answer the value of an environment setting, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is the value that has been set with the <setting> part of the matching @setenv command, or by hand. See the table hereabove for a list of settings. 
Note: only @getenv_daytime is supported by v1.19.0 (or older, i.e. non Windlight) viewers implementing RestrainedLove v1.15 and later.

==Important note about the global behaviours such as sendchat==
Such behaviours are global, which means they don't depend on a particular object. However, they are triggered by objects with a set [[UUID]] which can change, and several objects can add the same behaviour, which will be stored several times as the [[UUID]]s are different.

This has a nice side effect : when wearing 2 locked devices that prevent chat, it is necessary to unlock them both to be able to chat again. But it has a nasty side effect, too : if the item changes [[UUID]] (for instance it was derezzed and rezzed again), and it doesn't allow chat beforehand, then the user will have to wait a short moment because the rule stays "orphaned" (its [[UUID]] is defunct) until the '''garbage collector''' kicks in.

Please note : Since 1.16.1 any locked object that is kicked off by any mean (llAttachToAvatar for example) will be reattached automatically by the viewer after 5 seconds. This means that calling @clear on detaching will actually unlock the object, which will have to be relocked after being reattached. It is therefore not recommended anymore to call @clear on detach, as opposed to pre-1.16.1 versions.

==Shared Folders==

Since v1.11, the viewer can "share" some of your items with scripts in world in order to let them force you to attach, detach and list what you have shared.

"Share" does NOT mean they will be taken by other people if they want to (some of the items may be no-transfer anyway), but only that they can force YOU to wear/unwear them at will through the use of a script YOUR restraints contain. They will remain in your inventory.

To do this :
* Create a folder named "#RLV" (without the quotes) directly under "My Inventory" (right-click on "My Inventory", select "New Folder"). We'll call this folder the "shared root".
* Move a folder containing restraints or other attachments directly into this new folder.
* Wear the contents of that folder, that's it !

So it would look like this :

My Inventory
|- #RLV
| |- cuffs
| | |- left cuff (l forearm) (no copy)
| | \- right cuff (r forearm) (no copy)
| \- gag
| \- gag (mouth) (no copy)
|- Animations
|- Body Parts
.
.
.

For example : If you're owning a set of RR Straps and want to share them, just move the folder "Straps BOXED" under the shared root.

Either wear all the items of the folders you have just moved (one folder at a time !) or rename your items yourself, so that each item name contains the name of the target attachment point. For example : "left cuff (l forearm)", "right ankle cuff (r lower leg)". Please note that no-modify items are a bit more complex to share, because they cannot be renamed either by you or by the viewer. More on that below.

The attachment point name is the same as the one you find in the "Attach To" menu of your inventory, and is case insensitive (for example : "chest", "skull", "stomach", "left ear", "r upper arm"...). If you wear the item without renaming it first it will be renamed automatically, but only if it is in a shared folder, and does not contain any attachment point name already, and is mod. If you want to wear it on another attachment point, you'll need to rename it by hand first.

Pieces of clothing are treated exactly the same way (in fact they can even be put in the folder of a set of restraints and be worn with the same command). Shoes, for instance, are a good example of mixed outfits : some attachments and the Shoes layer. Clothes are NOT renamed automatically when worn, since their very type decides where they are to be worn (skirt, jacket, undershirt...).

HOW TO SHARE NO-MODIFY ITEMS :
As you already know, no-mod items cannot be renamed so the technique is a bit more complex. Create a sub-folder inside the outfit folder (such as "cuffs" in the example above), put ONE no-modify item in it. When wearing the object, you'll see the folder itself be renamed (that's why you must not put more than one object inside it). So if your outfit contains several no-mod objects, you'll need to create as many folders and put the no-mod objects in them, one in each folder.

Example with no-modify shoes :

My Inventory
|- #RLV
| \- shoes
| |- left shoe (left foot)
| | \- left shoe (no modify) (no transfer) <-- no-mod object
| |- right shoe (right foot)
| | \- right shoe (no modify) (no transfer) <-- no-mod object
| \- shoe base (no modify) (no transfer) <-- this is not an object
|- Animations
|- Body Parts
.
.
.

GOTCHAS :
* Do NOT put a comma (',') in the name of the folders under the shared root or it would screw the list up.
* Don't forget to rename the items in the shared folders (or to wear these items at least once to have them be renamed automatically) or the force attach command will appear to do nothing at all.
* Avoid cluttering the shared root with many folders, since some scripts may rely on the list they got with the @getinv command and chat messages are limited to 1023 characters. Choose wisely, and use short names. But with 9 characters per folder name average, you can expect to have about 100 folders available.
* Remember to put no-modify items in sub-folders, one each, so their names can be used by the viewer do find out where to attach them. They can't be shared like modify items since they can't be renamed, and the outfit folder itself will not be renamed (since it contains several items).

'''''Accept sub-folders given via llGiveInventoryList() into the shared folder''''' :

Starting with RestrainedLove v1.16.2, you may give a list of items to a victim and have them stored as a sub-folder inside the #RLV folder (thus allowing you to @attach the given items later).

Issuing a llGiveInventoryList(victim_id, "#RLV/~subfolder_name", list_of_stuff) command in a script makes a standard Keep/Discard/Mute dialog appear in the viewer of the victim (the avatar which key is victim_id).

Should the victim accept the offer, the list_of_stuff items are put into a new sub-folder of the #RLV folder. The name of this sub-folder is "~subfolder_name" (it is the scripter's responsibility to use unique sub-folder names: if the name is the same as an existing sub-folder, two sub-folders with the same name will appear in the #RLV folder).

Note that the tilde character *must* be used as the first character for the name of the sub-folder (this is so that the victim can easily spot any sub-folder given to them in this way, and so that such sub-folder names appear last in the #RLV folder).

Note also that this feature may be disabled by the user, (by setting the RestrainedLoveForbidGiveToRLV debug setting to TRUE): in this case the given items are put into a folder named "#RLV/~subfolder_name" at the root of the inventory instead of inside the #RLV folder.

Since the user may either refuse the offer or have the feature disabled in their viewer, and since SL may take quite some time to perform the actual transfer of the objects on laggy days, you must check that the given folder is present (with @getinv), before attempting to @attach the given objects.

==For your information==
Here is how it works internally, for a better understanding of the gotchas you may encounter :
* Each command is parsed into a '''Behaviour''' (ex: "remoutfit"), an '''Option''' (ex: "shirt") and a '''Param''' (ex: "force") and comes from an [[UUID]] (the unique identifier of the emitting object).

* There are two types of commands : '''one-shot''' commands (those which Param is "force" and those which Param is a number such as the channel number of a "version" call) and '''rules''' (those which Param is "y", "n", "add" or "rem"). "clear" is special but can be seen as a one-shot command.

* Parameters "n" and "add" are '''exactly equal''' and are treated '''exactly the same way''', they are just '''synonyms'''. Same goes for "y" and "rem". The only purpose is to distinguish rules ("sendchannel=n") from exceptions ("sendchannel:8=add") in a script for clarity.

* Rules are stored inside a table linking the [[UUID]] of the emitter to the rule itself. They are '''added''' when receiving a "n"/"add" Param, and '''removed''' when receiving a "y"/"rem" Param.
If '''''UUID1''''' is a collar and '''''UUID2''''' is a gag :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

Those two rules mean that the user cannot send IMs except to their keyholder, and cannot TP at all. Those two items are not detachable. Now if the collar sends "@sendim=n", the table becomes :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp, sendim

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

If it sends "@sendim=n" a second time nothing changes, as there is a check for its existence prior to adding it. If the gag is unlocked and detached, either it sends a "@clear" or the garbage collector kicks in so the rules linked to '''''UUID2''''' disappear. However, the avatar is still unable to send IMs even to their keyholder, as the exception has disappeared as well. This is because rules linked to one object don't conflict with rules linked to another one.

* One-shot commands, on the other hand, are executed on-the-fly and are not stored.

* When logging on, the avatar stays non-operational (cannot chat, cannot move) for some time, while the user sees the progress bar. However, worn scripted objects [[rez]] in the meantime and start sending rules and commands before the viewer can execute them. Therefore it stores them in a buffer and executes them only when the user is given controls (when the progress bar disappears).

* The viewer periodically (every N seconds) checks all its rules and removes the ones linked to an [[UUID]] that does not exist around anymore ("garbage collector"). This means that rules issued by an '''unworn''' owned object will be discarded as soon as the avatar [[teleports]] elsewhere.

[[Category:Third Party Client]]
[[Category:RestrainedLove]]

Template:LSL Function/ParticleSystem

2010-05-22T23:27:38Z

Batche Manen: Quick clarification PSYS_SRC_ACCEL works with negative values, constant's comment is a bit misleading

{{#if:

<noinclude>
{{#vardefine:self|*}}
{{#vardefine:moded|stp}}
</noinclude>

<includeonly>
{{#vardefine:header|{{#var:header}}{{LSLC|Effects}}{{LSLC|Light}}{{LSLC|Particles}}{{LSLC|Prim}}{{LSLC|Stop}}}}
</includeonly>

{{LSL Function/color}}
{{LSL Function/alpha}}

{{#vardefine:p_rules_desc|Particle system rules list in the format [ rule1, data1, rule2, data2 . . . rule'''n''', data'''n''' ]}}
{{#vardefine:p_rules_hover|Particle system rules list in the format [ rule1, data1, rule2, data2 . . . rulen, datan ]}}

}}<noinclude>
===spec===
</noinclude>{{#if:
{{#vardefine:spec|
Defines a particle system that sets the state of the [[particle emitter]] within the [[primitive|prim]] which the [[script]] is contained. Any other scripts in the same prim which call this function will modify the state of the same particle emitter. As such, the particle system defined by this function is a [[primitive property|prim property]], just like its size, shape, color, et cetera.
Each prim has only '''one (1)''' particle emitter, located at its [[geometric center]], and aligned along the prim's [[Viewer coordinate frames#Local|local]] Z-axis, pointing in the positive Z direction.

This is the only function which alters the state of the prim's particle emitter; thus, if you wish to change the emitter to a different state (i.e., emitting a different particle system entirely, or shut off the emitter completely), just call this same function with the parameters of the new particle system you wish to render instead. Specifying an empty list (i.e., <code>{{{1}}}</code>; ) turns the emitter off.

Particles are essentially 2D {{Wikipedia|Sprite_(computer_graphics)|sprites}} and are always rendered facing the viewer's camera.

The rule / data values are defined below.
{{#var:spec}}}}
}}<noinclude>
{{#var:spec}}
</noinclude>{{#if:

}}<noinclude>
===caveats===
</noinclude>{{#if:
{{#vardefine:caveats|
# When using particle systems that have a non-zero emitter age (PSYS_SRC_MAX_AGE) setting, you may notice that the particle system may restart without any scripted trigger going off. This is due to a bug which causes the emitter to "reset" when any of the prim properties are updated or otherwise sent to the viewer. As a result, you may have to use a [[timer]] or a forced [[llSleep|sleep]] and then clear the particle system once the age has expired. Debbie Trilling has posted a work-around here: http://forums.secondlife.com/showpost.php?p=1996465&postcount=6
# The spin defined by PSYS_SRC_OMEGA is relative to the [[Viewer coordinate frames#Region|region]] coordinate system, NOT the prim's [[Viewer coordinate frames#Local|local]] coordinate system.
# When freshly created a prims emitter is set to ZERO_ROTATION within the prim. If whilst designing a particle display you use PSYS_SRC_OMEGA the emitter will be rotated. If then you change the PSYS_SRC_OMEGA vector the emitter will not be reset to ZERO_ROTATION but will remain rotated to whatever axis it was at when stopped or altered. This can result in particles being displayed quite differently in the corrupted prim than they would be using the same script in a fresh prim (with a fresh emitter).
# Particles moving towards a humanoid avatar, specified by PSYS_SRC_TARGET_KEY rule and setting the PSYS_PART_TARGET_POS_MASK flag, will end up at the geometric center of the avatar's bounding box which, unfortunately, make them appear to be striking the person in the groin area. If you want them to end up at another point on a target avatar, you instead have to place a target prim that is moved to the position where you wish them to end up, and use the key of that prim for the value of the PSYS_SRC_TARGET_KEY rule.
# The Second Life viewer uses optimizations in culling objects which are too small to see at certain distances. If your emitter is very small, and is culled due to distance, the particle system associated with it will not be rendered either.
{{#var:caveats}}}}
}}<noinclude>
{{#var:caveats}}
</noinclude>{{#if:

}}<noinclude>
===notes===
</noinclude>{{#if:
{{#vardefine:notes|
* The default particle count for the client is normally set at 4096. That is the max particle count the client will render for ALL active particle systems within view range. Good particle system design is key to avoid "spamming" everyone with your particles, and starving out other people's particle systems. As such, if you are experiencing trouble getting your particle emitter to emit as many particles as you like, it may be the victim of particle starvation. Client/viewer lag (low frame rates) can also cause this issue, as particles are a rather low priority for rendering. The best solution for this is to move to a less laggy environment relatively free of other particle systems when designing and testing your own.
* Once particles are emitted, their direction of motion can only be affected by PSYS_SRC_ACCEL, the PSYS_PART_TARGET_POS_MASK flag, or the PSYS_PART_FOLLOW_SRC_MASK flag. As such, there is no good way to create the "swirling vortex" effect (like the one used in the viewer to indicate an object talking, begin derezzed, or when an avatar leaves the sim/grid). The effect can be created with a moving particle source (E.G. An orbiting script.)
{{#var:notes}}}}
}}<noinclude>
{{#var:notes}}
</noinclude>{{#if:

}}<noinclude>
===helpers===
</noinclude>{{#if:
{{#vardefine:helpers|
'''Useful functions for storing/retrieving color and alpha values to/from integers:''' 
<lsl>integer ColorAlphatoRGBA(vector color, float alpha) {
return (((integer)(alpha * 255.0) & 0xFF) << 24) |
(((integer)(color.x * 255.0) & 0xFF) << 16) |
(((integer)(color.y * 255.0) & 0xFF) << 8) |
((integer)(color.z * 255.0) & 0xFF);
}

vector RGBAtoColor(integer rgba) {
return < ((rgba >> 16) & 0xFF) / 255.0, ((rgba >> 8) & 0xFF) / 255.0, (rgba & 0xFF) / 255.0 >;
}

float RGBAtoAlpha(integer rgba) {
return ((rgba >> 24) & 0xFF) / 255.0;
}</lsl>
{{#var:helpers}}}}
}}<noinclude>
{{#var:helpers}}
</noinclude>{{#if:

}}<noinclude>
===constants_nb===
</noinclude>{{#if:
{{#vardefine:constants_nb|{{#var:constants_nb}}
{{{!}} {{prettytable|style=margin-top:0; margin-right:0;}}
{{!}}-{{Hl2}}
{{!!}}
{{!!}} Rule / Value Constant
{{!!}} Rule Parameter
{{!!}} Description
{{!!}} Value
{{!}}- style="background-color:#ccffcc;"
{{!}} colspan="5" align="left"{{!}}'''System Behavior'''
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_FLAGS
{{!!}}[[integer]] {{LSL Param|flags}}
{{!!}}Various flags controlling the behavior of the particle system. The value may be specified as an integer in decimal or [[hexadecimal|hex]] format, or by ORing together (using the <nowiki>|</nowiki> operator) one or more of the following flag constants:
{{!}}align="center"{{!}}0
{{!}}- style="background-color:#e0e0e0;"
{{!}}rowspan="15" style="background-color:#c0c0c0;" align="center" valign="center"{{!}}'''V a l u e s'''
{{!}}colspan="2"{{!}}PSYS_PART_BOUNCE_MASK
{{!!}}When set, specifies particles will bounce off a plane at the [[Viewer coordinate frames#Region|region]] Z height of the emitter. On "bounce", each particle reverses velocity and angle. This only works for particles above the plane falling down on it.
{{!}}align="center"{{!}}{{LSL_Hex|0x004|4}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_EMISSIVE_MASK
{{!!}}When set, particles are full-bright and are unaffected by global lighting (sunlight). Otherwise, particles will be lit depending on the current global lighting conditions. Note that point lights '''do''' illuminate non-emissive particles.
{{!}}align="center"{{!}}{{LSL_Hex|0x100|256}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_FOLLOW_SRC_MASK
{{!!}}When set, particles move relative to the position of the emitter. Otherwise, particle position and movement are unaffected by the position/movement of the emitter. This flag disables the PSYS_SRC_BURST_RADIUS rule.
{{!}}align="center"{{!}}{{LSL_Hex|0x010|16}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_FOLLOW_VELOCITY_MASK
{{!!}}When set, particles rotate to orient their "top" towards the direction of movement or emission. Otherwise, particles are oriented vertically as their textures would appear (top of texture at top, left at left).
{{!}}align="center"{{!}}{{LSL_Hex|0x020|32}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_INTERP_COLOR_MASK
{{!!}}When set, particle color and alpha transition from their START settings to their END settings during the particle's lifetime. The transition is a smooth interpolation.
{{!}}align="center"{{!}}{{LSL_Hex|0x001|1}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_INTERP_SCALE_MASK
{{!!}}When set, particle size/scale transitions from its START setting to its END setting during the particle's lifetime.
{{!}}align="center"{{!}}{{LSL_Hex|0x002|2}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_TARGET_LINEAR_MASK
{{!!}} When set, emitted particles move in a straight line towards the target specified by the PSYS_SRC_TARGET_KEY rule. In this mode, PSYS_SRC_ACCEL, PSYS_SRC_BURST_RADIUS, and possibly other rules are ignored.
{{!}}align="center"{{!}}{{LSL_Hex|0x080|128}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_TARGET_POS_MASK
{{!!}}When set, emitted particles change course during their lifetime, attempting to move towards the target specified by the PSYS_SRC_TARGET_KEY rule by the time they expire. Note that if no target is specified, the target moves out of range, or an invalid target is specified, the particles target the prim itself.
{{!}}align="center"{{!}}{{LSL_Hex|0x040|64}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_PART_WIND_MASK
{{!!}}When set, particle movement is affected by the [[llWind|wind]]. It is applied as a secondary force on the particles.
{{!}}align="center"{{!}}{{LSL_Hex|0x008|8}}
{{!}}-

{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}<s>PSYS_PART_BEAM_MASK</s>
{{!!}}(''unimplemented'') mask but in the enum
{{!}}align="center"{{!}}{{LSL_Hex|0x200|}}
{{!}}-

{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}<s>LL_PART_HUD</s>
{{!!}}Used by the viewer to keep HUD and World particle sources separate.
{{!}}align="center"{{!}}{{LSL_Hex|0x40000000|}}
{{!}}-
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}<s>LL_PART_DEAD_MASK</s>
{{!!}}Removes particles, not compatible with any other PSYS_PART_*_MASK
{{!}}align="center"{{!}}{{LSL_Hex|0x80000000|}}
{{!}}-

{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}<s style="color:darkred;">LL_PART_RANDOM_ACCEL_MASK</s>
{{!!}}(''unimplemented & commented out'') Presumed to be used to apply random acceleration to the particles.
{{!}}align="center"{{!}} -
{{!}}-

{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}<s style="color:darkred;">LL_PART_RANDOM_VEL_MASK</s>
{{!!}}(''unimplemented & commented out'') Presumed to be used to specify random velocity for the particles upon emission.
{{!}}align="center"{{!}} -
{{!}}-

{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}<s style="color:darkred;">LL_PART_TRAIL_MASK</s>
{{!!}}(''unimplemented & commented out'') Presumed to be used for implementing "trails" via emitting more particles at shorter bursts.
{{!}}align="center"{{!}} -
{{!}}-

{{!}}- style="background-color:#ccffcc;"
{{!}} colspan="5" align="left"{{!}}'''System Presentation'''
{{!}}-
{{!}} colspan="2"{{!}}PSYS_SRC_PATTERN
{{!!}}[[integer]] {{LSL Param|pattern}}
{{!!}}Specifies the general emission pattern.
{{!}}align="center"{{!}}9
{{!}}- style="background-color:#e0e0e0;"
{{!}}rowspan="5" style="background-color:#c0c0c0;" align="center" valign="center"{{!}}'''V a l u e s'''
{{!}}colspan="2"{{!}}PSYS_SRC_PATTERN_EXPLODE
{{!!}}Sprays particles outwards in a spherical area. The Initial velocity of each particle is determined by PSYS_SRC_BURST_SPEED_MIN and PSYS_SRC_BURST_SPEED_MAX. The EXPLODE pattern ignores the ANGLE parameters.
{{!}}align="center"{{!}}{{LSL_Hex|0x02|2}}
{{!}}- style="background-color:#e0e0e0;"
{{!}}colspan="2"{{!}}PSYS_SRC_PATTERN_ANGLE_CONE
{{!!}}Sprays particles outwards in a spherical, sub-spherical, conical or ring shaped area, as defined by the ANGLE parameters PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The ANGLE_CONE pattern can be used to imitate the EXPLODE pattern by explicitly setting PSYS_SRC_ANGLE_BEGIN to 0.00000 and PSYS_SRC_ANGLE_END to 3.14159 (or PI) (or vice versa).
{{!}}align="center"{{!}}{{LSL_Hex|0x08|8}}
{{!}}- style="background-color:#e0e0e0;"
{{!}} colspan="2"{{!}}PSYS_SRC_PATTERN_ANGLE
{{!!}}Sprays particles outward in a flat circular, semi-circular, arc or ray shaped areas, as defined by PSYS_SRC_ANGLE_BEGIN and PSYS_SRC_ANGLE_END. The circular pattern radiates outwards around the prim's local X axis line.
{{!}}align="center"{{!}}{{LSL_Hex|0x04|4}}
{{!}}- style="background-color:#e0e0e0;"
{{!}}colspan="2"{{!}}PSYS_SRC_PATTERN_DROP
{{!!}}Creates particles with no initial velocity. The DROP pattern will overrides any values given for PSYS_SRC_BURST_RADIUS, PSYS_SRC_BURST_SPEED_MIN, and PSYS_SRC_BURST_SPEED_MAX, setting each to 0.00000. (All patterns will behave like the DROP pattern, if RADIUS, SPEED_MIN and SPEED_MAX are explicitly set to 0.0000.)
{{!}}align="center"{{!}}{{LSL_Hex|0x01|1}}
{{!}}- style="background-color:#e0e0e0;"
{{!}}colspan="2"{{!}}PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY
{{!!}}(''incomplete implementation'') acts the same as the PSYS_SRC_PATTERN_DROP pattern, it is believed that the original intention for this pattern was to invert the effect of the ANGLE parameters, making them delineate an area where particles were NOT to be sprayed. (effectively the inverse or opposite of the behavior of the ANGLE_CONE pattern).
{{!}}align="center"{{!}}{{LSL_Hex|0x10|16}}
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_BURST_RADIUS
{{!!}}[[float]] {{LSL Param|radius}}
{{!!}}Specifies the distance from the emitter where particles will be created. This rule is ignored when the PSYS_PART_FOLLOW_SRC_MASK flag is set. A test in http://forums-archive.secondlife.com/327/f5/226722/1.html indicates that the maximum value is 50.00
{{!}}align="center"{{!}}16
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_ANGLE_BEGIN
{{!!}}[[float]] {{LSL Param|angle_begin}}
{{!!}}Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are the same as for PSYS_SRC_ANGLE_END, though the effects are reversed accordingly. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_SRC_ANGLE_END are internally re-ordered such that this parameter gets the smaller of the two values.
{{!}}align="center"{{!}}22
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_ANGLE_END
{{!!}}[[float]] {{LSL Param|angle_end}}
{{!!}}Specifies a half angle, in radians, of a circular or spherical "dimple" or conic section (starting from the emitter facing) within which particles will NOT be emitted. Valid values are 0.0, which will result in particles being emitted in a straight line in the direction of the emitter facing, to [[PI]], which will result in particles being emitted in a full circular or spherical arc around the emitter, not including the "dimple" or conic section defined by PSYS_SRC_ANGLE_BEGIN. If the pattern is PSYS_SRC_PATTERN_ANGLE, the presentation is a 2D flat circular section. If PSYS_SRC_PATTERN_ANGLE_CONE or PSYS_SRC_PATTERN_ANGLE_CONE_EMPTY is used, the presentation is a 3D spherical section. Note that the value of this parameter and PSYS_SRC_ANGLE_BEGIN are internally re-ordered such that this parameter gets the larger of the two values.
{{!}}align="center"{{!}}23
{{!}}-
{{!}}colspan="2"{{!}}<del>PSYS_SRC_INNERANGLE</del>
{{!!}}[[float]] {{LSL Param|angle_inner}}
{{!!}}'''DEPRECATED: Use PSYS_SRC_ANGLE_BEGIN instead.''' Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than its center.
{{!}}align="center"{{!}}10
{{!}}-
{{!}}colspan="2"{{!}}<del>PSYS_SRC_OUTERANGLE</del>
{{!!}}[[float]] {{LSL Param|angle_outer}}
{{!!}}'''DEPRECATED: Use PSYS_SRC_ANGLE_END instead.''' Works similar to its replacement rule, except the edge of the section is aligned with the emitter facing, rather than the section's center.
{{!}}align="center"{{!}}11
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_TARGET_KEY
{{!!}}[[key]] {{LSL Param|target}}
{{!!}}Specifies the key of a target object, prim, or agent towards which the particles will change course and move. They will attempt to end up at the geometric center of the target at the end of their lifetime. Requires the PSYS_PART_TARGET_POS_MASK flag be set. [[#Caveats|caveat 4]]
{{!}}align="center"{{!}}20
{{!}}- style="background-color:#ccffcc;"
{{!}}colspan="5" align="left"{{!}}'''Particle Appearance'''
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_START_COLOR
{{!!}}[[vector]] {{LSL Param|color_start}}
{{!!}}A vector specifying the [[color]] of the particles upon emission.
{{!}}align="center"{{!}}1
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_END_COLOR
{{!!}}[[vector]] {{LSL Param|color_end}}
{{!!}}A vector specifying the [[color]] the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set.
{{!}}align="center"{{!}}3
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_START_ALPHA
{{!!}}[[float]] {{LSL Param|alpha_start}}
{{!!}}Specifies the [[alpha]] of the particles upon emission. Valid values are in the range 0.0 to 1.0. Lower values are more transparent; higher ones are more opaque.
{{!}}align="center"{{!}}2
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_END_ALPHA
{{!!}}[[float]] {{LSL Param|alpha_end}}
{{!!}}Specifies the [[alpha]] the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_COLOR_MASK flag is set. Valid values are the same as PSYS_PART_START_ALPHA.
{{!}}align="center"{{!}}4
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_START_SCALE
{{!!}}[[vector]] {{LSL Param|scale_start}}
{{!!}}Specifies the [[scale]] or size of the particles upon emission. Valid values for each direction are 0.04 (0.03125) to 4.0, in meters. Since particles are essentially 2D sprites, the Z component of the vector is ignored and can be set to 0.0.
{{!}}align="center"{{!}}5
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_END_SCALE
{{!!}}[[vector]] {{LSL Param|scale_end}}
{{!!}}Specifies the [[scale]] or size the particles transition to during their lifetime. Only used if the PSYS_PART_INTERP_SCALE_MASK flag is set. Valid values are the same as PSYS_PART_START_SCALE.
{{!}}align="center"{{!}}6
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_TEXTURE
{{!!}}[[string]] {{LSL Param|texture}}
{{!!}}Specifies the name of a texture in the emitter prim's inventory to use for each particle. Alternatively, you may specify an asset key [[UUID]] for a texture. If using [[llLinkParticleSystem]] and texture is not a UUID, texture must be in the emitter prim (not necessarily with the script).
{{!}}align="center"{{!}}12
{{!}}- style="background-color:#ccffcc;"
{{!}}colspan="5" align="left"{{!}}'''Particle Flow'''
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_MAX_AGE
{{!!}}[[float]] {{LSL Param|duration_system}}
{{!!}}Specifies the length of time, in seconds, that the emitter will operate upon coming into view range (if the particle system is already set) or upon execution of this function (if already in view range). Upon expiration, no more particles will be emitted, except as specified above. Zero will give the particle system an infinite duration. ([[#Caveats|caveat 1]])
{{!}}align="center"{{!}}19
{{!}}-
{{!}}colspan="2"{{!}}PSYS_PART_MAX_AGE
{{!!}}[[float]] {{LSL Param|duration_particle}}
{{!!}}Specifies the lifetime of each particle emitted, in seconds. Maximum is 30.0 seconds. During this time, the particle will appear, change appearance and move according to the parameters specified in the other sections, and then disappear.
{{!}}align="center"{{!}}7
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_BURST_RATE
{{!!}}[[float]] {{LSL Param|burst_sleep}}
{{!!}}Specifies the time interval, in seconds, between "bursts" of particles being emitted. Specifying a value of 0.0 will cause the emission of particles as fast as the viewer can do so.
{{!}}align="center"{{!}}13
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_BURST_PART_COUNT
{{!!}}[[integer]] {{LSL Param|burst_particle_count}}
{{!!}}Specifies the number of particles emitted in each "burst".
{{!}}align="center"{{!}}15
{{!}}- style="background-color:#ccffcc;"
{{!}}colspan="5" align="left"{{!}}'''Particle Motion'''
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_ACCEL
{{!!}}[[vector]] {{LSL Param|acceleration}}
{{!!}}Specifies a directional acceleration vector applied to each particle as it is emitted, in meters per second. Valid values are 0.0 to 100.0 for each direction both positive and negative, as [[Viewer coordinate frames#Region|region]] coordinates.
{{!}}align="center"{{!}}8
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_OMEGA
{{!!}}[[vector]] {{LSL Param|omega}}
{{!!}}Specifies the rotational spin of the emitter in radians per second along each axis. This "unsticks" the emitter facing from the prim's positive Z axis and is noticeable in directional presentations. Prim spin (via [[llTargetOmega]]) has no effect on emitter spin. ([[#Caveats|caveat 2]] and [[#Caveats|caveat 3]])
{{!}}align="center"{{!}}21
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_BURST_SPEED_MIN
{{!!}}[[float]] {{LSL Param|speed_min}}
{{!!}}Specifies the minimum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_SRC_BURST_SPEED_MAX are internally re-ordered such that this parameter gets the smaller of the two values.
{{!}}align="center"{{!}}17
{{!}}-
{{!}}colspan="2"{{!}}PSYS_SRC_BURST_SPEED_MAX
{{!!}}[[float]] {{LSL Param|speed_max}}
{{!!}}Specifies the maximum value of a random range of values which is selected for each particle in a burst as its initial speed upon emission, in meters per second. Note that the value of this parameter and PSYS_SRC_BURST_SPEED_MIN are internally re-ordered such that this parameter gets the larger of the two values.
{{!}}align="center"{{!}}18
{{!}}-
{{!}} style="font-size:80%" colspan="5" {{!}} LL_PART_* constants are only found in {{SourceLink|indra/llmessage/llpartdata.h|rev=1681|line=99}}, those flags in red have been commented out.
{{!}}} }}
}}<noinclude>
{{#var:constants_nb}}
</noinclude>{{#if:

}}<noinclude>

===deepnotes===
</noinclude>{{#if:
{{#vardefine:deepnotes|
===Missing 14===
There is a missing constant which would have the value 14, the underlying enumeration {{SourceLink|indra/llmessage/llpartdata.h|rev=1681|line=51|text=LLPSScriptFlags}} has that as {{SourceLink|indra/llmessage/llpartdata.h|rev=1681|line=70|text=LLPS_SRC_BURST_DURATION}}, the value is used nowhere else in the client source. This isn't surprising considering that the burst duration is dependent on the PSYS_SRC_BURST_PART_COUNT, PSYS_SRC_BURST_RATE.
{{#var:deepnotes}}}}
}}<noinclude>
{{#var:deepnotes}}
</noinclude>{{#if:

}}