• A primitive is a single primitive that may be part of a link-set.
• An object may be a single primitive or an entire link-set.

• The API is written using functions such as wasKeyValueEncode, wasKeyValueGet or wasKeyValueSet which are defined on the key-value data page. In short these functions are (optimised) helper functions that provide POST-data manipulation and you can use in your scripts to communicate with Corrade.
• The API uses the RFC 4180 compliant LSL functions wasListToCSV and wasCSVToList for which you can find an implementation on the comma separated values page. This is due to the fact that the built-in Linden Lab functions llList2CSV, respectively llCSV2List do not adhere to any standard (for example, llList2CSV yields identical strings to llDumpList2String(string, ", ") which makes the Linden Lab function useless).
• The API uses application/x-www-form-urlencoded encoding functions wasFormEncode and wasFormDecode (erroneously used synonymously with wasURLEscape and wasURLUnescape) which can be found on the form encoding page.
• The API provides some examples, but you can do more depending on the parameters supplied. For example, the tell command sent to Corrade can make Corrade talk in local chat, in a group and to avatars depending on the entity parameter and, in case of local chat, the type parameter (whisper, say, normal).
• Some commands ask for firstname and lastname when you need to refer to an avatar. If firstname and lastname is not known to the script, you can just supply the agent parameter and feed it the key of the designated agent.
• Groups can also be passed as UUID rather than name - this is particularly useful in cases where a group is hidden and can only be found iff. the UUID of the group is known.
• Some commands take as parameter a positional vector that is said to pin-point a parcel. In order to understand this, any point-vector on a region can be projected onto the ground-plane. This projection always intersects a parcel.
• Every command that acts upon a group can also be passed the target parameter with a group name or group UUID as a value in order to act upon a different group.

• Commands and parameters are case-sensitive in the right context. For example, passing a lower-case avatar name to Corrade is fine because avatar names are not case sensitive. As a counter-example, passing in-world primitive names may be ambiguous if the primitives have a different casing. A good example for this extra complication are roles within a group which are case-sensitive such that passing a lower-case role name to Corrade's roles command may refer to the wrong role.
  • Err on the side of caution and pass data to Corrade exactly as it appears to you.

• If Corrade refuses to execute a command, install a callback and check Corrade's return. Corrade extensively reports errors such that it becomes easy to track why a command has failed. Furthermore, Corrade tries to perform all the necessary checks such that a command will be successful, however it may happen that Corrade returns successfully but no "usable data" is returned - just the success status. In such cases, it may very well be that there was no data to return in the first place. As such, Corrade's success return refers to whether the command has been executed successfully and does not reflect the fact that there was no data to be returned.
• There may be cases where Corrade's return will be larger than the 2KB limit of http_request of an LSL script. If that is the case, then the alternative is to run Corrade's internal HTTP server and query the data outside of the grid (for example, with a PHP script). An alternative solution if you have any previous knowledge about the data that is to be returned by Corrade and you really want the result returned in-world is to use sifting.

It is important to realize that the grid is not data-driven and that visual elements such as avatars and objects are passed to a viewer on a least-effort basis. There are few to no guarantees that specific objects or avatars will be passed to the viewer.

All commands that are radar-bound are subject to the draw distance, either defined in the configuration file as the Range parameter or passed to the individual command as the range parameter. The range represents the cutoff point after which objects and avatars will not be perceived by the viewer.

Other commands that rely on different subsystems such as directory services, or the map API will often offer better guarantees for finding avatars and objects. For instance, compare the two commands:

• "getprimitivesdata", and
• "getprimitiveowners"

The former command, "getprimitivesdata" is radar-bound and will not guarantee that any primitive in particular will be detected by the viewer whilst the latter command "getprimitiveowners" goes through the land and parcel subsystem and the command is guaranteed to return complete results.

The same applies to avatars, for instance, compare the two commands:

• "getavatarsdata", and
• "getavatarpositions"

The former command, "getavatarsdata" is radar-bound and will not guarantee that any avatar in particular will be detected by the viewer whilst the "getavatarpositions" command goes through the map API such that the command is guaranteed to return complete results.

Note that commands such as "getavatarsdata" and "getavatarpositions" are different in semantics where "getavatarsdata" is supposed to query avatars for various parameters and that "getavatarpositions" will return, as per the command definition, a CSV list of avatars by positions. Nevertheless, if the purpose is to find all avatars on a region reliably then "getavatarpositions" should be used instead of "getavatarsdata" and then the information that is not needed (such as the map position) can be discarded. Otherwise, "getavatarsdata" can be used in a context where incomplete data is acceptable.

