SL projects update 24 (3): New object return LSL capabilities

Update June 12th, 22:40 BST/14:40 SLT: The BlueSteel  / LeTigre deployment which includes these capabilities has been rolled back due to an issue whereby objects cannot be rezzed in BlueSteel / LeTigre parcels which disallow object entry (even if Create Objects is enabled) – BUG-2850. Both regions are now running the week 24 Magnum deployment.

In week 23, Kelly Linden announced new LSL capabilities for the scripted return of objects within a region / parcel.  In making the announcement, he indicated the capabilities would be available “some time in the future”, a comment which appears to have been a little overly cautious, as the new functionality received its first outing on the Main channel in the RC deployments to BlueSteel and Le Tigre on Wednesday June 12th.

The new object return functions are llReturnObjectsByOwner and llReturnObjectsByID, and are designed to be used to enable the automated return of specified linksets to their owners.

The object containing scripts using the functions can either be placed in the land, or worn as an attachment but will only work on land held by the object owner.

The primary aim of these functions is to make for easier clearing of private sandboxes and rental parcels in cases where previous users / tenants may have left objects behind on leaving (thus removing the onus on the land owner to locate and manually return items).  They are not intended as anti-griefing tools, nor are they a “replacement” for the parcel / region auto-return functions.

The Functions

The functions are defined within the BlueSteel and LeTigre release notes as follows:

• integer llReturnObjectsByID(list objects)
  • Requires new runtime permission PERMISSION_RETURN_OBJECTS
  • objects is a list of objects IDs to return to owner
    • If the script is owned by an estate owner or manager then any object in the region can be returned.
    • Otherwise the script can return any object over land owned by the owner of the script.
  • Throttled at max parcel land impact capacity region-wide per hour.
  • Returns the number of objects that were returned to their owners or an error code.
• integer llReturnObjectsByOwner(key owner, integer scope)
  • Requires new runtime permission PERMISSION_RETURN_OBJECTS
  • scope is:
    • OBJECT_RETURN_PARCEL to return all objects on the same parcel as the script which are owned by ‘owner’. The script must be owned by an estate manager or over a parcel owned by the owner of the script.
    • OBJECT_RETURN_PARCEL_OWNER to return all objects owned by ‘owner’ which are over parcels owned by the owner of the script.
    • OBJECT_RETURN_REGION to return all objects in the region owned by ‘owner’ – only works when the script is owned by the estate owner or an estate manager.
  • Parcel owner, estate owner and estate managers can not have their objects returned by this method.
  • Objects which are owned by the group the land is set to will not be returned by this method.
  • Throttled at max parcel land impact region-wide per hour.
  • Returns the number of objects that were returned to their owners or an error code.
• New error constants for llReturnObjectsByID and llReturnObjectsByOwner:
  • ERR_GENERIC = -1;
  • ERR_PARCEL_PERMISSIONS = -2;
  • ERR_MALFORMED_PARAMS = -3;
  • ERR_RUNTIME_PERMISSIONS = -4;
  • ERR_THROTTLED = -5;

Additional Notes and Q&A On Capabilities / Limitations

There are also some additional notes which go with the new functions:

• There are no cases where one of these new LSL calls would return an object that you could not manually return yourself
• The functions will only work on objects in the same region/parcel as the object containing the script using them. Objects which are returned are coalesced in the recipient’s inventory, rather than being returned as individual objects
• The functions work if and only if the user would have permission to return the object via the viewer, and it does not handle encroachment
• To prevent severely damaging accidents the mass returns by owner (llReturnObjectsByOwner) will not work for your own items, items owned by an estate owner or manager or items that are owned by the group the land is ‘set’ to
• llReturnObjectsByID will not return objects owned by the parcel owner
• In order to work on group-owned land the object containing the script using the functions must be deeded to the group by the group owner
• The return capabilities are throttled to a maximum hourly quota based on a parcel’s Land Capacity (under About Land > Object). So, if your Land Capacity is 500, then using these LSL functions you can return up to 500 linksets per hour
  • The throttle is there primarily to prevent a silent war between a rezzer and returner that could impact the back-end servers
  • Even with the throttling, it is anticipated that the functions should be able to return everything on your land within a region in one go, but not necessarily more than once an hour for large-scale returns.

Discussing the capabilities at the Simulator User Group meeting on Tuesday June 12th, Kelly faced an extensive Q&A session on the capabilities (primarily from Lucia Nightfire, although others also asked questions), which I’ve reproduced here for ease of reference:

Question: Can prims in limbo (SVC-7788) be returned by UUID (not on the prim owner’s list until selected, but still visible in the region and detectable by sensors)?

Kelly Linden:  I’m not sure. Those items are in limbo due to a bug that I don’t understand and have not investigated. I do not know how they will interact w/ these return functions.

Q: If an object with PERMISSION_RETURN_OBJECTS granted leaves the region, are permissions lost and/or is functionality bound to the region the perms were granted in?

KL: The permission acts as all other permissions do, I do not expect it to be lost on region cross. However in all cases it only works to return objects over the land of the object owner. So if you have land in region A and land in neighbour B, but you don’t want your object that you granted permissions to, to be able to return objects in neighbour B then don’t move your object there.

Q: Is the return limit specific to that script? or can you have multiple scripts out to go past the hourly limit?

KL: The throttles are per object owner.

Q: If a group owner grants object return perms and later leaves the group will their object still be able to return prims?

KL: Yes.

Q: Do returns executed for temp objects or no trans deeded objects impact the return allowance?

KL: Yes

Q: If prim return allowance is on a linkset basis, will there later be a function made available that gives land owners an idea of how many returns are available?

KL:There are no plans at this time for such a function. Once these functions are in use, if that is a necessary thing then it could be investigated. I do not anticipate many people to really run into the throttle.

Q: Is the prim return allowance reset on region start?

KL: Yes

Q: On group-owned land, the object must be group-deeded, but permissions granted by an Owner of the Group?

KL: The object can request permissions from a group owner when it is already owned by the group for this specific permission

Not for Griefing

It is important to understand that the new capabilities are not intended to combat persistent griefing attacks, a point Kelly has underlined several times. Rather then are intended to help with sandbox cleaning and automated rental property management.

While the functions may be useful for cleaning up a parcel / region after the source of griefing has been taken care of, but the throttles on the functions are liable to make them ineffective against any ongoing attack involving object rezzing, as the limits in the number of hourly returns are liable to be hit fairly quickly. As such, they should not be used in any attempt to combat a griefing attack.

Sample Script

Darien Caldwell has produced a script using the new capabilities for those wishing to test them, and has made it freely available to all. Note that at the time of writing, the script had not been thoroughly tested, and Darien cannot be held responsible for any errors or issues arising from its use.