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. 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. :)

<To be continued shortly>