For all API commands, when an item parameter is required by a command, either the primitive (or object) UUID or primitive name can be passed to the item parameter. In case a name is passed to the item parameter, then Corrade will scan all objects in the vicinity and attempt to find the primitive or object by name. In case an UUID is supplied, Corrade will attempt to find the primitive or object by UUID.

In most cases, it is preferable to combine Corrade command with llSensor or llSensorRepeat in order to provide Corrade with the UUID of the item instead of the name. This is due to the fact that objects in Linden-based virtual worlds carry only a limited amount of information and the name of the object is not part of that information such that the command may take a long time to complete. Furthermore, object or primitive names are not distinct such that issuing a command with the item parameter set to an object name might return ambiguous results where a different primitive is returned rather than the one desired.

In many cases when interacting with primitives and avatars, you will notice that Corrade takes as parameter a range. range is the search radius in meters from the bot where Corrade will attempt to find a named primitive. Note that Corrade's search functions also include avatar attachments such that range should be kept as low as possible, otherwise very many primitives will be scanned and the command will take longer to complete.

The range parameter corresponds to the Range configuration setting in the configuration file - usually, for all commands, if range is specified, then the parameter will take precedence over the Range configuration setting. Otherwise, if range is not supplied, the search range will be extended to the Range parameter in the configuration file.

• Corrade currently supports receiving commands:
  • In-world
    • using llInstantMessage (2s LSL delay),
    • via llRegionSayTo (no delay) or
    • llOwnerSay (no delay).
  • Directly, through:
    • an HTTP server,
    • MQTT,
      • built-in MQTT broker,
      • from a remote MQTT broker that has been subscribed to using the MQTT command,
    • WebSockets,
    • TCP,
    • UDP.
• Corrade also implements RLV behaviours.

• Corrade attempts to unescape both keys and values when it receives a command, and, in turn, escapes keys and values when it sends data back to the callback. For a more complete by-example tutorial, please see the command tutorial page.

• The order in which commands execute is not pre-determined. In other words, if you send two commands succinctly, say stand and then sit, there is no guarantee that stand will execute before sit but it may happen that sit will execute before stand! In order to have any sort of guarantee of linearity, you must use a callback and confirm that a command has executed before issuing a follow-up command. In other words, following the previous example: send the stand command and confirm via the callback that stand has executed; after that, send the sit command (and confirm via the callback that the sit command has executed).
  • As a quick mnemonic: if you do not care about the outcome of a command issued to Corrade then do not check the callback. Conversely, if you care about the outcome, then check the callback.
  • A notable example where the result of a command is negligible would be a HUD where Corrade can be made to move around remotely like a ROV using W, S, A, D keys such as one of the scripts found in the drone HUD. The script usesthe nudge command that is spammed continuously to Corrade via llRegionSayTo (in order to avoid the throttling penalty of instant messages) which makes Corrade move incrementally and since it is irrelevant whether a single one of the infinitesimal nudges got executed then the callback is not checked whilst spamming nudge commands.

You can read more about key-value pairs and comma separated values on the tutorial page concerning data returned by Corrade.

• Corrade uses key-value data as the first order structure and comma-separate values (CSV) as a second-order sub-structure. This is due to the minimal syntax that is used for the two structures contrasted to, say JSON or XML that add a very rich syntactical overhead which is impractical given the constraints imposed by LSL scripts (roughly 64KB of memory).
• The CSV sub-structure is compliant with RFC 4180 - except that table headers are not used. Unfortunately, the LSL functions llCSV2List and llList2CSV cannot be used because they are not RFC 4180 compliant. To illustrate why llCSV2List and llList2CSV will not work, lets take the invite command which takes one or more roles in the role parameters and invites an avatar into a group and places them in the supplied role. Suppose that the role we want to invite an avatar to carries the name: The "Good", Role!. As you can see, there are several problems here. First, the comma , would interfere with CSV and the double-quotes around Good would interfere with an attempt to escape. In such cases, we would send the command as:

llInstantMessage(CORRADE, 
    wasKeyValueEncode(
        [
            "command", "invite",
            "group", GROUP,
            "password", PASSWORD,
            "firstname", "John",
            "lastname", "Steinbeck",
            "role", llEscapeURL("\"The \"\"Good\"\", Role!\""),
            "callback", llEscapeURL(URL)
        ]
    )
);

Notice the role name \"The \"\"Good\"\", Role!\":

