LlCastRay

llCastRay

Introduction

I was trying to think of a witty and sarcastic way to start this page, but I'm tired and I want to go home, so this will have to do. :)

I've added a new LSL function to Oatmeal 9, 13, and 14 on our beta grid, Aditi. This is a very early prototype with no guarantee of shipping, etc., etc., disclaimers, warnings, may not apply in your state, terms and conditions may apply, etc. I've put it up in the hope that you (the SL scripting community) will take advantage of the long weekend (if you're in the United States...otherwise the regular-length weekend...unless it's one of those awesome Bank Holidays...oh, and I suppose France, too, has a day off...) to build some awesome stuff and help me understand your needs for the final llCastRay implementation. Without further ado, here is the API for llCastRay. Please be sure to read the NOTES section below it before you start working.

API

list llCastRay( vector start, vector end, integer filter, integer flags )
Return value: [UUID_1, {link_number_1}, hit_position_1, {hit_normal_1}, UUID_2, {link_number_1}, hit_position_2, {hit_normal_2}, ... , status_code] where {} indicates optional data.

Start and end are vectors specifying the start and end point of the ray. The ray must both start and end within the region where the script is located or a script runtime error will be generated. (So be sure to clamp your values!)

Filter is a bitwise-or combination of the following constants: RC_REJECT_AGENTS, RC_REJECT_PHYSICAL, RC_REJECT_NONPHYSICAL, and RC_REJECT_LAND except that if you select all 4 of them, a script runtime error will be generated (it makes no sense to cast a ray and reject everything!). Note that phantom and volume detect objects are never returned and that seated agents are treated like unseated agents. I.e., you either get seated and unseated agents in your results, or you use RC_REJECT_AGENTS and get neither. Using 0 as the filter value will return all hits.

Flags is a bitwise-or combination of: RC_GET_NORMAL, RC_GET_ROOT_KEY, and RC_GET_LINK_NUM. These select whether you want link numbers and hit normals in your results list. By default, you will get the UUID (i.e., 'key') of the exact child prim hit. If instead you want the key of the root prim, set RC_GET_ROOT_KEY. Oh, and also, a terrain hit will register as NULL_KEY.

Status_code is a number tacked onto the end of the strided list to give you extra information about the ray cast. If the cast succeeded, it will be >=0 and will indicate the number of hits. If the ray cast failed (which should only happen right now if the simulator performance is running low), you'll get a negative status code. RCERR_SIM_PERF_LOW will be used as the status code if the overall physics time in the simulator is too high to perform raycasts. The idea is that you will know to try your cast again in a few frames. When we finally release llCastRay, we will limit the total number of casts per linkset. To see if your cast failed because you've run out of casts this frame, you can check the status code and see if it is set to RCERR_MAX_CASTS_EXCEEDED.

Example Code

This is a very poor script that I wrote to test the ray casts. Use it as a starting point if you like.

<lsl> integer filter = 0;

default {

   state_entry()
   {
       llSay(0, "Hello, Avatar!");
   }

   touch_start(integer total_number)
   {
       vector start = llGetPos();
       vector end = start - <0,-25,0>;
       
       if ( filter > 8 )
       {
           filter = 0;
       }
       
       llOwnerSay("Filter " + (string)filter);

       list results = llCastRay(start, end, filter, 0);
       
       integer hitNum = 0;
       // Handle error conditions here by checking llList2Integer(results, -1) >= 0
       for ( hitNum = 0; hitNum < llList2Integer(results, -1); hitNum++ )
       {
           // Stride is 2 because we didn't request normals or link numbers
           key uuid = llList2Key(results, 2*hitNum);
           string name;
           if ( uuid == NULL_KEY )
           {
               name = "Land";
           }                
           else
           {
               name = llKey2Name(uuid);
           }
           llOwnerSay("Hit " + name);
       }
       
       filter += 1;
   }

} </lsl>

Notes

• Quick Tip #1: use llDumpList2String to see what the output looks like when you try a new set of flags
• Quick..no, not a quick tip. Only had one of those apparently. But I do have more notes.

1. Some notes on how this prototype might differ from the final version:
   • The final version may never ship (just being honest!)
   • The final version will have strict throttling. I'm currently thinking up to 4 calls to llCastRay per linkset per frame, and that will be subject to sim performance (but will probably require very, very poor performance before they start returned an error code rather than executing). Part of this early preview is to help me learn what reasonable throttles might be
   • The final version will not return ALL hits. It may only return the first hit. Or, if performance doesn't seem to be much of a problem, it might give you the option of selecting the first hit only or up to N hits for some max N.
   • Temp on rez objects will likely not be allowed to cast rays, possibly with the exception of allowing them to cast rays if they have an agent seated on them (to allow vehicles to use it but not bullets)

1. Please use discretion on these beta regions. The script calls are not currently throttled (much) and I will not be around every minute of the weekend if someone creates a griefer item and ruins it for everyone. But I will track down that person and make sure that I add a special check in the code that prevents him or her from ever using ray casts in their scripts. :)
2. Please provide lots of feedback, preferably on the discussion page in this wiki. That feedback, as well as the things you build in world, will help me determine appropriate throttles but will also help me offer more optimized versions of the script call for particular uses, if they turn out to be important. For example, if lots of people need to cast several rays at a time from the same start point, there's an optimized version I could make for that. E.g., llCastRay(vector start, list end_points, integer filter, integer flags);

Ideas

• Not that you folks need any ideas to get started, but here are a few:

1. Weapons. I'm personally praying that llCastRay will make simulated projectile weapons essentially obsolete in SL. They're horrible for performance. Ray casts FTW!
2. AI objects
3. Vehicles. Try simulating the wheels using raycasts. Not sure if LSL will be fast enough, but I'd love for someone to try and report back.
4. Lots of other stuff.