1. First, every double-quote (") must be escaped in order to not interfere with LSL's start and end-of-string delimiters and will be thus written as (\"). This will vary if you are using Corrade's HTTP interface and are using a different language that supports other delimiters. For example, in PHP, you could use single quotes to avoid clashes and the role would be thus escaped in PHP as '"The ""Good"", Role!"'.
2. The outer quotes \" (beginning and end) escape the entire role name - we need to do this because the role name contains a comma ,.
3. RFC 4180 states that in order to escape double-quotes we place another quote before it, as in: "". So, that is why in order to successfully pass "Good", we escape the double quotes using another double quote: \"\"Good\"\".

• Later versions of Corrade support using JSON as the scripting language - please see the JSON section on the command tutorial.

When setting or getting the permissions for an item - either in-world or as an inventory item, Corrade serializes and deserializes permissions from a specially-formatted string which resembles loosely a superset of the UNIX literal permissions. This is due to the fact that all permissions can be expressed unambiguously using Corrade's formatted string as well as making it much easier to deal with.

An example of what a permission string looks like, is the following permission extracted from a newly created object with "copy" and "transfer" set:

c--mvt------------c---vtc--mvt

To dissect these permissions, you can use the following guide:

• split that string in segments of 6 characters: cdemvt, ------, ------, cdemvt, cdemvt.
• each segment means, in order: base permissions, everyone permissions, group permissions, next owner permissions, owner permissions.
• each character means: c (copy), d (damage), e (export), m (modify), v (move), t (transfer).
  • if any of the previously mentioned characters are missing and have a dash (-) instead, that means that those permissions are missing.

Annotating the example, we have:

       everyone    next owner
          |            |
        +-+--+      +--+-+
        |    |      |    |
  cdemvt------------cde-vtcdemvt
  |    |      |    |      |    |
  +-+--+      +--+-+      +-+--+
    |            |          |
   base        group       owner

And interpreting the results, we have:

• first 6 characters cdemvt indicate that all permissions are set for the base mask are set.
• next 6 characters ------ indicate that no permissions are granted to the everyone mask.
• next 6 characters ------ indicate that no permissions are granted to the group mask.
• next 6 characters cde-vt indicate that the next owner has the ability to copy (c), damage (d), export (e), move (v) and transfer (t) but cannot modify the object (since the m is missing and a dash is there instead).
• last 6 characters cdemvt indicate that all permissions are set for the owner.

If you take a closer look at the everyone mask, and the group mask you will notice that there are no permissions there. These permissions are used in cases where, for example, you would grant everyone or a group the permission to move the object. All the fields are relevant, but it is highly likely that the next owner mask is the one you would want to change before giving an object away.

Note that in the instances where you have to set permissions, the Export and Damage permissions are special and pertain mostly to OpenSim. As such, setting an item to full-permission will require the string:

c--mvt------------c--mvtc--mvt

The following table summaries all the permissions that are usually set for the next owner on an object:

Note that the permissions summarised in the table above only change the hexa corresponding to the next owner and that the same variations can be applied to the other hexas.

The restriction for each hexa is that only Modify objects (or objects with no permissions) cannot exist in the Linden permission system. Thus, the following permission strings are illegal:

Corrade will still attempt to set the permissions but most likely the grid will reject the setting of the permissions and Corrade will thus return a script error to the callback. Keep in mind that Corrade can do anything (and more) that a viewer can do such that a large subset of the Linden restrictions apply to Corrade as well.

In order to blend elegantly with LSL semantics, Corrade uses vectors to reference parcels instead of parcel local IDs since local IDs are not recognized by the LSL API. By consequence, most commands that deal with parcels take a position argument that is supposed to represent a point vector that will intersect a single parcel when projected onto the plane.

For instance in the following illustration, when the vector is projected onto a simulator map, will intersect a given parcel.

          y   ^                                  
                                                 
            /                                    
     255   --------------------------------------
          /region                              / 
                                              /  
        /                                    /   
                       |  -------------     /    
      /         v(x, y)| /           /     /     
                       |/           /     /      
    /                  v    parcel /     /       
                      /-----------/     /        
  /                                    /         
                                      /          
/ - - - - - - - - - - - - - - - - - -/- - - - -> 
                                               x 
                                   255                  

Vector can then be fed to the position parameter for all commands that interact with parcels.

The getregionparcellocations command can be used to retrieve a CSV list of parcel names by parcel local ID by descriptive vector.

The getparceldata command can also be used to retrieve the AABMin and AABMax parameters for a parcel representing the south-western extremity point respectively the north-eastern extremity point of a parcel. Intuitively, one could then take the arithmetic mean value to determine the midpoint and compute a point vector that would fall within the parcel. However, in Second Life parcels are allowed to be disjoined such that using the AABMin and AABMax parameters from the getparceldata command will fail in certain situations.

As an example where calculating the midpoint using AABMin and AABMax via the getparceldata command would yield erroneous results, let us assume the following land topology:

        
                AABMax
    +----+--+----+
    |(A)-|//|----|
    |----|//|----|
    +----+//+----+
    |//(B)///////|
    +----+//+----+
    |----|//|----|
    |----|//|----|
    +----+--+----+
AABMin

representing a simulator that has been divided into two parcels denoted with A and B. Taking the AABmin and AABMax points for parcel A and calculating the midpoint as the arithmetic mean would produce a point vector (on the diagonal from AABMin to AABMax) that falls within parcel B.

The getregionparcellocations command is designed to always produced valid point vectors to describe parcels and should always be used instead of computing the midpoint via the getparceldata command.

Corrade distinguishes between two types of plural forms:

• a plural form that will apply to a collection of items given certain delimiters (ie: avatars on a particular parcel),
• a plural form that will apply to a list of items provided by the user

For example, the command getavatarappearancedata has a plural form getavatarsappearancedata and a named plural form batchgetavatarappearancedata.

The distinction is made due to the way SecondLife offers various properties that have different kind of contexts leading to different ways of handling the command entirely.

In any case, plural forms for commands that return data (all commands with the data suffix) will return the data requested by the user and only the data requested by the user. For example, suppose that the following command is used to query the IsTrial property of two avatars using the plural form command batchgetavatarsappearancedata:

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "batchgetavatarsappearancedata",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "avatars", wasListToCSV([
                "Juno Resident",
                "Cat Resident"
            ]),
            "data", "IsTrial",
            "callback", wasURLEscape(URL)
        ]
    )
);

The result passed to the callback URL (or other external services if querying via HTTP, MQTT, etc.) will be a CSV list containing two booleans and it will be impossible to determine to which avatar (either Juno Resident or Cat Resident) a particular boolean in the list corresponds to:

IsTrial,false,IsTrial,true

In order to solve the issue, the AvatarAppearanceEventArgs structure contains an AgentID property which can be queried along with the IsTrial property:

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "batchgetavatarappearancedata",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "avatars", wasListToCSV([
                "Juno Resident",
                "Cat Resident"
            ]),
            "data", wasListToCSV([
                "AgentID",
                "IsTrial"
            ]),
            "callback", wasURLEscape(URL)
        ]
    )
);

The result will now be a CSV list of avatar UUIDs by booleans:

AvatarID,870b5fa9-0b32-491e-8848-465666ae1151,IsTrial,true,AvatarID,ee0af3af-9881-476b-9482-a8048f64b3f5,IsTrial,false

Furthermore, plural forms shall never mangle the order of the properties passed to the data parameter within a subgroup yet subgroup order may be mangled. In other words, the following two results are possible if the previous command were to be issued twice:

AvatarID,870b5fa9-0b32-491e-8848-465666ae1151,IsTrial,true,AvatarID,ee0af3af-9881-476b-9482-a8048f64b3f5,IsTrial,false

is equivalent to:

AvatarID,ee0af3af-9881-476b-9482-a8048f64b3f5,IsTrial,false,AvatarID,870b5fa9-0b32-491e-8848-465666ae1151,IsTrial,true

As you can observe, the avatar IDs and trial flags have been switched for both avatars however, the correct trial flag still corresponds to the correct avatar. In other words, the subgroups:

AvatarID,ee0af3af-9881-476b-9482-a8048f64b3f5,IsTrial,false

and:

AvatarID,870b5fa9-0b32-491e-8848-465666ae1151,IsTrial,true

are interchangeable.

If you are curious why, imagine a table where the columns / column headers are the properties that users supply to the data parameter and the rows of that table are the results. Since there is no way to transfer a 2-dimensional table, Corrade places the column name before each cell, followed by the cell and each row after the other in the same long string. Following the analogy, the order of the rows is not relevant but the contents of each cell in a row is since it corresponds to a column header name.

The following BNF grammar describes the syntax of a Corrade command:

command ::= [ prefix ] <body> [ suffix ]
prefix ::= "batch" | ""
body ::= ( <term> [ plural ] )+
suffix ::= "data" | ""
plural ::= "s" | ""

Additionally the following notes apply universally to all commands:

• Commands prefixed with batch denote a command that is a named plural of a command. Such commands take a list of specific items and perform an action or retrieve some information on or for the specified items.

• Commands ending in data are commands that query various properties of itmes. Such commands are expected to return a data key to the callback whose value represents the queried data or the command does not return a data key at all in which case no data was available for the queried property (or the property does not exist).

• Plurals might appear using the string "s". The string "s" may be placed within the body of a command and may appear multiple times. Many times, such a command represents the plural of a different command. For example a fictive command "banavatars" would be a plural form of a command "banavatar". Plurals using the string "s" are left-associative and pluralize the term that they are placed after. For example, a fictive command "getavatarsnamedata" would not be the same as "getavatarnamesdata" since "getavatarsnamedata" would be a command that queries multiple avatars whereas "getavatarnamesdata" would be a command that queries multiple names of an avatar.

A formation that contains two or more plurals but one and only one named plural is possible. For example, a fictive command "batchgetavatarsnamedata" could possibly be a command that would query the name of multiple avatars (plural avatars) within multiple parcels (named plural grouping).

Although pertaining more to Linden grid design rather than Corrade, the meaning of UUIDs change depending on the executed commands. Items on the grid have different UUIDs, some of which can be accessed using a standard viewer and others that cannot.

For example, all objects in inventory have an inventory UUID that can be used to reference the objects when using inventory Corrade commands or even when sending the object to someone via the give command. However, the same object does not even have an asset UUID because objects do not have asset UUIDs (compared to, say, textures or sounds that can be downloaded via the download command where an asset UUID is required). If the object were to be rezzed in-world, then the grid will generate a random UUID for the in-world object (and the grid does so every time the same object is rezzed such that the UUID changes) and commands like touch require the in-world UUID to be passed to its parameters.

So far, using the example above, we have collected three different contexts where UUID may appear:

• inventory UUIDs, pertaining to items inside an avatar inventory
• asset UUIDs, pertaining to assets that can be retrieved via the asset server,
• in-world object UUIDs, pertaining to objects that are rezzed in world

This list can now be shunted with avatar UUIDs, group UUIDs and others. Whenever a Corrade command is issued that takes (or can take) as parameter an UUID, it is important to ensure that the passed UUID matches the proper context. Doing otherwise, will not find the object that you are looking for, for example, attempting to de-rez an in-world object via its inventory UUID will fail because an in-world object is referred to by its in-world UUID. Commands should mention the type of UUID that is required on their corresponding API pages.

All commands that must reference an inventory item, typically via the item parameter, can be referred to by either by inventory UUID or by inventory path.

One of the problems with Linden protocols is that inventory items may carry the same name, which is something that filesystems usually do not support, which makes referring to an item by name ambiguous. To overcome this problem, Corrade allows paths to inventory items to be built by name or by UUID or a combination thereof.

As an example, consider the following tree:

   + My Inventory (UUID: 7c38c488-5440-46c2-9f14-d5e3fcd0cc16)
   |
   +- Textures (UUID: 56a54ebe-7d4d-4839-a618-42ee3b307717)
         +
         |
         +- Floors (UUID: b13b0890-fac6-4085-975c-c2f760b185e4)
         |    +
         |    |
         |    +- Deck (UUID: 3e51dd70-9cd8-4dcf-9465-58c7036e673d)
         |
         +- Floors (UUID: c590792b-a724-4bb6-9f0c-81b6e733fad5)
              +
              |
              +- Table (UUID: 6eaffc93-df2a-479b-836b-4778bb917619)

If we wanted to list Deck via the inventory command and supposing that we are currently in My Inventory which is the root, then supplying /My Inventory/Textures/Floors/Deck to the path parameter would be ambiguous since it is uncertain which Floors folder should be browsed. To get rid of the Linden ambiguity, Corrade allows specifying UUIDs in the paths such that we are able to correctly reference Deck by supplying: /My Inventory/Textures/b13b0890-fac6-4085-975c-c2f760b185e4/Deck to the path parameter. Note that it is also possible to specify any of the other path components as UUIDs rather than by names - yet, in this case, that is not necessary: when you supply a name in the path, you are making a weak reference, when you are supplying an UUID you are making a strong reference.

Items that contain a forward-slash that would clash with the forward-slash (/) representing a path component can be escaped using a backslash (\). For instance, suppose that you have a texture named:

// Awesome Texture //

and that you want to reference it - you would then write:

"path" , wasURLEscape("/My Inventory/Textures/\/\/ Awesome Texture \/\/");

Alternatively, you can just use the UUID instead of the name.

Corrade accepts some parameters that are considered to have a global scoping in that they apply to every command. The following is a list of global parameters that can be passed as part of certain sets of commands and with various effects on the command.

Parameter	Value	Context	Description
timeout	an integer (default 60000)	all commands	this parameter allows overriding the default Corrade timeout of for the called command
target	a string or UUID	commands acting on groups	this parameter allows referring to a different group whilst authenticating with a configured group